Mercurial > prosody-modules
view mod_http_admin_api/openapi.yaml @ 5610:67f7df9892bb
mod_muc_block_pm: Advertise that Moderators are allowed to send PMs
But there appears to be no way in XEP-0045 to advertise that Anyone can
send PMs *to* Moderators.
author | Kim Alvefur <zash@zash.se> |
---|---|
date | Wed, 19 Jul 2023 17:01:40 +0200 |
parents | f60287bba62c |
children | 2aa66e928aa0 |
line wrap: on
line source
openapi: 3.0.1 info: title: Prosody administration API description: Prosody administration API contact: email: developers@prosody.im license: name: MIT url: https://prosody.im/source/mit version: 1.0.0 servers: - url: /admin_api tags: - name: user description: Manage user accounts - name: invite description: Pending invitations - name: group description: User groups paths: /users: get: tags: - user summary: List users description: Returns an array of users. operationId: listUsers responses: 200: description: successful operation content: application/json: schema: $ref: '#/components/schemas/UserList' /users/{username}: get: tags: - user summary: Get user by user name operationId: getUserByName parameters: - name: username in: path description: The name that needs to be fetched required: true schema: type: string responses: 200: description: successful operation content: application/json: schema: $ref: '#/components/schemas/User' 400: description: Invalid username supplied content: {} 404: description: User not found content: {} put: tags: - user summary: Updated user description: Update a user operationId: updateUser parameters: - name: username in: path description: user that need to be updated required: true schema: type: string requestBody: description: Updated user object content: '*/*': schema: $ref: '#/components/schemas/User' required: true responses: 400: description: Invalid user supplied content: {} 404: description: User not found content: {} x-codegen-request-body-name: body delete: tags: - user summary: Delete user description: Delete a user account operationId: deleteUser parameters: - name: username in: path description: The name that needs to be deleted required: true schema: type: string responses: 400: description: Invalid username supplied content: {} 404: description: User not found content: {} /users/{username}/groups: get: tags: - user summary: List groups that user is a member of operationId: getUserGroups parameters: - name: username in: path description: The name of the user to fetch required: true schema: type: string responses: 200: description: Returns an array of group IDs that the user belongs to content: application/json: schema: type: array description: "An array of group IDs that the user belongs to" items: type: string description: "Group ID" 400: description: Invalid username supplied content: {} 404: description: User not found content: {} /users/{username}/debug: get: tags: - user summary: Get user debug info operationId: getUserDebugInfo parameters: - name: username in: path description: The name of the user to fetch required: true schema: type: string responses: 200: description: successful operation content: application/json: schema: $ref: '#/components/schemas/UserDebugInfo' 400: description: Invalid username supplied content: {} 404: description: User not found content: {} /invites: get: tags: - invite summary: List invites description: Returns an array of users. operationId: listInvites responses: 200: description: successful operation content: application/json: schema: $ref: '#/components/schemas/InviteList' /invites/account: post: tags: - invite summary: Create invitation to register a new account description: Creates a new invitation operationId: createInviteForAccount requestBody: description: "Invite parameters (optional)" required: false content: application/json: schema: $ref: "#/components/schemas/NewAccountInvite" responses: 200: description: successful operation content: application/json: schema: $ref: '#/components/schemas/Invite' /invites/group: post: tags: - invite summary: Create group invitation description: | Creates a new group invitation. Group invitations may be shared with multiple people and each account created via a group invitation will automatically be contacts of every other account created through the same invitation. You can create an invitation to an existing group by including the existing group's id in the 'group' property of the request. If no existing group is specified, a new one will be created automatically (using the 'group_options' property as a template if provided). If no 'ttl' is specified then the invitation link will be valid until it is manually revoked. operationId: createInviteForGroup requestBody: description: "Invite parameters (optional)" required: false content: application/json: schema: $ref: "#/components/schemas/NewGroupInvite" responses: 200: description: successful operation content: application/json: schema: $ref: '#/components/schemas/Invite' /invites/reset: post: tags: - invite summary: Create account reset invitation description: | Creates a new invitation to reset the specified account. The created link is valid for a shorter time period (24 hours) by default and should only be shared securely with the user who owns the account. The returned link will allow the user to regain access to their account, for example if they have lost their password. operationId: createInviteForAccountReset requestBody: description: "Invite parameters" required: true content: application/json: schema: $ref: "#/components/schemas/NewResetInvite" responses: 200: description: successful operation content: application/json: schema: $ref: '#/components/schemas/Invite' /invites/{id}: get: tags: - invite summary: Get invite by id operationId: getInviteById parameters: - name: id in: path description: The id of the invite to fetch required: true schema: type: string responses: 200: description: successful operation content: application/json: schema: $ref: '#/components/schemas/Invite' 404: description: Invite not found content: {} delete: tags: - invite summary: Delete invite description: Delete a pending invite operationId: deleteInvite parameters: - name: id in: path description: The id of the invite to be deleted required: true schema: type: string responses: 404: description: Invite not found content: {} /groups: get: tags: - group summary: List groups description: Returns an array of groups. operationId: listGroups responses: 200: description: successful operation content: application/json: schema: $ref: '#/components/schemas/GroupList' post: tags: - group summary: Create group description: Creates a new user group operationId: createGroup requestBody: description: "Group parameters" required: true content: application/json: schema: $ref: "#/components/schemas/NewGroup" responses: 200: description: successful operation content: application/json: schema: $ref: '#/components/schemas/Group' /groups/{id}: get: tags: - group summary: Get group by id operationId: getGroupById parameters: - name: id in: path description: The id of the group to fetch required: true schema: type: string responses: 200: description: successful operation content: application/json: schema: $ref: '#/components/schemas/Group' 404: description: Group not found content: {} delete: tags: - group summary: Delete group description: Delete a group (does not delete users or existing subscriptions) operationId: deleteGroup parameters: - name: id in: path description: The id of the group to be deleted required: true schema: type: string responses: 404: description: Group not found /groups/{id}/members/{username}: put: tags: - group summary: Create group membership operationId: addGroupMember parameters: - name: id in: path description: The id of the group to modify required: true schema: type: string - name: username in: path description: The username to add to the group required: true schema: type: string responses: 200: description: successful operation 404: description: Group not found delete: tags: - group summary: Delete a group membership operationId: deleteGroupMember parameters: - name: id in: path description: The id of the group to modify required: true schema: type: string - name: username in: path description: The username to remove from the group required: true schema: type: string responses: 200: description: successful operation 404: description: Group not found /server/info: get: tags: - server summary: Get information about the server operationId: getServerInfo responses: 200: description: successful operation content: application/json: schema: $ref: '#/components/schemas/ServerInfo' /server/metrics: get: tags: - server summary: Get metrics from the running server operationId: getServerMetrics responses: 200: description: successful operation content: application/json: schema: $ref: '#/components/schemas/ServerMetrics' /server/announcement: post: tags: - server summary: Post an announcement to some or all users operationId: postServerAnnouncement requestBody: description: Announcement parameters required: true content: application/json: schema: $ref: "#/components/schemas/Announcement" responses: 201: description: Announcement has been sent components: schemas: UserList: type: array items: $ref: '#/components/schemas/User' User: type: object properties: username: type: string description: XMPP username of the user display_name: type: string description: Display name of the user nullable: true role: type: string description: Primary role of the user nullable: true secondary_roles: type: array description: List of additional roles assigned to the user items: type: string roles: type: array description: List of roles assigned to the user (Legacy) deprecated: true items: type: string email: type: string description: Optional email address for the user (NYI) nullable: true phone: type: string description: Optional phone number for the user (NYI) nullable: true groups: type: array description: List of group IDs user is a member of items: type: string description: Group ID InviteList: type: array items: $ref: '#/components/schemas/Invite' Invite: type: object properties: id: type: string description: Unique ID of the invite type: type: string description: The type (action) of the invite (register, roster, etc.) reusable: type: boolean description: Whether the invite may be used more than once (until expiry or revocation) inviter: type: string description: (Optional) JID of the inviter nullable: true jid: type: string description: The JID of the invite, interpretation varies based by invite type token: type: string description: Invite token uri: type: string description: XMPP URI of the invite landing_page: type: string description: HTTPS URL of invite page (use in preference to XMPP URI when available) nullable: true created_at: type: integer description: Unix timestamp of invite creation expires: type: integer description: Unix timestamp of invite expiration groups: type: array description: Array of group IDs that an accepting user will be added to items: type: string description: Group ID source: type: string description: | String that identifies how and by whom the invite was created. Invites created by this API will have the source string 'admin_api/USERNAME', where USERNAME is the name of the user that requested creation of the invite. reset: type: boolean description: "Indicates that this is an account reset for the account identified by 'username'" NewAccountInvite: type: object properties: username: type: string description: Optionally restrict the registered account to the specified username nullable: true ttl: type: number description: The time in seconds that the invitation will be valid for (uses a sensible default if not provided). nullable: true groups: type: array nullable: true description: "IDs of existing groups to add the new account to" items: type: string description: "Group ID" NewGroupInvite: type: object properties: ttl: type: number description: Specify that the invitation will only be valid for the specified number of seconds. If not provided, the invitation will be valid until it is manually deleted. groups: type: array nullable: true items: type: string description: "Group ID" description: "IDs of existing group to add the new accounts to" group_options: $ref: '#/components/schemas/NewGroup' NewResetInvite: type: object properties: username: type: string description: "Username of the account to create a password reset link for" ttl: type: number description: Time in seconds that the link will be valid. Defaults to 24 hours. nullable: true NewGroup: type: object properties: name: type: string description: "Display name of the group" create_muc: type: boolean description: Create a MUC associated with the group Group: type: object properties: id: type: string description: id of the group name: type: string description: Display name of the group muc_jid: type: string nullable: true description: JID of the associated MUC, if any. GroupList: type: array items: $ref: '#/components/schemas/Group' UserDebugInfo: type: object properties: sessions: type: array items: $ref: '#/components/schemas/UserDebugSessionInfo' push_registrations: $ref: '#/components/schemas/UserDebugPushRegistrations' omemo: $ref: '#/components/schemas/UserDebugOmemo' UserDebugSessionInfo: type: object properties: full_jid: type: string description: "Full JID of the session" ip: type: string description: "IP address of the session, human-readable" nullable: true since: type: integer description: "Unix timestamp of session establishment" status: type: object properties: connected: type: boolean description: "Whether the session is connected" hibernating: type: boolean description: "Whether the session is waiting to be resumed" active: type: boolean description: "Whether the session is active (CSI)" nullable: true features: type: object properties: encrypted: type: boolean description: "Whether the session enabled transport encryption" carbons: type: boolean description: "Whether the session enabled carbons" acks: type: boolean description: "Whether the session enabled acknowledgements" resumption: type: boolean description: "Whether the session enabled resumption" mobile_optimization: type: boolean description: "Whether the session enabled mobile optimizations" push_notifications: type: boolean description: "Whether the session enabled push notifications" history: type: boolean description: "Whether the session requested history" queues: type: object properties: held_stanzas: type: integer description: "Number of stanzas held due to mobile optimizations" nullable: true awaiting_acks: type: integer description: "Number of stanzas awaiting acknowledgement" nullable: true push_info: type: object nullable: true properties: id: type: string description: "ID of the push registration used by this session" wakeup_push_sent: type: integer description: "Unix timestamp of the first wakeup push sent (if any)" nullable: true UserDebugPushRegistrations: type: object description: | Push registrations of the user. The key of the object is the registration identifier. If a session is using a push registration, this identifier is found in `session.push_info.id`. It is possible to have push registrations with no active sessions attached. properties: since: type: integer description: "Unix timestamp of creation of this registration" service: type: string description: "The JID of the push service that notifications will be sent to" node: type: string description: "The identifier/token that the remote push service assigned to this registration." error_count: type: number description: "A count of recent errors for this push registration (reset on successful push)." UserDebugOmemo: type: object description: "Information about user's published OMEMO devices and keys" properties: status: type: object description: "Status of the OMEMO device list" properties: valid: type: boolean description: "Indicates whether the overall OMEMO configuration appears to be valid (including all devices)" config_valid: type: boolean description: "Indicates whether configuration of the device list appears to be valid" devices: type: array items: type: object description: "OMEMO device descriptor" properties: id: type: integer description: "The integer OMEMO device id of this device. May be missing if invalid." nullable: true have_bundle: type: boolean description: "True when a matching descriptor (bundle) is found for this device." valid: type: boolean description: "Whether the bundle config appears to be valid." ServerInfo: type: object description: Information about the current server properties: site_name: type: string description: A friendly name for the service version: type: string description: A human-readable version string ServerMetrics: type: object description: A selection of instantaneous metrics of the prosody server properties: memory: type: integer description: RSS in bytes cpu: type: object description: CPU time counter required: - value - since properties: since: type: number description: The metric epoch as UNIX timestamp value: type: number description: Seconds of CPU time used since the metric epoch c2s: type: integer description: Number of active c2s sessions uploads: type: integer description: Disk space used by uploaded files Announcement: type: object description: An announcemen to post to users on the server required: - body - recipients properties: body: type: string description: The message body to send recipients: description: List of recipients or one of the strings "online" or "all"