basePath: / definitions: account: description: The modelled account can be either a remote account, or one on this instance. title: Account models a fediverse account. x-go-name: Account x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/model accountRelationship: title: Relationship represents a relationship between accounts. x-go-name: Relationship x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/model accountRole: title: AccountRole models the role of an account. x-go-name: AccountRole x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/model adminAccountInfo: title: AdminAccountInfo models the admin view of an account's details. x-go-name: AdminAccountInfo x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/model adminEmoji: title: AdminEmoji models the admin view of a custom emoji. x-go-name: AdminEmoji x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/model adminReport: title: AdminReport models the admin view of a report. x-go-name: AdminReport x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/model advancedVisibilityFlagsForm: description: |- AdvancedVisibilityFlagsForm allows a few more advanced flags to be set on new statuses, in addition to the standard mastodon-compatible ones. x-go-name: AdvancedVisibilityFlagsForm x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/model announcement: title: Announcement models an admin announcement for the instance. x-go-name: Announcement x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/model announcementReaction: title: AnnouncementReaction models a user reaction to an announcement. x-go-name: AnnouncementReaction x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/model application: title: Application models an api application. x-go-name: Application x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/model attachment: title: Attachment models a media attachment. x-go-name: Attachment x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/model card: title: Card represents a rich preview card that is generated using OpenGraph tags from a URL. x-go-name: Card x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/model domain: description: Domain represents a remote domain x-go-name: Domain x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/model domainBlock: description: DomainBlock represents a block on one domain x-go-name: DomainBlock x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/model domainBlockCreateRequest: title: DomainBlockCreateRequest is the form submitted as a POST to /api/v1/admin/domain_blocks to create a new block. x-go-name: DomainBlockCreateRequest x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/model emoji: title: Emoji represents a custom emoji. x-go-name: Emoji x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/model emojiCategory: title: EmojiCategory represents a custom emoji category. x-go-name: EmojiCategory x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/model emojiCreateRequest: title: EmojiCreateRequest represents a request to create a custom emoji made through the admin API. x-go-name: EmojiCreateRequest x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/model emojiUpdateRequest: title: EmojiUpdateRequest represents a request to update a custom emoji, made through the admin API. x-go-name: EmojiUpdateRequest x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/model field: title: Field represents a name/value pair to display on an account's profile. x-go-name: Field x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/model hostmeta: description: 'See: https://www.rfc-editor.org/rfc/rfc6415.html#section-3' title: HostMeta represents a hostmeta document. x-go-name: HostMeta x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/model instanceConfigurationAccounts: title: InstanceConfigurationAccounts models instance account config parameters. x-go-name: InstanceConfigurationAccounts x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/model instanceConfigurationMediaAttachments: title: InstanceConfigurationMediaAttachments models instance media attachment config parameters. x-go-name: InstanceConfigurationMediaAttachments x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/model instanceConfigurationPolls: title: InstanceConfigurationPolls models instance poll config parameters. x-go-name: InstanceConfigurationPolls x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/model instanceConfigurationStatuses: title: InstanceConfigurationStatuses models instance status config parameters. x-go-name: InstanceConfigurationStatuses x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/model instanceV1: title: InstanceV1 models information about this instance. x-go-name: InstanceV1 x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/model instanceV1Configuration: title: InstanceV1Configuration models instance configuration parameters. x-go-name: InstanceV1Configuration x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/model instanceV1URLs: title: InstanceV1URLs models instance-relevant URLs for client application consumption. x-go-name: InstanceV1URLs x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/model instanceV2: title: InstanceV2 models information about this instance. x-go-name: InstanceV2 x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/model instanceV2Configuration: title: Configured values and limits for this instance. x-go-name: InstanceV2Configuration x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/model instanceV2ConfigurationTranslation: title: Hints related to translation. x-go-name: InstanceV2ConfigurationTranslation x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/model instanceV2Contact: title: Hints related to contacting a representative of the instance. x-go-name: InstanceV2Contact x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/model instanceV2Registrations: title: Information about registering for this instance. x-go-name: InstanceV2Registrations x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/model instanceV2Thumbnail: title: An image used to represent this instance. x-go-name: InstanceV2Thumbnail x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/model instanceV2ThumbnailVersions: title: Links to scaled resolution images, for high DPI screens. x-go-name: InstanceV2ThumbnailVersions x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/model instanceV2URLs: title: InstanceV2URLs models instance-relevant URLs for client application consumption. x-go-name: InstanceV2URLs x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/model instanceV2Usage: title: Usage data for this instance. x-go-name: InstanceV2Usage x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/model instanceV2Users: title: Usage data related to users on this instance. x-go-name: InstanceV2Users x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/model mediaDimensions: title: MediaDimensions models detailed properties of a piece of media. x-go-name: MediaDimensions x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/model mediaFocus: title: MediaFocus models the focal point of a piece of media. x-go-name: MediaFocus x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/model mediaMeta: description: This can be metadata about an image, an audio file, video, etc. title: MediaMeta models media metadata. x-go-name: MediaMeta x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/model nodeinfo: description: 'See: https://nodeinfo.diaspora.software/schema.html' title: Nodeinfo represents a version 2.1 or version 2.0 nodeinfo schema. x-go-name: Nodeinfo x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/model notification: title: Notification represents a notification of an event relevant to the user. x-go-name: Notification x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/model oauthToken: title: Token represents an OAuth token used for authenticating with the GoToSocial API and performing actions. x-go-name: Token x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/model poll: title: Poll represents a poll attached to a status. x-go-name: Poll x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/model pollOptions: title: PollOptions represents the current vote counts for different poll options. x-go-name: PollOptions x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/model report: title: Report models a moderation report submitted to the instance, either via the client API or via the federated API. x-go-name: Report x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/model searchResult: title: SearchResult models a search result. x-go-name: SearchResult x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/model status: title: Status models a status or post. x-go-name: Status x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/model statusContext: title: Context models the tree around a given status. x-go-name: Context x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/model statusCreateRequest: title: StatusCreateRequest models status creation parameters. x-go-name: StatusCreateRequest x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/model statusReblogged: title: StatusReblogged represents a reblogged status. x-go-name: StatusReblogged x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/model swaggerCollection: title: SwaggerCollection represents an ActivityPub Collection. x-go-name: SwaggerCollection x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/activitypub/users swaggerCollectionPage: title: SwaggerCollectionPage represents one page of a collection. x-go-name: SwaggerCollectionPage x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/activitypub/users swaggerFeaturedCollection: title: SwaggerFeaturedCollection represents an ActivityPub OrderedCollection. x-go-name: SwaggerFeaturedCollection x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/activitypub/users tag: title: Tag represents a hashtag used within the content of a status. x-go-name: Tag x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/model updateField: description: By default, max 6 fields and 255 characters per property/value. title: UpdateField is to be used specifically in an UpdateCredentialsRequest. x-go-name: UpdateField x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/model updateSource: title: UpdateSource is to be used specifically in an UpdateCredentialsRequest. x-go-name: UpdateSource x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/model wellKnownResponse: description: See https://webfinger.net/ title: |- WellKnownResponse represents the response to either a webfinger request for an 'acct' resource, or a request to nodeinfo. For example, it would be returned from https://example.org/.well-known/webfinger?resource=acct:some_username@example.org x-go-name: WellKnownResponse x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/model host: example.org info: contact: email: admin@gotosocial.org name: GoToSocial Authors license: name: AGPL3 url: https://www.gnu.org/licenses/agpl-3.0.en.html title: GoToSocial Swagger documentation. version: 0.9.1 paths: /.well-known/host-meta: get: description: 'See: https://www.rfc-editor.org/rfc/rfc6415.html' operationId: hostMetaGet produces: - application/xrd+xml" responses: "200": description: "" schema: $ref: '#/definitions/hostmeta' summary: Returns a compliant hostmeta response to web host metadata queries. tags: - .well-known /.well-known/nodeinfo: get: description: |- eg. `{"links":[{"rel":"http://nodeinfo.diaspora.software/ns/schema/2.0","href":"http://example.org/nodeinfo/2.0"}]}` See: https://nodeinfo.diaspora.software/protocol.html operationId: nodeInfoWellKnownGet produces: - application/json responses: "200": description: "" schema: $ref: '#/definitions/wellKnownResponse' summary: Returns a well-known response which redirects callers to `/nodeinfo/2.0`. tags: - .well-known /.well-known/webfinger: get: description: |- For example, a GET to `https://goblin.technology/.well-known/webfinger?resource=acct:tobi@goblin.technology` would return: ``` {"subject":"acct:tobi@goblin.technology","aliases":["https://goblin.technology/users/tobi","https://goblin.technology/@tobi"],"links":[{"rel":"http://webfinger.net/rel/profile-page","type":"text/html","href":"https://goblin.technology/@tobi"},{"rel":"self","type":"application/activity+json","href":"https://goblin.technology/users/tobi"}]} ``` See: https://webfinger.net/ operationId: webfingerGet produces: - application/jrd+json responses: "200": description: "" schema: $ref: '#/definitions/wellKnownResponse' summary: Handles webfinger account lookup requests. tags: - .well-known /api/{api_version}/media: post: consumes: - multipart/form-data operationId: mediaCreate parameters: - description: Version of the API to use. Must be either `v1` or `v2`. in: path name: api_version required: true type: string - description: Image or media description to use as alt-text on the attachment. This is very useful for users of screenreaders! May or may not be required, depending on your instance settings. in: formData name: description type: string - default: 0,0 description: 'Focus of the media file. If present, it should be in the form of two comma-separated floats between -1 and 1. For example: `-0.5,0.25`.' in: formData name: focus type: string - description: The media attachment to upload. in: formData name: file required: true type: file produces: - application/json responses: "200": description: The newly-created media attachment. schema: $ref: '#/definitions/attachment' "400": description: bad request "401": description: unauthorized "422": description: unprocessable "500": description: internal server error security: - OAuth2 Bearer: - write:media summary: Upload a new media attachment. tags: - media /api/v1/accounts: post: consumes: - application/json - application/xml - application/x-www-form-urlencoded description: |- The parameters can also be given in the body of the request, as JSON, if the content-type is set to 'application/json'. The parameters can also be given in the body of the request, as XML, if the content-type is set to 'application/xml'. operationId: accountCreate parameters: - description: Text that will be reviewed by moderators if registrations require manual approval. in: query name: reason type: string x-go-name: Reason - description: The desired username for the account. in: query name: username type: string x-go-name: Username - description: The email address to be used for login. in: query name: email type: string x-go-name: Email - description: The password to be used for login. This will be hashed before storage. in: query name: password type: string x-go-name: Password - description: The user agrees to the terms, conditions, and policies of the instance. in: query name: agreement type: boolean x-go-name: Agreement - description: The language of the confirmation email that will be sent. in: query name: locale type: string x-go-name: Locale produces: - application/json responses: "200": description: An OAuth2 access token for the newly-created account. schema: $ref: '#/definitions/oauthToken' "400": description: bad request "401": description: unauthorized "404": description: not found "406": description: not acceptable "500": description: internal server error security: - OAuth2 Application: - write:accounts summary: Create a new account using an application token. tags: - accounts /api/v1/accounts/{id}: get: operationId: accountGet parameters: - description: The id of the requested account. in: path name: id required: true type: string produces: - application/json responses: "200": description: The requested account. schema: $ref: '#/definitions/account' "400": description: bad request "401": description: unauthorized "404": description: not found "406": description: not acceptable "500": description: internal server error security: - OAuth2 Bearer: - read:accounts summary: Get information about an account with the given ID. tags: - accounts /api/v1/accounts/{id}/block: post: operationId: accountBlock parameters: - description: The id of the account to block. in: path name: id required: true type: string produces: - application/json responses: "200": description: Your relationship to the account. schema: $ref: '#/definitions/accountRelationship' "400": description: bad request "401": description: unauthorized "404": description: not found "406": description: not acceptable "500": description: internal server error security: - OAuth2 Bearer: - write:blocks summary: Block account with id. tags: - accounts /api/v1/accounts/{id}/follow: post: consumes: - application/json - application/xml - application/x-www-form-urlencoded description: |- The parameters can also be given in the body of the request, as JSON, if the content-type is set to 'application/json'. The parameters can also be given in the body of the request, as XML, if the content-type is set to 'application/xml'. If you already follow (request) the given account, then the follow (request) will be updated instead using the `reblogs` and `notify` parameters. operationId: accountFollow parameters: - description: ID of the account to follow. in: path name: id required: true type: string - default: true description: Show reblogs from this account. in: formData name: reblogs type: boolean - default: false description: Notify when this account posts. in: formData name: notify type: boolean produces: - application/json responses: "200": description: Your relationship to this account. schema: $ref: '#/definitions/accountRelationship' "400": description: bad request "401": description: unauthorized "404": description: not found "406": description: not acceptable "500": description: internal server error security: - OAuth2 Bearer: - write:follows summary: Follow account with id. tags: - accounts /api/v1/accounts/{id}/followers: get: operationId: accountFollowers parameters: - description: Account ID. in: path name: id required: true type: string produces: - application/json responses: "200": description: Array of accounts that follow this account. schema: items: $ref: '#/definitions/account' type: array "400": description: bad request "401": description: unauthorized "404": description: not found "406": description: not acceptable "500": description: internal server error security: - OAuth2 Bearer: - read:accounts summary: See followers of account with given id. tags: - accounts /api/v1/accounts/{id}/following: get: operationId: accountFollowing parameters: - description: Account ID. in: path name: id required: true type: string produces: - application/json responses: "200": description: Array of accounts that are followed by this account. "400": description: bad request "401": description: unauthorized "404": description: not found "406": description: not acceptable "500": description: internal server error security: - OAuth2 Bearer: - read:accounts summary: See accounts followed by given account id. tags: - accounts /api/v1/accounts/{id}/statuses: get: description: The statuses will be returned in descending chronological order (newest first), with sequential IDs (bigger = newer). operationId: accountStatuses parameters: - description: Account ID. in: path name: id required: true type: string - default: 30 description: Number of statuses to return. in: query name: limit type: integer - default: false description: Exclude statuses that are a reply to another status. in: query name: exclude_replies type: boolean - default: false description: Exclude statuses that are a reblog/boost of another status. in: query name: exclude_reblogs type: boolean - description: Return only statuses *OLDER* than the given max status ID. The status with the specified ID will not be included in the response. in: query name: max_id type: string - description: Return only statuses *NEWER* than the given min status ID. The status with the specified ID will not be included in the response. in: query name: min_id type: string - default: false description: Show only pinned statuses. In other words, exclude statuses that are not pinned to the given account ID. in: query name: pinned_only type: boolean - default: false description: Show only statuses with media attachments. in: query name: only_media type: boolean - default: false description: Show only statuses with a privacy setting of 'public'. in: query name: only_public type: boolean produces: - application/json responses: "200": description: Array of statuses. schema: items: $ref: '#/definitions/status' type: array "400": description: bad request "401": description: unauthorized "404": description: not found "406": description: not acceptable "500": description: internal server error security: - OAuth2 Bearer: - read:accounts summary: See statuses posted by the requested account. tags: - accounts /api/v1/accounts/{id}/unblock: post: operationId: accountUnblock parameters: - description: The id of the account to unblock. in: path name: id required: true type: string produces: - application/json responses: "200": description: Your relationship to this account. schema: $ref: '#/definitions/accountRelationship' "400": description: bad request "401": description: unauthorized "404": description: not found "406": description: not acceptable "500": description: internal server error security: - OAuth2 Bearer: - write:blocks summary: Unblock account with ID. tags: - accounts /api/v1/accounts/{id}/unfollow: post: operationId: accountUnfollow parameters: - description: The id of the account to unfollow. in: path name: id required: true type: string produces: - application/json responses: "200": description: Your relationship to this account. schema: $ref: '#/definitions/accountRelationship' "400": description: bad request "401": description: unauthorized "404": description: not found "406": description: not acceptable "500": description: internal server error security: - OAuth2 Bearer: - write:follows summary: Unfollow account with id. tags: - accounts /api/v1/accounts/delete: post: consumes: - multipart/form-data operationId: accountDelete parameters: - description: Password of the account user, for confirmation. in: formData name: password required: true type: string responses: "202": description: The account deletion has been accepted and the account will be deleted. "400": description: bad request "401": description: unauthorized "404": description: not found "406": description: not acceptable "500": description: internal server error security: - OAuth2 Bearer: - write:accounts summary: Delete your account. tags: - accounts /api/v1/accounts/relationships: get: operationId: accountRelationships parameters: - description: Account IDs. in: query items: type: string name: id required: true type: array produces: - application/json responses: "200": description: Array of account relationships. schema: items: $ref: '#/definitions/accountRelationship' type: array "400": description: bad request "401": description: unauthorized "404": description: not found "406": description: not acceptable "500": description: internal server error security: - OAuth2 Bearer: - read:accounts summary: See your account's relationships with the given account IDs. tags: - accounts /api/v1/accounts/update_credentials: patch: consumes: - multipart/form-data - application/json operationId: accountUpdate parameters: - description: Account should be made discoverable and shown in the profile directory (if enabled). in: formData name: discoverable type: boolean - description: Account is flagged as a bot. in: formData name: bot type: boolean - allowEmptyValue: true description: The display name to use for the account. in: formData name: display_name type: string - allowEmptyValue: true description: Bio/description of this account. in: formData name: note type: string - description: Avatar of the user. in: formData name: avatar type: file - description: Header of the user. in: formData name: header type: file - description: Require manual approval of follow requests. in: formData name: locked type: boolean - description: Default post privacy for authored statuses. in: formData name: source[privacy] type: string - description: Mark authored statuses as sensitive by default. in: formData name: source[sensitive] type: boolean - description: Default language to use for authored statuses (ISO 6391). in: formData name: source[language] type: string - description: Default content type to use for authored statuses (text/plain or text/markdown). in: formData name: source[status_content_type] type: string - description: Custom CSS to use when rendering this account's profile or statuses. String must be no more than 5,000 characters (~5kb). in: formData name: custom_css type: string - description: Enable RSS feed for this account's Public posts at `/[username]/feed.rss` in: formData name: enable_rss type: boolean - description: Profile fields to be added to this account's profile in: formData items: type: object name: fields_attributes type: array produces: - application/json responses: "200": description: The newly updated account. schema: $ref: '#/definitions/account' "400": description: bad request "401": description: unauthorized "404": description: not found "406": description: not acceptable "500": description: internal server error security: - OAuth2 Bearer: - write:accounts summary: Update your account. tags: - accounts /api/v1/accounts/verify_credentials: get: operationId: accountVerify produces: - application/json responses: "200": description: "" schema: $ref: '#/definitions/account' "400": description: bad request "401": description: unauthorized "404": description: not found "406": description: not acceptable "500": description: internal server error security: - OAuth2 Bearer: - read:accounts summary: Verify a token by returning account details pertaining to it. tags: - accounts /api/v1/admin/accounts/{id}/action: post: consumes: - multipart/form-data operationId: adminAccountAction parameters: - description: ID of the account. in: path name: id required: true type: string - description: Type of action to be taken, currently only supports `suspend`. in: formData name: type required: true type: string - description: Optional text describing why this action was taken. in: formData name: text type: string produces: - application/json responses: "200": description: OK "400": description: bad request "401": description: unauthorized "403": description: forbidden "404": description: not found "406": description: not acceptable "500": description: internal server error security: - OAuth2 Bearer: - admin summary: Perform an admin action on an account. tags: - admin /api/v1/admin/custom_emojis: get: description: |- The next and previous queries can be parsed from the returned Link header. Example: `; rel="next", ; rel="prev"` operationId: emojisGet parameters: - default: domain:all description: |- Comma-separated list of filters to apply to results. Recognized filters are: `domain:[domain]` -- show emojis from the given domain, eg `?filter=domain:example.org` will show emojis from `example.org` only. Instead of giving a specific domain, you can also give either one of the key words `local` or `all` to show either local emojis only (`domain:local`) or show all emojis from all domains (`domain:all`). Note: `domain:*` is equivalent to `domain:all` (including local). If no domain filter is provided, `domain:all` will be assumed. `disabled` -- include emojis that have been disabled. `enabled` -- include emojis that are enabled. `shortcode:[shortcode]` -- show only emojis with the given shortcode, eg `?filter=shortcode:blob_cat_uwu` will show only emojis with the shortcode `blob_cat_uwu` (case sensitive). If neither `disabled` or `enabled` are provided, both disabled and enabled emojis will be shown. If no filter query string is provided, the default `domain:all` will be used, which will show all emojis from all domains. in: query name: filter type: string - default: 50 description: Number of emojis to return. Less than 1, or not set, means unlimited (all emojis). in: query name: limit type: integer - description: |- Return only emojis with `[shortcode]@[domain]` *LOWER* (alphabetically) than given `[shortcode]@[domain]`. For example, if `max_shortcode_domain=beep@example.org`, then returned values might include emojis with `[shortcode]@[domain]`s like `car@example.org`, `debian@aaa.com`, `test@` (local emoji), etc. Emoji with the given `[shortcode]@[domain]` will not be included in the result set. in: query name: max_shortcode_domain type: string - description: |- Return only emojis with `[shortcode]@[domain]` *HIGHER* (alphabetically) than given `[shortcode]@[domain]`. For example, if `max_shortcode_domain=beep@example.org`, then returned values might include emojis with `[shortcode]@[domain]`s like `arse@test.com`, `0101_binary@hackers.net`, `bee@` (local emoji), etc. Emoji with the given `[shortcode]@[domain]` will not be included in the result set. in: query name: min_shortcode_domain type: string produces: - application/json responses: "200": description: An array of emojis, arranged alphabetically by shortcode and domain. headers: Link: description: Links to the next and previous queries. type: string schema: items: $ref: '#/definitions/adminEmoji' type: array "400": description: bad request "401": description: unauthorized "403": description: forbidden "404": description: not found "406": description: not acceptable "500": description: internal server error summary: View local and remote emojis available to / known by this instance. tags: - admin post: consumes: - multipart/form-data operationId: emojiCreate parameters: - description: The code to use for the emoji, which will be used by instance denizens to select it. This must be unique on the instance. in: formData name: shortcode pattern: \w{2,30} required: true type: string - description: A png or gif image of the emoji. Animated pngs work too! To ensure compatibility with other fedi implementations, emoji size limit is 50kb by default. in: formData name: image required: true type: file - description: Category in which to place the new emoji. 64 characters or less. If left blank, emoji will be uncategorized. If a category with the given name doesn't exist yet, it will be created. in: formData name: category type: string produces: - application/json responses: "200": description: The newly-created emoji. schema: $ref: '#/definitions/emoji' "400": description: bad request "401": description: unauthorized "403": description: forbidden "404": description: not found "406": description: not acceptable "409": description: conflict -- shortcode for this emoji is already in use "500": description: internal server error security: - OAuth2 Bearer: - admin summary: Upload and create a new instance emoji. tags: - admin /api/v1/admin/custom_emojis/{id}: delete: description: |- Emoji with the given ID will no longer be available to use on the instance. If you just want to update the emoji image instead, use the `/api/v1/admin/custom_emojis/{id}` PATCH route. To disable emojis from **remote** instances, use the `/api/v1/admin/custom_emojis/{id}` PATCH route. operationId: emojiDelete parameters: - description: The id of the emoji. in: path name: id required: true type: string produces: - application/json responses: "200": description: The deleted emoji will be returned to the caller in case further processing is necessary. schema: $ref: '#/definitions/adminEmoji' "400": description: bad request "401": description: unauthorized "403": description: forbidden "404": description: not found "406": description: not acceptable "500": description: internal server error security: - OAuth2 Bearer: - admin summary: Delete a **local** emoji with the given ID from the instance. tags: - admin get: operationId: emojiGet parameters: - description: The id of the emoji. in: path name: id required: true type: string produces: - application/json responses: "200": description: A single emoji. schema: $ref: '#/definitions/adminEmoji' "400": description: bad request "401": description: unauthorized "403": description: forbidden "404": description: not found "406": description: not acceptable "500": description: internal server error summary: Get the admin view of a single emoji. tags: - admin patch: consumes: - multipart/form-data description: |- Action performed depends upon the action `type` provided. `disable`: disable a REMOTE emoji from being used/displayed on this instance. Does not work for local emojis. `copy`: copy a REMOTE emoji to this instance. When doing this action, a shortcode MUST be provided, and it must be unique among emojis already present on this instance. A category MAY be provided, and the copied emoji will then be put into the provided category. `modify`: modify a LOCAL emoji. You can provide a new image for the emoji and/or update the category. Local emojis cannot be deleted using this endpoint. To delete a local emoji, check DELETE /api/v1/admin/custom_emojis/{id} instead. operationId: emojiUpdate parameters: - description: The id of the emoji. in: path name: id required: true type: string - description: |- Type of action to be taken. One of: (`disable`, `copy`, `modify`). For REMOTE emojis, `copy` or `disable` are supported. For LOCAL emojis, only `modify` is supported. in: formData name: type required: true type: string - description: The code to use for the emoji, which will be used by instance denizens to select it. This must be unique on the instance. Works for the `copy` action type only. in: formData name: shortcode pattern: \w{2,30} type: string - description: A new png or gif image to use for the emoji. Animated pngs work too! To ensure compatibility with other fedi implementations, emoji size limit is 50kb by default. Works for LOCAL emojis only. in: formData name: image type: file - description: Category in which to place the emoji. 64 characters or less. If a category with the given name doesn't exist yet, it will be created. in: formData name: category type: string produces: - application/json responses: "200": description: The updated emoji. schema: $ref: '#/definitions/adminEmoji' "400": description: bad request "401": description: unauthorized "403": description: forbidden "404": description: not found "406": description: not acceptable "500": description: internal server error security: - OAuth2 Bearer: - admin summary: Perform admin action on a local or remote emoji known to this instance. tags: - admin /api/v1/admin/custom_emojis/categories: get: operationId: emojiCategoriesGet parameters: - description: The id of the emoji. in: path name: id required: true type: string produces: - application/json responses: "200": description: Array of existing emoji categories. schema: items: $ref: '#/definitions/adminEmojiCategory' type: array "400": description: bad request "401": description: unauthorized "403": description: forbidden "404": description: not found "406": description: not acceptable "500": description: internal server error summary: Get a list of existing emoji categories. tags: - admin /api/v1/admin/domain_blocks: get: operationId: domainBlocksGet parameters: - description: If set to `true`, then each entry in the returned list of domain blocks will only consist of the fields `domain` and `public_comment`. This is perfect for when you want to save and share a list of all the domains you have blocked on your instance, so that someone else can easily import them, but you don't want them to see the database IDs of your blocks, or private comments etc. in: query name: export type: boolean produces: - application/json responses: "200": description: All domain blocks currently in place. schema: items: $ref: '#/definitions/domainBlock' type: array "400": description: bad request "401": description: unauthorized "403": description: forbidden "404": description: not found "406": description: not acceptable "500": description: internal server error security: - OAuth2 Bearer: - admin summary: View all domain blocks currently in place. tags: - admin post: consumes: - multipart/form-data description: |- You have two options when using this endpoint: either you can set `import` to `true` and upload a file containing multiple domain blocks, JSON-formatted, or you can leave import as `false`, and just add one domain block. The format of the json file should be something like: `[{"domain":"example.org"},{"domain":"whatever.com","public_comment":"they smell"}]` operationId: domainBlockCreate parameters: - default: false description: Signal that a list of domain blocks is being imported as a file. If set to `true`, then 'domains' must be present as a JSON-formatted file. If set to `false`, then `domains` will be ignored, and `domain` must be present. in: query name: import type: boolean - description: JSON-formatted list of domain blocks to import. This is only used if `import` is set to `true`. in: formData name: domains type: file - description: Single domain to block. Used only if `import` is not `true`. in: formData name: domain type: string - description: Obfuscate the name of the domain when serving it publicly. Eg., `example.org` becomes something like `ex***e.org`. Used only if `import` is not `true`. in: formData name: obfuscate type: boolean - description: Public comment about this domain block. This will be displayed alongside the domain block if you choose to share blocks. Used only if `import` is not `true`. in: formData name: public_comment type: string - description: Private comment about this domain block. Will only be shown to other admins, so this is a useful way of internally keeping track of why a certain domain ended up blocked. Used only if `import` is not `true`. in: formData name: private_comment type: string produces: - application/json responses: "200": description: The newly created domain block, if `import` != `true`. If a list has been imported, then an `array` of newly created domain blocks will be returned instead. schema: $ref: '#/definitions/domainBlock' "400": description: bad request "401": description: unauthorized "403": description: forbidden "404": description: not found "406": description: not acceptable "500": description: internal server error security: - OAuth2 Bearer: - admin summary: Create one or more domain blocks, from a string or a file. tags: - admin /api/v1/admin/domain_blocks/{id}: delete: operationId: domainBlockDelete parameters: - description: The id of the domain block. in: path name: id required: true type: string produces: - application/json responses: "200": description: The domain block that was just deleted. schema: $ref: '#/definitions/domainBlock' "400": description: bad request "401": description: unauthorized "403": description: forbidden "404": description: not found "406": description: not acceptable "500": description: internal server error security: - OAuth2 Bearer: - admin summary: Delete domain block with the given ID. tags: - admin get: operationId: domainBlockGet parameters: - description: The id of the domain block. in: path name: id required: true type: string produces: - application/json responses: "200": description: The requested domain block. schema: $ref: '#/definitions/domainBlock' "400": description: bad request "401": description: unauthorized "403": description: forbidden "404": description: not found "406": description: not acceptable "500": description: internal server error security: - OAuth2 Bearer: - admin summary: View domain block with the given ID. tags: - admin /api/v1/admin/email/test: post: consumes: - multipart/form-data description: |- This can be used to validate an instance's SMTP configuration, and to debug any potential issues. If an error is returned by the SMTP connection, this handler will return code 422 to indicate that the request could not be processed, and the SMTP error will be returned to the caller. operationId: testEmailSend parameters: - description: The email address that the test email should be sent to. in: formData name: email type: string produces: - application/json responses: "202": description: Test email was sent. "400": description: bad request "401": description: unauthorized "403": description: forbidden "404": description: not found "406": description: not acceptable "422": description: An smtp occurred while the email attempt was in progress. Check the returned json for more information. The smtp error will be included, to help you debug communication with the smtp server. "500": description: internal server error security: - OAuth2 Bearer: - admin summary: Send a generic test email to a specified email address. tags: - admin /api/v1/admin/media_cleanup: post: consumes: - application/json - application/xml - application/x-www-form-urlencoded description: Also cleans up unused headers + avatars from the media cache and prunes orphaned items from storage. operationId: mediaCleanup parameters: - description: |- Number of days of remote media to keep. Native values will be treated as 0. If value is not specified, the value of media-remote-cache-days in the server config will be used. format: int64 in: query name: remote_cache_days type: integer x-go-name: RemoteCacheDays produces: - application/json responses: "200": description: Echos the number of days requested. The cleanup is performed asynchronously after the request completes. "400": description: bad request "401": description: unauthorized "403": description: forbidden "404": description: not found "406": description: not acceptable "500": description: internal server error security: - OAuth2 Bearer: - admin summary: Clean up remote media older than the specified number of days. tags: - admin /api/v1/admin/media_refetch: post: description: |- Currently, this only includes remote emojis. This endpoint is useful when data loss has occurred, and you want to try to recover to a working state. operationId: mediaRefetch parameters: - description: Domain to refetch media from. If empty, all domains will be refetched. in: query name: domain type: string produces: - application/json responses: "202": description: Request accepted and will be processed. Check the logs for progress / errors. "400": description: bad request "401": description: unauthorized "403": description: forbidden "404": description: not found "406": description: not acceptable "500": description: internal server error security: - OAuth2 Bearer: - admin summary: Refetch media specified in the database but missing from storage. tags: - admin /api/v1/admin/reports: get: description: |- The reports will be returned in descending chronological order (newest first), with sequential IDs (bigger = newer). The next and previous queries can be parsed from the returned Link header. Example: ``` ; rel="next", ; rel="prev" ```` operationId: adminReports parameters: - description: If set to true, only resolved reports will be returned. If false, only unresolved reports will be returned. If unset, reports will not be filtered on their resolved status. in: query name: resolved type: boolean - description: Return only reports created by the given account id. in: query name: account_id type: string - description: Return only reports that target the given account id. in: query name: target_account_id type: string - description: Return only reports *OLDER* than the given max ID. The report with the specified ID will not be included in the response. in: query name: max_id type: string - description: Return only reports *NEWER* than the given since ID. The report with the specified ID will not be included in the response. This parameter is functionally equivalent to min_id. in: query name: since_id type: string - description: Return only reports *NEWER* than the given min ID. The report with the specified ID will not be included in the response. This parameter is functionally equivalent to since_id. in: query name: min_id type: string - default: 20 description: Number of reports to return. If more than 100 or less than 1, will be clamped to 100. in: query name: limit type: integer produces: - application/json responses: "200": description: Array of reports. schema: items: $ref: '#/definitions/adminReport' type: array "400": description: bad request "401": description: unauthorized "404": description: not found "406": description: not acceptable "500": description: internal server error security: - OAuth2 Bearer: - admin summary: View user moderation reports. tags: - admin /api/v1/admin/reports/{id}: get: operationId: adminReportGet parameters: - description: The id of the report. in: path name: id required: true type: string produces: - application/json responses: "200": description: The requested report. schema: $ref: '#/definitions/adminReport' "400": description: bad request "401": description: unauthorized "404": description: not found "406": description: not acceptable "500": description: internal server error security: - OAuth2 Bearer: - admin summary: View user moderation report with the given id. tags: - admin /api/v1/admin/reports/{id}/resolve: post: consumes: - application/json - application/xml - multipart/form-data operationId: adminReportResolve parameters: - description: The id of the report. in: path name: id required: true type: string - description: Optional admin comment on the action taken in response to this report. Useful for providing an explanation about what action was taken (if any) before the report was marked as resolved. This will be visible to the user that created the report! example: The reported account was suspended. in: formData name: action_taken_comment type: string produces: - application/json responses: "200": description: The resolved report. schema: $ref: '#/definitions/adminReport' "400": description: bad request "401": description: unauthorized "404": description: not found "406": description: not acceptable "500": description: internal server error security: - OAuth2 Bearer: - admin summary: Mark a report as resolved. tags: - admin /api/v1/apps: post: consumes: - application/json - application/xml - application/x-www-form-urlencoded description: |- The registered application can be used to obtain an application token. This can then be used to register a new account, or (through user auth) obtain an access token. The parameters can also be given in the body of the request, as JSON, if the content-type is set to 'application/json'. The parameters can also be given in the body of the request, as XML, if the content-type is set to 'application/xml'. operationId: appCreate parameters: - description: The name of the application. in: formData name: client_name required: true type: string x-go-name: ClientName - description: |- Where the user should be redirected after authorization. To display the authorization code to the user instead of redirecting to a web page, use `urn:ietf:wg:oauth:2.0:oob` in this parameter. in: formData name: redirect_uris required: true type: string x-go-name: RedirectURIs - description: |- Space separated list of scopes. If no scopes are provided, defaults to `read`. in: formData name: scopes type: string x-go-name: Scopes - description: A URL to the web page of the app (optional). in: formData name: website type: string x-go-name: Website produces: - application/json responses: "200": description: The newly-created application. schema: $ref: '#/definitions/application' "400": description: bad request "401": description: unauthorized "403": description: forbidden "404": description: not found "406": description: not acceptable "500": description: internal server error summary: Register a new application on this instance. tags: - apps /api/v1/blocks: get: description: |- The next and previous queries can be parsed from the returned Link header. Example: ``` ; rel="next", ; rel="prev" ```` operationId: blocksGet parameters: - default: 20 description: Number of blocks to return. in: query name: limit type: integer - description: Return only blocks *OLDER* than the given block ID. The block with the specified ID will not be included in the response. in: query name: max_id type: string - description: Return only blocks *NEWER* than the given block ID. The block with the specified ID will not be included in the response. in: query name: since_id type: string produces: - application/json responses: "200": description: "" headers: Link: description: Links to the next and previous queries. type: string schema: items: $ref: '#/definitions/account' type: array "400": description: bad request "401": description: unauthorized "404": description: not found "406": description: not acceptable "500": description: internal server error security: - OAuth2 Bearer: - read:blocks summary: Get an array of accounts that requesting account has blocked. tags: - blocks /api/v1/bookmarks: get: description: Get an array of statuses bookmarked in the instance operationId: bookmarksGet produces: - application/json responses: "200": description: Array of bookmarked statuses headers: Link: description: Links to the next and previous queries. type: string schema: items: $ref: '#/definitions/status' type: array "401": description: unauthorized "406": description: not acceptable "500": description: internal server error security: - OAuth2 Bearer: - read:bookmarks tags: - bookmarks /api/v1/custom_emojis: get: operationId: customEmojisGet produces: - application/json responses: "200": description: Array of custom emojis. schema: items: $ref: '#/definitions/emoji' type: array "401": description: unauthorized "406": description: not acceptable "500": description: internal server error security: - OAuth2 Bearer: - read:custom_emojis summary: Get an array of custom emojis available on the instance. tags: - custom_emojis /api/v1/favourites: get: description: |- The next and previous queries can be parsed from the returned Link header. Example: ``` ; rel="next", ; rel="prev" ```` operationId: favouritesGet parameters: - default: 20 description: Number of statuses to return. in: query name: limit type: integer - description: Return only favourited statuses *OLDER* than the given favourite ID. The status with the corresponding fave ID will not be included in the response. in: query name: max_id type: string - description: Return only favourited statuses *NEWER* than the given favourite ID. The status with the corresponding fave ID will not be included in the response. in: query name: min_id type: string produces: - application/json responses: "200": description: "" headers: Link: description: Links to the next and previous queries. type: string schema: items: $ref: '#/definitions/status' type: array "400": description: bad request "401": description: unauthorized "404": description: not found "406": description: not acceptable "500": description: internal server error security: - OAuth2 Bearer: - read:favourites summary: Get an array of statuses that the requesting account has favourited. tags: - favourites /api/v1/featured_tags: get: description: 'THIS ENDPOINT IS CURRENTLY NOT FULLY IMPLEMENTED: it will always return an empty array.' operationId: getFeaturedTags produces: - application/json responses: "200": description: "" schema: items: type: object type: array "400": description: bad request "401": description: unauthorized "404": description: not found "406": description: not acceptable "500": description: internal server error security: - OAuth2 Bearer: - read:accounts summary: Get an array of all hashtags that you currently have featured on your profile. tags: - featured_tags /api/v1/follow_requests: get: description: Accounts will be sorted in order of follow request date descending (newest first). operationId: getFollowRequests parameters: - default: 40 description: Number of accounts to return. in: query name: limit type: integer produces: - application/json responses: "200": description: "" headers: Link: description: Links to the next and previous queries. type: string schema: items: $ref: '#/definitions/account' type: array "400": description: bad request "401": description: unauthorized "404": description: not found "406": description: not acceptable "500": description: internal server error security: - OAuth2 Bearer: - read:follows summary: Get an array of accounts that have requested to follow you. tags: - follow_requests /api/v1/follow_requests/{account_id}/authorize: post: description: Accept a follow request and put the requesting account in your 'followers' list. operationId: authorizeFollowRequest parameters: - description: ID of the account requesting to follow you. in: path name: account_id required: true type: string produces: - application/json responses: "200": description: Your relationship to this account. schema: $ref: '#/definitions/accountRelationship' "400": description: bad request "401": description: unauthorized "404": description: not found "406": description: not acceptable "500": description: internal server error security: - OAuth2 Bearer: - write:follows summary: Accept/authorize follow request from the given account ID. tags: - follow_requests /api/v1/follow_requests/{account_id}/reject: post: operationId: rejectFollowRequest parameters: - description: ID of the account requesting to follow you. in: path name: account_id required: true type: string produces: - application/json responses: "200": description: Your relationship to this account. schema: $ref: '#/definitions/accountRelationship' "400": description: bad request "401": description: unauthorized "404": description: not found "406": description: not acceptable "500": description: internal server error security: - OAuth2 Bearer: - write:follows summary: Reject/deny follow request from the given account ID. tags: - follow_requests /api/v1/instance: get: operationId: instanceGetV1 produces: - application/json responses: "200": description: Instance information. schema: $ref: '#/definitions/instanceV1' "406": description: not acceptable "500": description: internal error summary: View instance information. tags: - instance patch: consumes: - multipart/form-data description: This requires admin permissions on the instance. operationId: instanceUpdate parameters: - allowEmptyValue: true description: Title to use for the instance. in: formData maximum: 40 name: title type: string - allowEmptyValue: true description: Username of the contact account. This must be the username of an instance admin. in: formData name: contact_username type: string - allowEmptyValue: true description: Email address to use as the instance contact. in: formData name: contact_email type: string - allowEmptyValue: true description: Short description of the instance. in: formData maximum: 500 name: short_description type: string - allowEmptyValue: true description: Longer description of the instance. in: formData maximum: 5000 name: description type: string - allowEmptyValue: true description: Terms and conditions of the instance. in: formData maximum: 5000 name: terms type: string - description: Thumbnail image to use for the instance. in: formData name: thumbnail type: file - description: Image description of the submitted instance thumbnail. in: formData name: thumbnail_description type: string - description: Header image to use for the instance. in: formData name: header type: file produces: - application/json responses: "200": description: The newly updated instance. schema: $ref: '#/definitions/instance' "400": description: bad request "401": description: unauthorized "403": description: forbidden "404": description: not found "406": description: not acceptable "500": description: internal server error security: - OAuth2 Bearer: - admin summary: Update your instance information and/or upload a new avatar/header for the instance. tags: - instance /api/v1/instance/peers: get: operationId: instancePeersGet parameters: - default: open description: |- Comma-separated list of filters to apply to results. Recognized filters are: - `open` -- include peers that are not suspended or silenced - `suspended` -- include peers that have been suspended. If filter is `open`, only instances that haven't been suspended or silenced will be returned. If filter is `suspended`, only suspended instances will be shown. If filter is `open,suspended`, then all known instances will be returned. If filter is an empty string or not set, then `open` will be assumed as the default. in: query name: filter type: string produces: - application/json responses: "200": description: |- If no filter parameter is provided, or filter is empty, then a legacy, Mastodon-API compatible response will be returned. This will consist of just a 'flat' array of strings like `["example.com", "example.org"]`, which corresponds to domains this instance peers with. If a filter parameter is provided, then an array of objects with at least a `domain` key set on each object will be returned. Domains that are silenced or suspended will also have a key `suspended_at` or `silenced_at` that contains an iso8601 date string. If one of these keys is not present on the domain object, it is open. Suspended instances may in some cases be obfuscated, which means they will have some letters replaced by `*` to make it more difficult for bad actors to target instances with harassment. Whether a flat response or a more detailed response is returned, domains will be sorted alphabetically by hostname. schema: items: $ref: '#/definitions/domain' type: array "400": description: bad request "401": description: unauthorized "403": description: forbidden "404": description: not found "406": description: not acceptable "500": description: internal server error tags: - instance /api/v1/media/{id}: get: operationId: mediaGet parameters: - description: id of the attachment in: path name: id required: true type: string produces: - application/json responses: "200": description: The requested media attachment. schema: $ref: '#/definitions/attachment' "400": description: bad request "401": description: unauthorized "404": description: not found "406": description: not acceptable "500": description: internal server error security: - OAuth2 Bearer: - read:media summary: Get a media attachment that you own. tags: - media put: consumes: - application/json - application/xml - application/x-www-form-urlencoded description: |- You must own the media attachment, and the attachment must not yet be attached to a status. The parameters can also be given in the body of the request, as JSON, if the content-type is set to 'application/json'. The parameters can also be given in the body of the request, as XML, if the content-type is set to 'application/xml'. operationId: mediaUpdate parameters: - description: id of the attachment to update in: path name: id required: true type: string - allowEmptyValue: true description: Image or media description to use as alt-text on the attachment. This is very useful for users of screenreaders! May or may not be required, depending on your instance settings. in: formData name: description type: string - allowEmptyValue: true default: 0,0 description: 'Focus of the media file. If present, it should be in the form of two comma-separated floats between -1 and 1. For example: `-0.5,0.25`.' in: formData name: focus type: string produces: - application/json responses: "200": description: The newly-updated media attachment. schema: $ref: '#/definitions/attachment' "400": description: bad request "401": description: unauthorized "404": description: not found "406": description: not acceptable "500": description: internal server error security: - OAuth2 Bearer: - write:media summary: Update a media attachment. tags: - media /api/v1/notification/{id}: get: operationId: notification produces: - application/json responses: "200": description: Requested notification. schema: $ref: '#/definitions/notification' "400": description: bad request "401": description: unauthorized "404": description: not found "406": description: not acceptable "500": description: internal server error security: - OAuth2 Bearer: - read:notifications summary: Get a single notification with the given ID. tags: - notifications /api/v1/notifications: get: description: |- The notifications will be returned in descending chronological order (newest first), with sequential IDs (bigger = newer). The next and previous queries can be parsed from the returned Link header. Example: ``` ; rel="next", ; rel="prev" ```` operationId: notifications parameters: - description: Return only notifications *OLDER* than the given max notification ID. The notification with the specified ID will not be included in the response. in: query name: max_id type: string - description: Return only notifications *newer* than the given since notification ID. The notification with the specified ID will not be included in the response. in: query name: since_id type: string - description: Return only notifications *immediately newer* than the given since notification ID. The notification with the specified ID will not be included in the response. in: query name: min_id type: string - default: 20 description: Number of notifications to return. in: query name: limit type: integer - in: query items: type: string name: exclude_types type: array produces: - application/json responses: "200": description: Array of notifications. headers: Link: description: Links to the next and previous queries. type: string schema: items: $ref: '#/definitions/notification' type: array "400": description: bad request "401": description: unauthorized "404": description: not found "406": description: not acceptable "500": description: internal server error security: - OAuth2 Bearer: - read:notifications summary: Get notifications for currently authorized user. tags: - notifications post: description: Will return an empty object `{}` to indicate success. operationId: clearNotifications produces: - application/json responses: "200": description: "" schema: type: object "400": description: bad request "401": description: unauthorized "404": description: not found "406": description: not acceptable "500": description: internal server error security: - OAuth2 Bearer: - read:notifications summary: Clear/delete all notifications for currently authorized user. tags: - notifications /api/v1/preferences: get: description: |- Example: ``` { "posting:default:visibility": "public", "posting:default:sensitive": false, "posting:default:language": "en", "reading:expand:media": "default", "reading:expand:spoilers": false, "reading:autoplay:gifs": false } ```` operationId: preferencesGet produces: - application/json responses: "200": description: "" schema: type: object "400": description: bad request "401": description: unauthorized "404": description: not found "406": description: not acceptable "500": description: internal server error security: - OAuth2 Bearer: - read:accounts summary: Return an object of user preferences. tags: - preferences /api/v1/reports: get: description: |- The reports will be returned in descending chronological order (newest first), with sequential IDs (bigger = newer). The next and previous queries can be parsed from the returned Link header. Example: ``` ; rel="next", ; rel="prev" ```` operationId: reports parameters: - description: If set to true, only resolved reports will be returned. If false, only unresolved reports will be returned. If unset, reports will not be filtered on their resolved status. in: query name: resolved type: boolean - description: Return only reports that target the given account id. in: query name: target_account_id type: string - description: Return only reports *OLDER* than the given max ID. The report with the specified ID will not be included in the response. in: query name: max_id type: string - description: Return only reports *NEWER* than the given since ID. The report with the specified ID will not be included in the response. This parameter is functionally equivalent to min_id. in: query name: since_id type: string - description: Return only reports *NEWER* than the given min ID. The report with the specified ID will not be included in the response. This parameter is functionally equivalent to since_id. in: query name: min_id type: string - default: 20 description: Number of reports to return. If less than 1, will be clamped to 1. If more than 100, will be clamped to 100. in: query name: limit type: integer produces: - application/json responses: "200": description: Array of reports. schema: items: $ref: '#/definitions/report' type: array "400": description: bad request "401": description: unauthorized "404": description: not found "406": description: not acceptable "500": description: internal server error security: - OAuth2 Bearer: - read:reports summary: See reports created by the requesting account. tags: - reports post: consumes: - application/json - application/xml - application/x-www-form-urlencoded operationId: reportCreate parameters: - description: ID of the account to report. example: 01GPE75FXSH2EGFBF85NXPH3KP in: formData name: account_id required: true type: string x-go-name: AccountID - description: IDs of statuses to attach to the report to provide additional context. example: - 01GPE76N4SBVRZ8K24TW51ZZQ4 - 01GPE76WN9JZE62EPT3Q9FRRD4 in: formData items: type: string name: status_ids type: array x-go-name: StatusIDs - description: The reason for the report. Default maximum of 1000 characters. example: Anti-Blackness, transphobia. in: formData name: comment type: string x-go-name: Comment - default: false description: If the account is remote, should the report be forwarded to the remote admin? example: true in: formData name: forward type: boolean x-go-name: Forward - default: other description: |- Specify if the report is due to spam, violation of enumerated instance rules, or some other reason. Currently only 'other' is supported. example: other in: formData name: category type: string x-go-name: Category - description: |- IDs of rules on this instance which have been broken according to the reporter. This is currently not supported, provided only for API compatibility. example: - 1 - 2 - 3 in: formData items: format: int64 type: integer name: rule_ids type: array x-go-name: RuleIDs produces: - application/json responses: "200": description: The created report. schema: $ref: '#/definitions/report' "400": description: bad request "401": description: unauthorized "404": description: not found "406": description: not acceptable "500": description: internal server error security: - OAuth2 Bearer: - write:reports summary: Create a new user report with the given parameters. tags: - reports /api/v1/reports/{id}: get: operationId: reportGet parameters: - description: ID of the report in: path name: id required: true type: string produces: - application/json responses: "200": description: The requested report. schema: $ref: '#/definitions/report' "400": description: bad request "401": description: unauthorized "404": description: not found "406": description: not acceptable "500": description: internal server error security: - OAuth2 Bearer: - read:reports summary: Get one report with the given id. tags: - reports /api/v1/search: get: description: If statuses are in the result, they will be returned in descending chronological order (newest first), with sequential IDs (bigger = newer). operationId: searchGet parameters: - description: If type is `statuses`, then statuses returned will be authored only by this account. in: query name: account_id type: string x-go-name: AccountID - description: |- Return results *older* than this id. The entry with this ID will not be included in the search results. in: query name: max_id type: string x-go-name: MaxID - description: |- Return results *newer* than this id. The entry with this ID will not be included in the search results. in: query name: min_id type: string x-go-name: MinID - description: |- Type of the search query to perform. Must be one of: `accounts`, `hashtags`, `statuses`. in: query name: type required: true type: string x-go-name: Type - default: false description: Filter out tags that haven't been reviewed and approved by an instance admin. in: query name: exclude_unreviewed type: boolean x-go-name: ExcludeUnreviewed - description: |- String to use as a search query. For accounts, this should be in the format `@someaccount@some.instance.com`, or the format `https://some.instance.com/@someaccount` For a status, this can be in the format: `https://some.instance.com/@someaccount/SOME_ID_OF_A_STATUS` in: query name: q required: true type: string x-go-name: Query - default: false description: Attempt to resolve the query by performing a remote webfinger lookup, if the query includes a remote host. in: query name: resolve type: boolean x-go-name: Resolve - default: 20 description: Maximum number of results to load, per type. format: int64 in: query maximum: 40 minimum: 1 name: limit type: integer x-go-name: Limit - default: 0 description: Offset for paginating search results. format: int64 in: query name: offset type: integer x-go-name: Offset - default: false description: Only include accounts that the searching account is following. in: query name: following type: boolean x-go-name: Following responses: "200": description: Results of the search. schema: items: $ref: '#/definitions/searchResult' type: array "400": description: bad request "401": description: unauthorized "404": description: not found "406": description: not acceptable "500": description: internal server error security: - OAuth2 Bearer: - read:search summary: Search for statuses, accounts, or hashtags, on this instance or elsewhere. tags: - search /api/v1/statuses: post: consumes: - application/json - application/xml - application/x-www-form-urlencoded description: |- The parameters can also be given in the body of the request, as JSON, if the content-type is set to 'application/json'. The parameters can also be given in the body of the request, as XML, if the content-type is set to 'application/xml'. operationId: statusCreate parameters: - description: |- Text content of the status. If media_ids is provided, this becomes optional. Attaching a poll is optional while status is provided. in: formData name: status type: string x-go-name: Status - description: |- Array of Attachment ids to be attached as media. If provided, status becomes optional, and poll cannot be used. If the status is being submitted as a form, the key is 'media_ids[]', but if it's json or xml, the key is 'media_ids'. in: formData items: type: string name: media_ids type: array x-go-name: MediaIDs - description: ID of the status being replied to, if status is a reply. in: formData name: in_reply_to_id type: string x-go-name: InReplyToID - description: Status and attached media should be marked as sensitive. in: formData name: sensitive type: boolean x-go-name: Sensitive - description: |- Text to be shown as a warning or subject before the actual content. Statuses are generally collapsed behind this field. in: formData name: spoiler_text type: string x-go-name: SpoilerText - description: Visibility of the posted status. in: formData name: visibility x-go-name: Visibility - description: |- ISO 8601 Datetime at which to schedule a status. Providing this parameter will cause ScheduledStatus to be returned instead of Status. Must be at least 5 minutes in the future. in: formData name: scheduled_at type: string x-go-name: ScheduledAt - description: ISO 639 language code for this status. in: formData name: language type: string x-go-name: Language - description: Content type to use when parsing this status. in: formData name: content_type x-go-name: ContentType - description: This status will be federated beyond the local timeline(s). in: query name: federated type: boolean x-go-name: Federated - description: This status can be boosted/reblogged. in: query name: boostable type: boolean x-go-name: Boostable - description: This status can be replied to. in: query name: replyable type: boolean x-go-name: Replyable - description: This status can be liked/faved. in: query name: likeable type: boolean x-go-name: Likeable produces: - application/json responses: "200": description: The newly created status. schema: $ref: '#/definitions/status' "400": description: bad request "401": description: unauthorized "403": description: forbidden "404": description: not found "406": description: not acceptable "500": description: internal server error security: - OAuth2 Bearer: - write:statuses summary: Create a new status. tags: - statuses /api/v1/statuses/{id}: delete: description: |- The deleted status will be returned in the response. The `text` field will contain the original text of the status as it was submitted. This is useful when doing a 'delete and redraft' type operation. operationId: statusDelete parameters: - description: Target status ID. in: path name: id required: true type: string produces: - application/json responses: "200": description: The status that was just deleted. schema: $ref: '#/definitions/status' "400": description: bad request "401": description: unauthorized "403": description: forbidden "404": description: not found "406": description: not acceptable "500": description: internal server error security: - OAuth2 Bearer: - write:statuses summary: Delete status with the given ID. The status must belong to you. tags: - statuses get: operationId: statusGet parameters: - description: Target status ID. in: path name: id required: true type: string produces: - application/json responses: "200": description: The requested status. schema: $ref: '#/definitions/status' "400": description: bad request "401": description: unauthorized "403": description: forbidden "404": description: not found "406": description: not acceptable "500": description: internal server error security: - OAuth2 Bearer: - read:statuses summary: View status with the given ID. tags: - statuses /api/v1/statuses/{id}/bookmark: post: operationId: statusBookmark parameters: - description: Target status ID. in: path name: id required: true type: string produces: - application/json responses: "200": description: The status. schema: $ref: '#/definitions/status' "400": description: bad request "401": description: unauthorized "403": description: forbidden "404": description: not found "406": description: not acceptable "500": description: internal server error security: - OAuth2 Bearer: - write:statuses summary: Bookmark status with the given ID. tags: - statuses /api/v1/statuses/{id}/context: get: description: The returned statuses will be ordered in a thread structure, so they are suitable to be displayed in the order in which they were returned. operationId: statusContext parameters: - description: Target status ID. in: path name: id required: true type: string produces: - application/json responses: "200": description: Status context object. schema: $ref: '#/definitions/statusContext' "400": description: bad request "401": description: unauthorized "403": description: forbidden "404": description: not found "406": description: not acceptable "500": description: internal server error security: - OAuth2 Bearer: - read:statuses summary: Return ancestors and descendants of the given status. tags: - statuses /api/v1/statuses/{id}/favourite: post: operationId: statusFave parameters: - description: Target status ID. in: path name: id required: true type: string produces: - application/json responses: "200": description: The newly faved status. schema: $ref: '#/definitions/status' "400": description: bad request "401": description: unauthorized "403": description: forbidden "404": description: not found "406": description: not acceptable "500": description: internal server error security: - OAuth2 Bearer: - write:statuses summary: Star/like/favourite the given status, if permitted. tags: - statuses /api/v1/statuses/{id}/favourited_by: get: operationId: statusFavedBy parameters: - description: Target status ID. in: path name: id required: true type: string produces: - application/json responses: "200": description: "" schema: items: $ref: '#/definitions/account' type: array "400": description: bad request "401": description: unauthorized "403": description: forbidden "404": description: not found "406": description: not acceptable "500": description: internal server error security: - OAuth2 Bearer: - read:accounts summary: View accounts that have faved/starred/liked the target status. tags: - statuses /api/v1/statuses/{id}/pin: post: description: |- You can only pin original posts (not reblogs) that you authored yourself. Supported privacy levels for pinned posts are public, unlisted, and private/followers-only, but only public posts will appear on the web version of your profile. operationId: statusPin parameters: - description: Target status ID. in: path name: id required: true type: string produces: - application/json responses: "200": description: The status. schema: $ref: '#/definitions/status' "400": description: bad request "401": description: unauthorized "403": description: forbidden "404": description: not found "406": description: not acceptable "500": description: internal server error security: - OAuth2 Bearer: - write:accounts summary: Pin a status to the top of your profile, and add it to your Featured ActivityPub collection. tags: - statuses /api/v1/statuses/{id}/reblog: post: description: |- If the target status is rebloggable/boostable, it will be shared with your followers. This is equivalent to an ActivityPub 'Announce' activity. operationId: statusReblog parameters: - description: Target status ID. in: path name: id required: true type: string produces: - application/json responses: "200": description: The boost of the status. schema: $ref: '#/definitions/status' "400": description: bad request "401": description: unauthorized "403": description: forbidden "404": description: not found "406": description: not acceptable "500": description: internal server error security: - OAuth2 Bearer: - write:statuses summary: Reblog/boost status with the given ID. tags: - statuses /api/v1/statuses/{id}/reblogged_by: get: operationId: statusBoostedBy parameters: - description: Target status ID. in: path name: id required: true type: string produces: - application/json responses: "200": description: "" schema: items: $ref: '#/definitions/account' type: array "400": description: bad request "401": description: unauthorized "403": description: forbidden "404": description: not found security: - OAuth2 Bearer: - read:accounts summary: View accounts that have reblogged/boosted the target status. tags: - statuses /api/v1/statuses/{id}/unbookmark: post: operationId: statusUnbookmark parameters: - description: Target status ID. in: path name: id required: true type: string produces: - application/json responses: "200": description: The status. schema: $ref: '#/definitions/status' "400": description: bad request "401": description: unauthorized "403": description: forbidden "404": description: not found "406": description: not acceptable "500": description: internal server error security: - OAuth2 Bearer: - write:statuses summary: Unbookmark status with the given ID. tags: - statuses /api/v1/statuses/{id}/unfavourite: post: operationId: statusUnfave parameters: - description: Target status ID. in: path name: id required: true type: string produces: - application/json responses: "200": description: The unfaved status. schema: $ref: '#/definitions/status' "400": description: bad request "401": description: unauthorized "403": description: forbidden "404": description: not found "406": description: not acceptable "500": description: internal server error security: - OAuth2 Bearer: - write:statuses summary: Unstar/unlike/unfavourite the given status. tags: - statuses /api/v1/statuses/{id}/unpin: post: operationId: statusUnpin parameters: - description: Target status ID. in: path name: id required: true type: string produces: - application/json responses: "200": description: The status. schema: $ref: '#/definitions/status' "400": description: bad request "401": description: unauthorized "403": description: forbidden "404": description: not found "406": description: not acceptable "500": description: internal server error security: - OAuth2 Bearer: - write:accounts summary: Unpin one of your pinned statuses. tags: - statuses /api/v1/statuses/{id}/unreblog: post: operationId: statusUnreblog parameters: - description: Target status ID. in: path name: id required: true type: string produces: - application/json responses: "200": description: The unboosted status. schema: $ref: '#/definitions/status' "400": description: bad request "401": description: unauthorized "403": description: forbidden "404": description: not found "406": description: not acceptable "500": description: internal server error security: - OAuth2 Bearer: - write:statuses summary: Unreblog/unboost status with the given ID. tags: - statuses /api/v1/streaming: get: description: |- The scheme used should *always* be `wss`. The streaming basepath can be viewed at `/api/v1/instance`. On a successful connection, a code `101` will be returned, which indicates that the connection is being upgraded to a secure websocket connection. As long as the connection is open, various message types will be streamed into it. GoToSocial will ping the connection every 30 seconds to check whether the client is still receiving. If the ping fails, or something else goes wrong during transmission, then the connection will be dropped, and the client will be expected to start it again. operationId: streamGet parameters: - description: Access token for the requesting account. in: query name: access_token required: true type: string - description: |- Type of stream to request. Options are: `user`: receive updates for the account's home timeline. `public`: receive updates for the public timeline. `public:local`: receive updates for the local timeline. `hashtag`: receive updates for a given hashtag. `hashtag:local`: receive local updates for a given hashtag. `list`: receive updates for a certain list of accounts. `direct`: receive updates for direct messages. in: query name: stream required: true type: string produces: - application/json responses: "101": description: "" schema: properties: event: description: |- The type of event being received. `update`: a new status has been received. `notification`: a new notification has been received. `delete`: a status has been deleted. `filters_changed`: not implemented. enum: - update - notification - delete - filters_changed type: string payload: description: |- The payload of the streamed message. Different depending on the `event` type. If present, it should be parsed as a string. If `event` = `update`, then the payload will be a JSON string of a status. If `event` = `notification`, then the payload will be a JSON string of a notification. If `event` = `delete`, then the payload will be a status ID. example: '{"id":"01FC3TZ5CFG6H65GCKCJRKA669","created_at":"2021-08-02T16:25:52Z","sensitive":false,"spoiler_text":"","visibility":"public","language":"en","uri":"https://gts.superseriousbusiness.org/users/dumpsterqueer/statuses/01FC3TZ5CFG6H65GCKCJRKA669","url":"https://gts.superseriousbusiness.org/@dumpsterqueer/statuses/01FC3TZ5CFG6H65GCKCJRKA669","replies_count":0,"reblogs_count":0,"favourites_count":0,"favourited":false,"reblogged":false,"muted":false,"bookmarked":fals…//gts.superseriousbusiness.org/fileserver/01JNN207W98SGG3CBJ76R5MVDN/header/original/019036W043D8FXPJKSKCX7G965.png","header_static":"https://gts.superseriousbusiness.org/fileserver/01JNN207W98SGG3CBJ76R5MVDN/header/small/019036W043D8FXPJKSKCX7G965.png","followers_count":33,"following_count":28,"statuses_count":126,"last_status_at":"2021-08-02T16:25:52Z","emojis":[],"fields":[]},"media_attachments":[],"mentions":[],"tags":[],"emojis":[],"card":null,"poll":null,"text":"a"}' type: string stream: items: enum: - user - public - public:local - hashtag - hashtag:local - list - direct type: string type: array type: object "400": description: bad request "401": description: unauthorized schemes: - wss security: - OAuth2 Bearer: - read:streaming summary: Initiate a websocket connection for live streaming of statuses and notifications. tags: - streaming /api/v1/timelines/home: get: description: |- The statuses will be returned in descending chronological order (newest first), with sequential IDs (bigger = newer). The returned Link header can be used to generate the previous and next queries when scrolling up or down a timeline. Example: ``` ; rel="next", ; rel="prev" ```` operationId: homeTimeline parameters: - description: Return only statuses *OLDER* than the given max status ID. The status with the specified ID will not be included in the response. in: query name: max_id type: string - description: Return only statuses *newer* than the given since status ID. The status with the specified ID will not be included in the response. in: query name: since_id type: string - description: Return only statuses *immediately newer* than the given since status ID. The status with the specified ID will not be included in the response. in: query name: min_id type: string - default: 20 description: Number of statuses to return. in: query name: limit type: integer - default: false description: Show only statuses posted by local accounts. in: query name: local type: boolean produces: - application/json responses: "200": description: Array of statuses. headers: Link: description: Links to the next and previous queries. type: string schema: items: $ref: '#/definitions/status' type: array "400": description: bad request "401": description: unauthorized security: - OAuth2 Bearer: - read:statuses summary: See statuses/posts by accounts you follow. tags: - timelines /api/v1/timelines/public: get: description: |- The statuses will be returned in descending chronological order (newest first), with sequential IDs (bigger = newer). The returned Link header can be used to generate the previous and next queries when scrolling up or down a timeline. Example: ``` ; rel="next", ; rel="prev" ```` operationId: publicTimeline parameters: - description: Return only statuses *OLDER* than the given max status ID. The status with the specified ID will not be included in the response. in: query name: max_id type: string - description: Return only statuses *NEWER* than the given since status ID. The status with the specified ID will not be included in the response. in: query name: since_id type: string - description: Return only statuses *NEWER* than the given since status ID. The status with the specified ID will not be included in the response. in: query name: min_id type: string - default: 20 description: Number of statuses to return. in: query name: limit type: integer - default: false description: Show only statuses posted by local accounts. in: query name: local type: boolean produces: - application/json responses: "200": description: Array of statuses. headers: Link: description: Links to the next and previous queries. type: string schema: items: $ref: '#/definitions/status' type: array "400": description: bad request "401": description: unauthorized security: - OAuth2 Bearer: - read:statuses summary: See public statuses/posts that your instance is aware of. tags: - timelines /api/v1/user/password_change: post: consumes: - application/json - application/xml - application/x-www-form-urlencoded description: |- The parameters can also be given in the body of the request, as JSON, if the content-type is set to 'application/json'. The parameters can also be given in the body of the request, as XML, if the content-type is set to 'application/xml'. operationId: userPasswordChange parameters: - description: User's previous password. in: formData name: old_password required: true type: string x-go-name: OldPassword - description: |- Desired new password. If the password does not have high enough entropy, it will be rejected. See https://github.com/wagslane/go-password-validator in: formData name: new_password required: true type: string x-go-name: NewPassword produces: - application/json responses: "200": description: Change successful "400": description: bad request "401": description: unauthorized "403": description: forbidden "406": description: not acceptable "500": description: internal error security: - OAuth2 Bearer: - write:user summary: Change the password of authenticated user. tags: - user /api/v2/instance: get: operationId: instanceGetV2 produces: - application/json responses: "200": description: Instance information. schema: $ref: '#/definitions/instanceV2' "406": description: not acceptable "500": description: internal error summary: View instance information. tags: - instance /nodeinfo/2.0: get: description: 'See: https://nodeinfo.diaspora.software/schema.html' operationId: nodeInfoGet produces: - application/json; profile="http://nodeinfo.diaspora.software/ns/schema/2.0#" responses: "200": description: "" schema: $ref: '#/definitions/nodeinfo' summary: Returns a compliant nodeinfo response to node info queries. tags: - nodeinfo /users/{username}/collections/featured: get: description: |- The response will contain an ordered collection of Note URIs in the `items` property. It is up to the caller to dereference the provided Note URIs (or not, if they already have them cached). HTTP signature is required on the request. operationId: s2sFeaturedCollectionGet produces: - application/activity+json responses: "200": description: "" schema: $ref: '#/definitions/swaggerFeaturedCollection' "400": description: bad request "401": description: unauthorized "403": description: forbidden "404": description: not found summary: Get the featured collection (pinned posts) for a user. tags: - s2s/federation /users/{username}/outbox: get: description: |- Note that the response will be a Collection with a page as `first`, as shown below, if `page` is `false`. If `page` is `true`, then the response will be a single `CollectionPage` without the wrapping `Collection`. HTTP signature is required on the request. operationId: s2sOutboxGet parameters: - description: Username of the account. in: path name: username required: true type: string - default: false description: Return response as a CollectionPage. in: query name: page type: boolean - description: Minimum ID of the next status, used for paging. in: query name: min_id type: string - description: Maximum ID of the next status, used for paging. in: query name: max_id type: string produces: - application/activity+json responses: "200": description: "" schema: $ref: '#/definitions/swaggerCollection' "400": description: bad request "401": description: unauthorized "403": description: forbidden "404": description: not found summary: Get the public outbox collection for an actor. tags: - s2s/federation /users/{username}/statuses/{status}/replies: get: description: |- Note that the response will be a Collection with a page as `first`, as shown below, if `page` is `false`. If `page` is `true`, then the response will be a single `CollectionPage` without the wrapping `Collection`. HTTP signature is required on the request. operationId: s2sRepliesGet parameters: - description: Username of the account. in: path name: username required: true type: string - description: ID of the status. in: path name: status required: true type: string - default: false description: Return response as a CollectionPage. in: query name: page type: boolean - default: false description: Return replies only from accounts other than the status owner. in: query name: only_other_accounts type: boolean - description: Minimum ID of the next status, used for paging. in: query name: min_id type: string produces: - application/activity+json responses: "200": description: "" schema: $ref: '#/definitions/swaggerCollection' "400": description: bad request "401": description: unauthorized "403": description: forbidden "404": description: not found summary: Get the replies collection for a status. tags: - s2s/federation schemes: - https - http securityDefinitions: OAuth2 Application: flow: application scopes: write:accounts: grants write access to accounts tokenUrl: https://example.org/oauth/token type: oauth2 OAuth2 Bearer: authorizationUrl: https://example.org/oauth/authorize flow: accessCode scopes: admin: grants admin access to everything admin:accounts: grants admin access to accounts read: grants read access to everything read:accounts: grants read access to accounts read:blocks: grant read access to blocks read:custom_emojis: grant read access to custom_emojis read:favourites: grant read access to favourites read:follows: grant read access to follows read:media: grant read access to media read:notifications: grants read access to notifications read:search: grant read access to searches read:statuses: grants read access to statuses read:streaming: grants read access to streaming api read:user: grants read access to user-level info write: grants write access to everything write:accounts: grants write access to accounts write:blocks: grants write access to blocks write:follows: grants write access to follows write:media: grants write access to media write:statuses: grants write access to statuses write:user: grants write access to user-level info tokenUrl: https://example.org/oauth/token type: oauth2 swagger: "2.0"