basePath: / definitions: FilterAction: title: FilterAction is the action to apply to statuses matching a filter. type: string x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/model InstanceConfigurationEmojis: properties: emoji_size_limit: description: Max allowed emoji image size in bytes. example: 51200 format: int64 type: integer x-go-name: EmojiSizeLimit title: InstanceConfigurationEmojis models instance emoji config parameters. type: object x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/model Link: description: See https://webfinger.net/ and https://www.rfc-editor.org/rfc/rfc6415.html#section-3.1 properties: href: type: string x-go-name: Href rel: type: string x-go-name: Rel template: type: string x-go-name: Template type: type: string x-go-name: Type title: Link represents one 'link' in a slice of links returned from a lookup request. type: object x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/model Mention: properties: acct: description: |- The account URI as discovered via webfinger. Equal to username for local users, or username@domain for remote users. example: some_user@example.org type: string x-go-name: Acct id: description: The ID of the mentioned account. example: 01FBYJHQWQZAVWFRK9PDYTKGMB type: string x-go-name: ID url: description: The web URL of the mentioned account's profile. example: https://example.org/@some_user type: string x-go-name: URL username: description: The username of the mentioned account. example: some_user type: string x-go-name: Username title: Mention represents a mention of another account. type: object x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/model NodeInfoServices: properties: inbound: items: type: string type: array x-go-name: Inbound outbound: items: type: string type: array x-go-name: Outbound title: NodeInfoServices represents inbound and outbound services that this node offers connections to. type: object x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/model NodeInfoSoftware: properties: name: example: gotosocial type: string x-go-name: Name version: example: 0.1.2 1234567 type: string x-go-name: Version title: NodeInfoSoftware represents the name and version number of the software of this node. type: object x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/model NodeInfoUsage: properties: localPosts: format: int64 type: integer x-go-name: LocalPosts users: $ref: '#/definitions/NodeInfoUsers' title: NodeInfoUsage represents usage information about this server, such as number of users. type: object x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/model NodeInfoUsers: properties: total: format: int64 type: integer x-go-name: Total title: NodeInfoUsers represents aggregate information about the users on the server. type: object x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/model Source: description: Returned as an additional entity when verifying and updated credentials, as an attribute of Account. properties: also_known_as_uris: description: |- This account is aliased to / also known as accounts at the given ActivityPub URIs. To set this, use `/api/v1/accounts/alias`. Omitted from json if empty / not set. items: type: string type: array x-go-name: AlsoKnownAsURIs fields: description: Metadata about the account. items: $ref: '#/definitions/field' type: array x-go-name: Fields follow_requests_count: description: The number of pending follow requests. format: int64 type: integer x-go-name: FollowRequestsCount language: description: The default posting language for new statuses. type: string x-go-name: Language note: description: Profile bio. type: string x-go-name: Note privacy: description: |- The default post privacy to be used for new statuses. public = Public post unlisted = Unlisted post private = Followers-only post direct = Direct post type: string x-go-name: Privacy sensitive: description: Whether new statuses should be marked sensitive by default. type: boolean x-go-name: Sensitive status_content_type: description: The default posting content type for new statuses. type: string x-go-name: StatusContentType web_visibility: description: |- Visibility level(s) of posts to show for this account via the web api. "public" = default, show only Public visibility posts on the web. "unlisted" = show Public *and* Unlisted visibility posts on the web. "none" = show no posts on the web, not even Public ones. type: string x-go-name: WebVisibility title: Source represents display or publishing preferences of user's own account. type: object x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/model TimelineMarker: properties: last_read_id: description: The ID of the most recently viewed entity. type: string x-go-name: LastReadID updated_at: description: The timestamp of when the marker was set (ISO 8601 Datetime) type: string x-go-name: UpdatedAt version: description: Used for locking to prevent write conflicts. format: int64 type: integer x-go-name: Version title: TimelineMarker contains information about a user's progress through a specific timeline. type: object x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/model account: description: The modelled account can be either a remote account, or one on this instance. properties: acct: description: |- The account URI as discovered via webfinger. Equal to username for local users, or username@domain for remote users. example: some_user@example.org type: string x-go-name: Acct avatar: description: Web location of the account's avatar. example: https://example.org/media/some_user/avatar/original/avatar.jpeg type: string x-go-name: Avatar avatar_description: description: Description of this account's avatar, for alt text. example: A cute drawing of a smiling sloth. type: string x-go-name: AvatarDescription avatar_media_id: description: |- Database ID of the media attachment for this account's avatar image. Omitted if no avatar uploaded for this account (ie., default avatar). example: 01JAJ3XCD66K3T99JZESCR137W type: string x-go-name: AvatarMediaID avatar_static: description: |- Web location of a static version of the account's avatar. Only relevant when the account's main avatar is a video or a gif. example: https://example.org/media/some_user/avatar/static/avatar.png type: string x-go-name: AvatarStatic bot: description: Account identifies as a bot. type: boolean x-go-name: Bot created_at: description: When the account was created (ISO 8601 Datetime). example: "2021-07-30T09:20:25+00:00" type: string x-go-name: CreatedAt custom_css: description: CustomCSS to include when rendering this account's profile or statuses. type: string x-go-name: CustomCSS discoverable: description: Account has opted into discovery features. type: boolean x-go-name: Discoverable display_name: description: The account's display name. example: big jeff (he/him) type: string x-go-name: DisplayName emojis: description: |- Array of custom emojis used in this account's note or display name. Empty for blocked accounts. items: $ref: '#/definitions/emoji' type: array x-go-name: Emojis enable_rss: description: |- Account has enabled RSS feed. Key/value omitted if false. type: boolean x-go-name: EnableRSS fields: description: |- Additional metadata attached to this account's profile. Empty for blocked accounts. items: $ref: '#/definitions/field' type: array x-go-name: Fields followers_count: description: Number of accounts following this account, according to our instance. format: int64 type: integer x-go-name: FollowersCount following_count: description: Number of account's followed by this account, according to our instance. format: int64 type: integer x-go-name: FollowingCount header: description: Web location of the account's header image. example: https://example.org/media/some_user/header/original/header.jpeg type: string x-go-name: Header header_description: description: Description of this account's header, for alt text. example: A sunlit field with purple flowers. type: string x-go-name: HeaderDescription header_media_id: description: |- Database ID of the media attachment for this account's header image. Omitted if no header uploaded for this account (ie., default header). example: 01JAJ3XCD66K3T99JZESCR137W type: string x-go-name: HeaderMediaID header_static: description: |- Web location of a static version of the account's header. Only relevant when the account's main header is a video or a gif. example: https://example.org/media/some_user/header/static/header.png type: string x-go-name: HeaderStatic hide_collections: description: |- Account has opted to hide their followers/following collections. Key/value omitted if false. type: boolean x-go-name: HideCollections id: description: The account id. example: 01FBVD42CQ3ZEEVMW180SBX03B type: string x-go-name: ID last_status_at: description: When the account's most recent status was posted (ISO 8601 Date). example: "2021-07-30" type: string x-go-name: LastStatusAt locked: description: Account manually approves follow requests. type: boolean x-go-name: Locked moved: $ref: '#/definitions/account' note: description: Bio/description of this account. type: string x-go-name: Note role: $ref: '#/definitions/accountRole' roles: description: |- Roles lists the public roles of the account on this instance. Unlike Role, this is always available, but never includes permissions details. Key/value omitted for remote accounts. items: $ref: '#/definitions/accountDisplayRole' type: array x-go-name: Roles source: $ref: '#/definitions/Source' statuses_count: description: Number of statuses posted by this account, according to our instance. format: int64 type: integer x-go-name: StatusesCount suspended: description: Account has been suspended by our instance. type: boolean x-go-name: Suspended theme: description: Filename of user-selected CSS theme to include when rendering this account's profile or statuses. Eg., `blurple-light.css`. type: string x-go-name: Theme url: description: Web location of the account's profile page. example: https://example.org/@some_user type: string x-go-name: URL username: description: The username of the account, not including domain. example: some_user type: string x-go-name: Username title: Account models a fediverse account. type: object x-go-name: Account x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/model accountDisplayRole: description: This is a subset of AccountRole. properties: color: description: |- Color is a 6-digit CSS-style hex color code with leading `#`, or an empty string if this role has no color. Since GotoSocial doesn't use role colors, we leave this empty. type: string x-go-name: Color id: description: |- ID of the role. Not used by GotoSocial, but we set it to the role name, just in case a client expects a unique ID. type: string x-go-name: ID name: description: Name of the role. type: string x-go-name: Name title: AccountDisplayRole models a public, displayable role of an account. type: object x-go-name: AccountDisplayRole x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/model accountExportStats: description: |- AccountExportStats models an account's stats specifically for the purpose of informing about export sizes at the /api/v1/exports/stats endpoint. properties: blocks_count: description: Number of accounts blocked by this account. example: 15 format: int64 type: integer x-go-name: BlocksCount followers_count: description: Number of accounts following this account. example: 50 format: int64 type: integer x-go-name: FollowersCount following_count: description: Number of accounts followed by this account. example: 50 format: int64 type: integer x-go-name: FollowingCount lists_count: description: Number of lists created by this account. example: 10 format: int64 type: integer x-go-name: ListsCount media_storage: description: 'TODO: String representation of media storage size attributed to this account.' example: 500MB type: string x-go-name: MediaStorage mutes_count: description: Number of accounts muted by this account. example: 11 format: int64 type: integer x-go-name: MutesCount statuses_count: description: Number of statuses created by this account. example: 81986 format: int64 type: integer x-go-name: StatusesCount type: object x-go-name: AccountExportStats x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/model accountRelationship: properties: blocked_by: description: This account is blocking you. type: boolean x-go-name: BlockedBy blocking: description: You are blocking this account. type: boolean x-go-name: Blocking domain_blocking: description: You are blocking this account's domain. type: boolean x-go-name: DomainBlocking endorsed: description: You are featuring this account on your profile. type: boolean x-go-name: Endorsed followed_by: description: This account follows you. type: boolean x-go-name: FollowedBy following: description: You are following this account. type: boolean x-go-name: Following id: description: The account id. example: 01FBW9XGEP7G6K88VY4S9MPE1R type: string x-go-name: ID muting: description: You are muting this account. type: boolean x-go-name: Muting muting_notifications: description: You are muting notifications from this account. type: boolean x-go-name: MutingNotifications note: description: Your note on this account. type: string x-go-name: Note notifying: description: You are seeing notifications when this account posts. type: boolean x-go-name: Notifying requested: description: You have requested to follow this account, and the request is pending. type: boolean x-go-name: Requested requested_by: description: This account has requested to follow you, and the request is pending. type: boolean x-go-name: RequestedBy showing_reblogs: description: You are seeing reblogs/boosts from this account in your home timeline. type: boolean x-go-name: ShowingReblogs title: Relationship represents a relationship between accounts. type: object x-go-name: Relationship x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/model accountRole: properties: color: description: |- Color is a 6-digit CSS-style hex color code with leading `#`, or an empty string if this role has no color. Since GotoSocial doesn't use role colors, we leave this empty. type: string x-go-name: Color highlighted: description: |- Highlighted indicates whether the role is publicly visible on the user profile. This is always true for GotoSocial's built-in admin and moderator roles, and false otherwise. type: boolean x-go-name: Highlighted id: description: |- ID of the role. Not used by GotoSocial, but we set it to the role name, just in case a client expects a unique ID. type: string x-go-name: ID name: description: Name of the role. type: string x-go-name: Name permissions: description: Permissions is a bitmap serialized as a numeric string, indicating which admin/moderation actions a user can perform. type: string x-go-name: Permissions title: AccountRole models the role of an account. type: object x-go-name: AccountRole x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/model adminAccountInfo: properties: account: $ref: '#/definitions/account' approved: description: Whether the account is currently approved. type: boolean x-go-name: Approved confirmed: description: Whether the account has confirmed their email address. type: boolean x-go-name: Confirmed created_at: description: When the account was first discovered. (ISO 8601 Datetime) example: "2021-07-30T09:20:25+00:00" type: string x-go-name: CreatedAt created_by_application_id: description: The ID of the application that created this account. type: string x-go-name: CreatedByApplicationID disabled: description: Whether the account is currently disabled. type: boolean x-go-name: Disabled domain: description: |- The domain of the account. Null for local accounts. example: example.org type: string x-go-name: Domain email: description: |- The email address associated with the account. Empty string for remote accounts or accounts with no known email address. example: someone@somewhere.com type: string x-go-name: Email id: description: The ID of the account in the database. example: 01GQ4PHNT622DQ9X95XQX4KKNR type: string x-go-name: ID invite_request: description: |- The reason given when signing up. Null if no reason / remote account. example: Pleaaaaaaaaaaaaaaase!! type: string x-go-name: InviteRequest invited_by_account_id: description: The ID of the account that invited this user type: string x-go-name: InvitedByAccountID ip: description: |- The IP address last used to login to this account. Null if not known. example: 192.0.2.1 type: string x-go-name: IP ips: description: |- All known IP addresses associated with this account. NOT IMPLEMENTED (will always be empty array). example: [] items: {} type: array x-go-name: IPs locale: description: The locale of the account. (ISO 639 Part 1 two-letter language code) example: en type: string x-go-name: Locale role: $ref: '#/definitions/accountRole' silenced: description: Whether the account is currently silenced type: boolean x-go-name: Silenced suspended: description: Whether the account is currently suspended. type: boolean x-go-name: Suspended username: description: The username of the account. example: dril type: string x-go-name: Username title: AdminAccountInfo models the admin view of an account's details. type: object x-go-name: AdminAccountInfo x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/model adminActionResponse: description: |- AdminActionResponse models the server response to an admin action. properties: action_id: description: Internal ID of the action. example: 01H9QG6TZ9W5P0402VFRVM17TH type: string x-go-name: ActionID type: object x-go-name: AdminActionResponse x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/model adminEmoji: properties: category: description: Used for sorting custom emoji in the picker. example: blobcats type: string x-go-name: Category content_type: description: The MIME content type of the emoji. example: image/png type: string x-go-name: ContentType disabled: description: True if this emoji has been disabled by an admin action. example: false type: boolean x-go-name: Disabled domain: description: The domain from which the emoji originated. Only defined for remote domains, otherwise key will not be set. example: example.org type: string x-go-name: Domain id: description: The ID of the emoji. example: 01GEM7SFDZ7GZNRXFVZ3X4E4N1 type: string x-go-name: ID shortcode: description: The name of the custom emoji. example: blobcat_uwu type: string x-go-name: Shortcode static_url: description: A link to a static copy of the custom emoji. example: https://example.org/fileserver/emojis/blogcat_uwu.png type: string x-go-name: StaticURL total_file_size: description: The total file size taken up by the emoji in bytes, including static and animated versions. example: 69420 format: int64 type: integer x-go-name: TotalFileSize updated_at: description: Time when the emoji image was last updated. example: "2022-10-05T09:21:26.419Z" type: string x-go-name: UpdatedAt uri: description: The ActivityPub URI of the emoji. example: https://example.org/emojis/016T5Q3SQKBT337DAKVSKNXXW1 type: string x-go-name: URI url: description: Web URL of the custom emoji. example: https://example.org/fileserver/emojis/blogcat_uwu.gif type: string x-go-name: URL visible_in_picker: description: Emoji is visible in the emoji picker of the instance. example: true type: boolean x-go-name: VisibleInPicker title: AdminEmoji models the admin view of a custom emoji. type: object x-go-name: AdminEmoji x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/model adminReport: properties: account: $ref: '#/definitions/adminAccountInfo' action_taken: description: Whether an action has been taken by an admin in response to this report. example: false type: boolean x-go-name: ActionTaken action_taken_at: description: |- If an action was taken, at what time was this done? (ISO 8601 Datetime) Will be null if not set / no action yet taken. example: "2021-07-30T09:20:25+00:00" type: string x-go-name: ActionTakenAt action_taken_by_account: $ref: '#/definitions/adminAccountInfo' action_taken_comment: description: |- If an action was taken, what comment was made by the admin on the taken action? Will be null if not set / no action yet taken. example: Account was suspended. type: string x-go-name: ActionTakenComment assigned_account: $ref: '#/definitions/adminAccountInfo' category: description: Under what category was this report created? example: spam type: string x-go-name: Category comment: description: |- Comment submitted when the report was created. Will be empty if no comment was submitted. example: This person has been harassing me. type: string x-go-name: Comment created_at: description: The date when this report was created (ISO 8601 Datetime). example: "2021-07-30T09:20:25+00:00" type: string x-go-name: CreatedAt forwarded: description: Bool to indicate that report should be federated to remote instance. example: true type: boolean x-go-name: Forwarded id: description: ID of the report. example: 01FBVD42CQ3ZEEVMW180SBX03B type: string x-go-name: ID rules: description: |- Array of rules that were broken according to this report. Will be empty if no rule IDs were submitted with the report. items: $ref: '#/definitions/instanceRule' type: array x-go-name: Rules statuses: description: |- Array of statuses that were submitted along with this report. Will be empty if no status IDs were submitted with the report. items: $ref: '#/definitions/status' type: array x-go-name: Statuses target_account: $ref: '#/definitions/adminAccountInfo' updated_at: description: Time of last action on this report (ISO 8601 Datetime). example: "2021-07-30T09:20:25+00:00" type: string x-go-name: UpdatedAt title: AdminReport models the admin view of a report. type: object x-go-name: AdminReport x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/model application: properties: client_id: description: Client ID associated with this application. type: string x-go-name: ClientID client_secret: description: Client secret associated with this application. type: string x-go-name: ClientSecret id: description: The ID of the application. example: 01FBVD42CQ3ZEEVMW180SBX03B type: string x-go-name: ID name: description: The name of the application. example: Tusky type: string x-go-name: Name redirect_uri: description: Post-authorization redirect URI for the application (OAuth2). example: https://example.org/callback?some=query type: string x-go-name: RedirectURI vapid_key: description: Push API key for this application. type: string x-go-name: VapidKey website: description: The website associated with the application (url) example: https://tusky.app type: string x-go-name: Website title: Application models an api application. type: object x-go-name: Application x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/model attachment: properties: blurhash: description: |- A hash computed by the BlurHash algorithm, for generating colorful preview thumbnails when media has not been downloaded yet. See https://github.com/woltapp/blurhash type: string x-go-name: Blurhash description: description: Alt text that describes what is in the media attachment. example: This is a picture of a kitten. type: string x-go-name: Description id: description: The ID of the attachment. example: 01FC31DZT1AYWDZ8XTCRWRBYRK type: string x-go-name: ID meta: $ref: '#/definitions/mediaMeta' preview_remote_url: description: |- The location of a scaled-down preview of the attachment on the remote server. Only defined for instances other than our own. example: https://some-other-server.org/attachments/small/ahhhhh.jpeg type: string x-go-name: PreviewRemoteURL preview_url: description: The location of a scaled-down preview of the attachment. example: https://example.org/fileserver/some_id/attachments/some_id/small/attachment.jpeg type: string x-go-name: PreviewURL remote_url: description: |- The location of the full-size original attachment on the remote server. Only defined for instances other than our own. example: https://some-other-server.org/attachments/original/ahhhhh.jpeg type: string x-go-name: RemoteURL text_url: description: |- A shorter URL for the attachment. In our case, we just give the URL again since we don't create smaller URLs. type: string x-go-name: TextURL type: description: The type of the attachment. example: image type: string x-go-name: Type url: description: The location of the original full-size attachment. example: https://example.org/fileserver/some_id/attachments/some_id/original/attachment.jpeg type: string x-go-name: URL title: Attachment models a media attachment. type: object x-go-name: Attachment x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/model card: properties: author_name: description: The author of the original resource. example: weewee@buzzfeed.com type: string x-go-name: AuthorName author_url: description: A link to the author of the original resource. example: https://buzzfeed.com/authors/weewee type: string x-go-name: AuthorURL blurhash: description: A hash computed by the BlurHash algorithm, for generating colorful preview thumbnails when media has not been downloaded yet. type: string x-go-name: Blurhash description: description: Description of preview. example: Is water wet? We're not sure. In this article, we ask an expert... type: string x-go-name: Description embed_url: description: Used for photo embeds, instead of custom html. type: string x-go-name: EmbedURL height: description: Height of preview, in pixels. format: int64 type: integer x-go-name: Height html: description: HTML to be used for generating the preview card. type: string x-go-name: HTML image: description: Preview thumbnail. example: https://example.org/fileserver/preview/thumb.jpg type: string x-go-name: Image provider_name: description: The provider of the original resource. example: Buzzfeed type: string x-go-name: ProviderName provider_url: description: A link to the provider of the original resource. example: https://buzzfeed.com type: string x-go-name: ProviderURL title: description: Title of linked resource. example: Buzzfeed - Is Water Wet? type: string x-go-name: Title type: description: The type of the preview card. example: link type: string x-go-name: Type url: description: Location of linked resource. example: https://buzzfeed.com/some/fuckin/buzzfeed/article type: string x-go-name: URL width: description: Width of preview, in pixels. format: int64 type: integer x-go-name: Width title: Card represents a rich preview card that is generated using OpenGraph tags from a URL. type: object x-go-name: Card x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/model conversation: description: |- Conversation represents a conversation with "direct message" visibility. properties: accounts: description: |- Participants in the conversation. If this is a conversation between no accounts (ie., a self-directed DM), this will include only the requesting account itself. Otherwise, it will include every other account in the conversation *except* the requester. items: $ref: '#/definitions/account' type: array x-go-name: Accounts id: description: Local database ID of the conversation. type: string x-go-name: ID last_status: $ref: '#/definitions/status' unread: description: Is the conversation currently marked as unread? type: boolean x-go-name: Unread type: object x-go-name: Conversation x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/model debugAPUrlResponse: description: |- DebugAPUrlResponse provides detailed debug information for an AP URL dereference request. properties: request_headers: additionalProperties: items: type: string type: array description: HTTP headers used in the outgoing request. type: object x-go-name: RequestHeaders request_url: description: Remote AP URL that was requested. type: string x-go-name: RequestURL response_body: description: |- Body returned from the remote instance. Will be stringified bytes; may be JSON, may be an error, may be both! type: string x-go-name: ResponseBody response_code: description: HTTP response code returned from the remote instance. format: int64 type: integer x-go-name: ResponseCode response_headers: additionalProperties: items: type: string type: array description: HTTP headers returned from the remote instance. type: object x-go-name: ResponseHeaders type: object x-go-name: DebugAPUrlResponse x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/model defaultPolicies: properties: direct: $ref: '#/definitions/interactionPolicy' private: $ref: '#/definitions/interactionPolicy' public: $ref: '#/definitions/interactionPolicy' unlisted: $ref: '#/definitions/interactionPolicy' title: Default interaction policies to use for new statuses by requesting account. type: object x-go-name: DefaultPolicies x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/model domain: description: Domain represents a remote domain properties: domain: description: The hostname of the domain. example: example.org type: string x-go-name: Domain public_comment: description: If the domain is blocked, what's the publicly-stated reason for the block. example: they smell type: string x-go-name: PublicComment silenced_at: description: Time at which this domain was silenced. Key will not be present on open domains. example: "2021-07-30T09:20:25+00:00" type: string x-go-name: SilencedAt suspended_at: description: Time at which this domain was suspended. Key will not be present on open domains. example: "2021-07-30T09:20:25+00:00" type: string x-go-name: SuspendedAt type: object x-go-name: Domain x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/model domainPermission: properties: created_at: description: Time at which the permission entry was created (ISO 8601 Datetime). example: "2021-07-30T09:20:25+00:00" type: string x-go-name: CreatedAt created_by: description: ID of the account that created this domain permission entry. example: 01FBW2758ZB6PBR200YPDDJK4C type: string x-go-name: CreatedBy domain: description: The hostname of the domain. example: example.org type: string x-go-name: Domain id: description: The ID of the domain permission entry. example: 01FBW21XJA09XYX51KV5JVBW0F readOnly: true type: string x-go-name: ID obfuscate: description: Obfuscate the domain name when serving this domain permission entry publicly. example: false type: boolean x-go-name: Obfuscate permission_type: description: |- Permission type of this entry (block, allow). Only set for domain permission drafts. type: string x-go-name: PermissionType private_comment: description: Private comment for this permission entry, visible to this instance's admins only. example: they are poopoo type: string x-go-name: PrivateComment public_comment: description: If the domain is blocked, what's the publicly-stated reason for the block. example: they smell type: string x-go-name: PublicComment silenced_at: description: Time at which this domain was silenced. Key will not be present on open domains. example: "2021-07-30T09:20:25+00:00" type: string x-go-name: SilencedAt subscription_id: description: If applicable, the ID of the subscription that caused this domain permission entry to be created. example: 01FBW25TF5J67JW3HFHZCSD23K type: string x-go-name: SubscriptionID suspended_at: description: Time at which this domain was suspended. Key will not be present on open domains. example: "2021-07-30T09:20:25+00:00" type: string x-go-name: SuspendedAt title: DomainPermission represents a permission applied to one domain (explicit block/allow). type: object x-go-name: DomainPermission x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/model domainPermissionSubscription: properties: adopt_orphans: description: 'If true, this domain permission subscription will "adopt" domain permissions which already exist on the instance, and which meet the following conditions: 1) they have no subscription ID (ie., they''re "orphaned") and 2) they are present in the subscribed list. Such orphaned domain permissions will be given this subscription''s subscription ID value.' example: false type: boolean x-go-name: AdoptOrphans as_draft: description: If true, domain permissions arising from this subscription will be created as drafts that must be approved by a moderator to take effect. If false, domain permissions from this subscription will come into force immediately. example: true type: boolean x-go-name: AsDraft content_type: description: MIME content type to use when parsing the permissions list. example: text/csv type: string x-go-name: ContentType count: description: Count of domain permission entries discovered at URI on last (successful) fetch. example: 53 format: uint64 readOnly: true type: integer x-go-name: Count created_at: description: Time at which the subscription was created (ISO 8601 Datetime). example: "2021-07-30T09:20:25+00:00" type: string x-go-name: CreatedAt created_by: description: ID of the account that created this subscription. example: 01FBW21XJA09XYX51KV5JVBW0F readOnly: true type: string x-go-name: CreatedBy error: description: If most recent fetch attempt failed, this field will contain an error message related to the fetch attempt. example: Oopsie doopsie, we made a fucky wucky. readOnly: true type: string x-go-name: Error fetch_password: description: (Optional) password to set for basic auth when doing a fetch of URI. example: admin123 type: string x-go-name: FetchPassword fetch_username: description: (Optional) username to set for basic auth when doing a fetch of URI. example: admin123 type: string x-go-name: FetchUsername fetched_at: description: Time of the most recent fetch attempt (successful or otherwise) (ISO 8601 Datetime). example: "2021-07-30T09:20:25+00:00" readOnly: true type: string x-go-name: FetchedAt id: description: The ID of the domain permission subscription. example: 01FBW21XJA09XYX51KV5JVBW0F readOnly: true type: string x-go-name: ID permission_type: description: The type of domain permission subscription (allow, block). example: block type: string x-go-name: PermissionType priority: description: Priority of this subscription compared to others of the same permission type. 0-255 (higher = higher priority). example: 100 format: uint8 type: integer x-go-name: Priority successfully_fetched_at: description: Time of the most recent successful fetch (ISO 8601 Datetime). example: "2021-07-30T09:20:25+00:00" readOnly: true type: string x-go-name: SuccessfullyFetchedAt title: description: Title of this subscription, as set by admin who created or updated it. example: really cool list of neato pals type: string x-go-name: Title uri: description: URI to call in order to fetch the permissions list. example: https://www.example.org/blocklists/list1.csv type: string x-go-name: URI title: DomainPermissionSubscription represents an auto-refreshing subscription to a list of domain permissions (allows, blocks). type: object x-go-name: DomainPermissionSubscription x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/model emoji: properties: category: description: Used for sorting custom emoji in the picker. example: blobcats type: string x-go-name: Category shortcode: description: The name of the custom emoji. example: blobcat_uwu type: string x-go-name: Shortcode static_url: description: A link to a static copy of the custom emoji. example: https://example.org/fileserver/emojis/blogcat_uwu.png type: string x-go-name: StaticURL url: description: Web URL of the custom emoji. example: https://example.org/fileserver/emojis/blogcat_uwu.gif type: string x-go-name: URL visible_in_picker: description: Emoji is visible in the emoji picker of the instance. example: true type: boolean x-go-name: VisibleInPicker title: Emoji represents a custom emoji. type: object x-go-name: Emoji x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/model emojiCategory: properties: id: description: The ID of the custom emoji category. type: string x-go-name: ID name: description: The name of the custom emoji category. type: string x-go-name: Name title: EmojiCategory represents a custom emoji category. type: object x-go-name: EmojiCategory x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/model field: properties: name: description: The key/name of this field. example: pronouns type: string x-go-name: Name value: description: The value of this field. example: they/them type: string x-go-name: Value verified_at: description: If this field has been verified, when did this occur? (ISO 8601 Datetime). example: "2021-07-30T09:20:25+00:00" type: string x-go-name: VerifiedAt title: Field represents a name/value pair to display on an account's profile. type: object x-go-name: Field x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/model filterContext: description: v1 and v2 filter APIs use the same set of contexts. title: FilterContext represents the context in which to apply a filter. type: string x-go-name: FilterContext x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/model filterKeyword: properties: id: description: The ID of the filter keyword entry in the database. type: string x-go-name: ID keyword: description: The text to be filtered. example: fnord type: string x-go-name: Keyword whole_word: description: Should the filter keyword consider word boundaries? example: true type: boolean x-go-name: WholeWord title: FilterKeyword represents text to filter within a v2 filter. type: object x-go-name: FilterKeyword x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/model filterResult: properties: filter: $ref: '#/definitions/filterV2' keyword_matches: description: The keywords within the filter that were matched. items: type: string type: array x-go-name: KeywordMatches status_matches: description: The status IDs within the filter that were matched. items: type: string type: array x-go-name: StatusMatches title: FilterResult is returned along with a filtered status to explain why it was filtered. type: object x-go-name: FilterResult x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/model filterStatus: properties: id: description: The ID of the filter status entry in the database. type: string x-go-name: ID phrase: description: The status ID to be filtered. type: string x-go-name: StatusID title: FilterStatus represents a single status to filter within a v2 filter. type: object x-go-name: FilterStatus x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/model filterV1: description: |- Note that v1 filters are mapped to v2 filters and v2 filter keywords internally. If whole_word is true, client app should do: Define ‘word constituent character’ for your app. In the official implementation, it’s [A-Za-z0-9_] in JavaScript, and [[:word:]] in Ruby. Ruby uses the POSIX character class (Letter | Mark | Decimal_Number | Connector_Punctuation). If the phrase starts with a word character, and if the previous character before matched range is a word character, its matched range should be treated to not match. If the phrase ends with a word character, and if the next character after matched range is a word character, its matched range should be treated to not match. Please check app/javascript/mastodon/selectors/index.js and app/lib/feed_manager.rb in the Mastodon source code for more details. properties: context: description: The contexts in which the filter should be applied. example: - home - public items: $ref: '#/definitions/filterContext' minItems: 1 type: array uniqueItems: true x-go-name: Context expires_at: description: When the filter should no longer be applied. Null if the filter does not expire. example: "2024-02-01T02:57:49Z" type: string x-go-name: ExpiresAt id: description: The ID of the filter in the database. type: string x-go-name: ID irreversible: description: Should matching entities be removed from the user's timelines/views, instead of hidden? example: false type: boolean x-go-name: Irreversible phrase: description: The text to be filtered. example: fnord type: string x-go-name: Phrase whole_word: description: Should the filter consider word boundaries? example: true type: boolean x-go-name: WholeWord title: FilterV1 represents a user-defined filter for determining which statuses should not be shown to the user. type: object x-go-name: FilterV1 x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/model filterV2: description: v2 filters have names and can include multiple phrases and status IDs to filter. properties: context: description: The contexts in which the filter should be applied. example: - home - public items: $ref: '#/definitions/filterContext' minItems: 1 type: array uniqueItems: true x-go-name: Context expires_at: description: When the filter should no longer be applied. Null if the filter does not expire. example: "2024-02-01T02:57:49Z" type: string x-go-name: ExpiresAt filter_action: $ref: '#/definitions/FilterAction' id: description: The ID of the filter in the database. type: string x-go-name: ID keywords: description: The keywords grouped under this filter. items: $ref: '#/definitions/filterKeyword' type: array x-go-name: Keywords statuses: description: The statuses grouped under this filter. items: $ref: '#/definitions/filterStatus' type: array x-go-name: Statuses title: description: The name of the filter. example: Linux Words type: string x-go-name: Title title: FilterV2 represents a user-defined filter for determining which statuses should not be shown to the user. type: object x-go-name: FilterV2 x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/model headerFilter: properties: created_at: description: Time at which the header filter was created (ISO 8601 Datetime). example: "2021-07-30T09:20:25+00:00" readOnly: true type: string x-go-name: CreatedAt created_by: description: The ID of the admin account that created this header filter. example: 01FBW2758ZB6PBR200YPDDJK4C readOnly: true type: string x-go-name: CreatedBy header: description: The HTTP header to match against. example: User-Agent type: string x-go-name: Header id: description: The ID of the header filter. example: 01FBW21XJA09XYX51KV5JVBW0F readOnly: true type: string x-go-name: ID regex: description: The header value matching regular expression. example: .*Firefox.* type: string x-go-name: Regex title: HeaderFilter represents a regex value filter applied to one particular HTTP header (allow / block). type: object x-go-name: HeaderFilter x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/model hostmeta: description: 'See: https://www.rfc-editor.org/rfc/rfc6415.html#section-3' properties: Link: items: $ref: '#/definitions/Link' type: array XMLNS: type: string XMLName: {} title: HostMeta represents a hostmeta document. type: object x-go-name: HostMeta x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/model instanceConfigurationAccounts: properties: allow_custom_css: description: Whether or not accounts on this instance are allowed to upload custom CSS for profiles and statuses. example: false type: boolean x-go-name: AllowCustomCSS max_featured_tags: description: |- The maximum number of featured tags allowed for each account. Currently not implemented, so this is hardcoded to 10. format: int64 type: integer x-go-name: MaxFeaturedTags max_profile_fields: description: |- The maximum number of profile fields allowed for each account. Currently not configurable, so this is hardcoded to 6. (https://github.com/superseriousbusiness/gotosocial/issues/1876) format: int64 type: integer x-go-name: MaxProfileFields title: InstanceConfigurationAccounts models instance account config parameters. type: object x-go-name: InstanceConfigurationAccounts x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/model instanceConfigurationMediaAttachments: properties: image_matrix_limit: description: |- Max allowed image size in pixels as height*width. GtS doesn't set a limit on this, but for compatibility we give Mastodon's 4096x4096px value here. example: 16777216 format: int64 type: integer x-go-name: ImageMatrixLimit image_size_limit: description: Max allowed image size in bytes example: 2097152 format: int64 type: integer x-go-name: ImageSizeLimit supported_mime_types: description: List of mime types that it's possible to upload to this instance. example: - image/jpeg - image/gif items: type: string type: array x-go-name: SupportedMimeTypes video_frame_rate_limit: description: Max allowed video frame rate. example: 60 format: int64 type: integer x-go-name: VideoFrameRateLimit video_matrix_limit: description: |- Max allowed video size in pixels as height*width. GtS doesn't set a limit on this, but for compatibility we give Mastodon's 4096x4096px value here. example: 16777216 format: int64 type: integer x-go-name: VideoMatrixLimit video_size_limit: description: Max allowed video size in bytes example: 10485760 format: int64 type: integer x-go-name: VideoSizeLimit title: InstanceConfigurationMediaAttachments models instance media attachment config parameters. type: object x-go-name: InstanceConfigurationMediaAttachments x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/model instanceConfigurationPolls: properties: max_characters_per_option: description: Number of characters allowed per option in the poll. example: 50 format: int64 type: integer x-go-name: MaxCharactersPerOption max_expiration: description: Maximum expiration time of the poll in seconds. example: 2629746 format: int64 type: integer x-go-name: MaxExpiration max_options: description: Number of options permitted in a poll on this instance. example: 4 format: int64 type: integer x-go-name: MaxOptions min_expiration: description: Minimum expiration time of the poll in seconds. example: 300 format: int64 type: integer x-go-name: MinExpiration title: InstanceConfigurationPolls models instance poll config parameters. type: object x-go-name: InstanceConfigurationPolls x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/model instanceConfigurationStatuses: properties: characters_reserved_per_url: description: Amount of characters clients should assume a url takes up. example: 25 format: int64 type: integer x-go-name: CharactersReservedPerURL max_characters: description: Maximum allowed length of a post on this instance, in characters. example: 5000 format: int64 type: integer x-go-name: MaxCharacters max_media_attachments: description: Max number of attachments allowed on a status. example: 4 format: int64 type: integer x-go-name: MaxMediaAttachments supported_mime_types: description: List of mime types that it's possible to use for statuses on this instance. example: - text/plain - text/markdown items: type: string type: array x-go-name: SupportedMimeTypes title: InstanceConfigurationStatuses models instance status config parameters. type: object x-go-name: InstanceConfigurationStatuses x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/model instanceRule: properties: id: type: string x-go-name: ID text: type: string x-go-name: Text title: InstanceRule represents a single instance rule. type: object x-go-name: InstanceRule x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/model instanceV1: properties: account_domain: description: |- The domain of accounts on this instance. This will not necessarily be the same as simply the Host part of the URI. example: example.org type: string x-go-name: AccountDomain approval_required: description: New account registrations require admin approval. type: boolean x-go-name: ApprovalRequired configuration: $ref: '#/definitions/instanceV1Configuration' contact_account: $ref: '#/definitions/account' custom_css: description: Custom CSS for the instance. type: string x-go-name: CustomCSS debug: description: Whether or not instance is running in DEBUG mode. Omitted if false. type: boolean x-go-name: Debug description: description: |- Description of the instance. Should be HTML formatted, but might be plaintext. This should be displayed on the 'about' page for an instance. type: string x-go-name: Description description_text: description: Raw (unparsed) version of description. type: string x-go-name: DescriptionText email: description: An email address that may be used for inquiries. example: admin@example.org type: string x-go-name: Email invites_enabled: description: Invites are enabled on this instance. type: boolean x-go-name: InvitesEnabled languages: description: Primary language of the instance. example: - en items: type: string type: array x-go-name: Languages max_toot_chars: description: |- Maximum allowed length of a post on this instance, in characters. This is provided for compatibility with Tusky and other apps. example: 5000 format: uint64 type: integer x-go-name: MaxTootChars registrations: description: New account registrations are enabled on this instance. type: boolean x-go-name: Registrations rules: description: An itemized list of rules for this instance. items: $ref: '#/definitions/instanceRule' type: array x-go-name: Rules short_description: description: |- A shorter description of the instance. Should be HTML formatted, but might be plaintext. This should be displayed on the instance splash/landing page. type: string x-go-name: ShortDescription short_description_text: description: Raw (unparsed) version of short description. type: string x-go-name: ShortDescriptionText stats: additionalProperties: format: int64 type: integer description: |- Statistics about the instance: number of posts, accounts, etc. Values are pointers because we don't want to skip 0 values when rendering stats via web templates. type: object x-go-name: Stats terms: description: Terms and conditions for accounts on this instance. type: string x-go-name: Terms terms_text: description: Raw (unparsed) version of terms. type: string x-go-name: TermsRaw thumbnail: description: URL of the instance avatar/banner image. example: https://example.org/files/instance/thumbnail.jpeg type: string x-go-name: Thumbnail thumbnail_description: description: Description of the instance thumbnail. example: picture of a cute lil' friendly sloth type: string x-go-name: ThumbnailDescription thumbnail_static: description: URL of the static instance avatar/banner image. example: https://example.org/files/instance/static/thumbnail.webp type: string x-go-name: ThumbnailStatic thumbnail_static_type: description: MIME type of the static instance thumbnail. example: image/webp type: string x-go-name: ThumbnailStaticType thumbnail_type: description: MIME type of the instance thumbnail. example: image/png type: string x-go-name: ThumbnailType title: description: The title of the instance. example: GoToSocial Example Instance type: string x-go-name: Title uri: description: The URI of the instance. example: https://gts.example.org type: string x-go-name: URI urls: $ref: '#/definitions/instanceV1URLs' version: description: |- The version of GoToSocial installed on the instance. This will contain at least a semantic version number. It may also contain, after a space, the short git commit ID of the running software. example: 0.1.1 cb85f65 type: string x-go-name: Version title: InstanceV1 models information about this instance. type: object x-go-name: InstanceV1 x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/model instanceV1Configuration: properties: accounts: $ref: '#/definitions/instanceConfigurationAccounts' emojis: $ref: '#/definitions/InstanceConfigurationEmojis' media_attachments: $ref: '#/definitions/instanceConfigurationMediaAttachments' oidc_enabled: description: True if instance is running with OIDC as auth/identity backend, else omitted. type: boolean x-go-name: OIDCEnabled polls: $ref: '#/definitions/instanceConfigurationPolls' statuses: $ref: '#/definitions/instanceConfigurationStatuses' title: InstanceV1Configuration models instance configuration parameters. type: object x-go-name: InstanceV1Configuration x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/model instanceV1URLs: properties: streaming_api: description: Websockets address for status and notification streaming. example: wss://example.org type: string x-go-name: StreamingAPI title: InstanceV1URLs models instance-relevant URLs for client application consumption. type: object x-go-name: InstanceV1URLs x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/model instanceV2: properties: account_domain: description: |- The domain of accounts on this instance. This will not necessarily be the same as domain. example: example.org type: string x-go-name: AccountDomain configuration: $ref: '#/definitions/instanceV2Configuration' contact: $ref: '#/definitions/instanceV2Contact' custom_css: description: Instance Custom Css type: string x-go-name: CustomCSS debug: description: Whether or not instance is running in DEBUG mode. Omitted if false. type: boolean x-go-name: Debug description: description: |- Description of the instance. Should be HTML formatted, but might be plaintext. This should be displayed on the 'about' page for an instance. type: string x-go-name: Description description_text: description: Raw (unparsed) version of description. type: string x-go-name: DescriptionText domain: description: The domain of the instance. example: gts.example.org type: string x-go-name: Domain languages: description: Primary languages of the instance + moderators/admins. example: - en items: type: string type: array x-go-name: Languages registrations: $ref: '#/definitions/instanceV2Registrations' rules: description: An itemized list of rules for this instance. items: $ref: '#/definitions/instanceRule' type: array x-go-name: Rules source_url: description: The URL for the source code of the software running on this instance, in keeping with AGPL license requirements. example: https://github.com/superseriousbusiness/gotosocial type: string x-go-name: SourceURL terms: description: Terms and conditions for accounts on this instance. type: string x-go-name: Terms terms_text: description: Raw (unparsed) version of terms. type: string x-go-name: TermsText thumbnail: $ref: '#/definitions/instanceV2Thumbnail' title: description: The title of the instance. example: GoToSocial Example Instance type: string x-go-name: Title usage: $ref: '#/definitions/instanceV2Usage' version: description: |- The version of GoToSocial installed on the instance. This will contain at least a semantic version number. It may also contain, after a space, the short git commit ID of the running software. example: 0.1.1 cb85f65 type: string x-go-name: Version title: InstanceV2 models information about this instance. type: object x-go-name: InstanceV2 x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/model instanceV2Configuration: properties: accounts: $ref: '#/definitions/instanceConfigurationAccounts' emojis: $ref: '#/definitions/InstanceConfigurationEmojis' media_attachments: $ref: '#/definitions/instanceConfigurationMediaAttachments' oidc_enabled: description: True if instance is running with OIDC as auth/identity backend, else omitted. type: boolean x-go-name: OIDCEnabled polls: $ref: '#/definitions/instanceConfigurationPolls' statuses: $ref: '#/definitions/instanceConfigurationStatuses' translation: $ref: '#/definitions/instanceV2ConfigurationTranslation' urls: $ref: '#/definitions/instanceV2URLs' title: Configured values and limits for this instance. type: object x-go-name: InstanceV2Configuration x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/model instanceV2ConfigurationTranslation: properties: enabled: description: |- Whether the Translations API is available on this instance. Not implemented so this value is always false. type: boolean x-go-name: Enabled title: Hints related to translation. type: object x-go-name: InstanceV2ConfigurationTranslation x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/model instanceV2Contact: properties: account: $ref: '#/definitions/account' email: description: |- An email address that can be messaged regarding inquiries or issues. Empty string if no email address set. example: someone@example.org type: string x-go-name: Email title: Hints related to contacting a representative of the instance. type: object x-go-name: InstanceV2Contact x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/model instanceV2Registrations: properties: approval_required: description: Whether registrations require moderator approval. example: true type: boolean x-go-name: ApprovalRequired enabled: description: Whether registrations are enabled. example: false type: boolean x-go-name: Enabled message: description: |- A custom message (html string) to be shown when registrations are closed. Value will be null if no message is set. example:

Registrations are currently closed on example.org because of spam bots!

type: string x-go-name: Message title: Information about registering for this instance. type: object x-go-name: InstanceV2Registrations x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/model instanceV2Thumbnail: properties: blurhash: description: |- A hash computed by the BlurHash algorithm, for generating colorful preview thumbnails when media has not been downloaded yet. Key/value not set if no blurhash available. example: UeKUpFxuo~R%0nW;WCnhF6RjaJt757oJodS$ type: string x-go-name: Blurhash static_url: description: StaticURL version of the thumbnail image. example: https://example.org/fileserver/01BPSX2MKCRVMD4YN4D71G9CP5/attachment/static/01H88X0KQ2DFYYDSWYP93VDJZA.webp type: string x-go-name: StaticURL thumbnail_description: description: |- Description of the instance thumbnail. Key/value not set if no description available. example: picture of a cute lil' friendly sloth type: string x-go-name: Description thumbnail_static_type: description: |- MIME type of the instance thumbnail. Key/value not set if thumbnail image type unknown. example: image/png type: string x-go-name: StaticType thumbnail_type: description: |- MIME type of the instance thumbnail. Key/value not set if thumbnail image type unknown. example: image/png type: string x-go-name: Type url: description: The URL for the thumbnail image. example: https://example.org/fileserver/01BPSX2MKCRVMD4YN4D71G9CP5/attachment/original/01H88X0KQ2DFYYDSWYP93VDJZA.png type: string x-go-name: URL versions: $ref: '#/definitions/instanceV2ThumbnailVersions' title: An image used to represent this instance. type: object x-go-name: InstanceV2Thumbnail x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/model instanceV2ThumbnailVersions: properties: '@1x': description: |- The URL for the thumbnail image at 1x resolution. Key/value not set if scaled versions not available. type: string x-go-name: Size1URL '@2x': description: |- The URL for the thumbnail image at 2x resolution. Key/value not set if scaled versions not available. type: string x-go-name: Size2URL title: Links to scaled resolution images, for high DPI screens. type: object x-go-name: InstanceV2ThumbnailVersions x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/model instanceV2URLs: properties: streaming: description: Websockets address for status and notification streaming. example: wss://example.org type: string x-go-name: Streaming title: InstanceV2URLs models instance-relevant URLs for client application consumption. type: object x-go-name: InstanceV2URLs x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/model instanceV2Usage: properties: users: $ref: '#/definitions/instanceV2Users' title: Usage data for this instance. type: object x-go-name: InstanceV2Usage x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/model instanceV2Users: properties: active_month: description: |- The number of active users in the past 4 weeks. Currently not implemented: will always be 0. example: 0 format: int64 type: integer x-go-name: ActiveMonth title: Usage data related to users on this instance. type: object x-go-name: InstanceV2Users x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/model interactionPolicy: properties: can_favourite: $ref: '#/definitions/interactionPolicyRules' can_reblog: $ref: '#/definitions/interactionPolicyRules' can_reply: $ref: '#/definitions/interactionPolicyRules' title: Interaction policy of a status. type: object x-go-name: InteractionPolicy x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/model interactionPolicyRules: properties: always: description: Policy entries for accounts that can always do this type of interaction. items: $ref: '#/definitions/interactionPolicyValue' type: array x-go-name: Always with_approval: description: Policy entries for accounts that require approval to do this type of interaction. items: $ref: '#/definitions/interactionPolicyValue' type: array x-go-name: WithApproval title: Rules for one interaction type. type: object x-go-name: PolicyRules x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/model interactionPolicyValue: description: |- It can be EITHER one of the internal keywords listed below, OR a full-fledged ActivityPub URI of an Actor, like "https://example.org/users/some_user". Internal keywords: public - Public, aka anyone who can see the status according to its visibility level. followers - Followers of the status author. following - People followed by the status author. mutuals - Mutual follows of the status author (reserved, unused). mentioned - Accounts mentioned in, or replied-to by, the status. author - The status author themself. me - If request was made with an authorized user, "me" represents the user who made the request and is now looking at this interaction policy. title: One interaction policy entry for a status. type: string x-go-name: PolicyValue x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/model interactionRequest: properties: accepted_at: description: The timestamp that the interaction request was accepted (ISO 8601 Datetime). Field omitted if request not accepted (yet). type: string x-go-name: AcceptedAt account: $ref: '#/definitions/account' created_at: description: The timestamp of the interaction request (ISO 8601 Datetime) type: string x-go-name: CreatedAt id: description: The id of the interaction request in the database. type: string x-go-name: ID rejected_at: description: The timestamp that the interaction request was rejected (ISO 8601 Datetime). Field omitted if request not rejected (yet). type: string x-go-name: RejectedAt reply: $ref: '#/definitions/status' status: $ref: '#/definitions/status' type: description: |- The type of interaction that this interaction request pertains to. `favourite` - Someone favourited a status. `reply` - Someone replied to a status. `reblog` - Someone reblogged / boosted a status. type: string x-go-name: Type uri: description: URI of the Accept or Reject. Only set if accepted_at or rejected_at is set, else omitted. type: string x-go-name: URI title: InteractionRequest represents a pending, approved, or rejected interaction of type favourite, reply, or reblog. type: object x-go-name: InteractionRequest x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/model list: properties: exclusive: description: |- Exclusive setting for this list. If true, hide posts from members of this list from your home timeline. type: boolean x-go-name: Exclusive id: description: The ID of the list. type: string x-go-name: ID replies_policy: description: |- RepliesPolicy for this list. followed = Show replies to any followed user list = Show replies to members of the list none = Show replies to no one type: string x-go-name: RepliesPolicy title: description: The user-defined title of the list. type: string x-go-name: Title title: List represents a user-created list of accounts that the user follows. type: object x-go-name: List x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/model markers: properties: home: $ref: '#/definitions/TimelineMarker' notifications: $ref: '#/definitions/TimelineMarker' title: Marker represents the last read position within a user's timelines. type: object x-go-name: Marker x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/model mediaDimensions: properties: aspect: description: |- Aspect ratio of the media. Equal to width / height. example: 1.777777778 format: float type: number x-go-name: Aspect bitrate: description: Bitrate of the media in bits per second. example: 1000000 format: uint64 type: integer x-go-name: Bitrate duration: description: |- Duration of the media in seconds. Only set for video and audio. example: 5.43 format: float type: number x-go-name: Duration frame_rate: description: |- Framerate of the media. Only set for video and gifs. example: "30" type: string x-go-name: FrameRate height: description: |- Height of the media in pixels. Not set for audio. example: 1080 format: int64 type: integer x-go-name: Height size: description: |- Size of the media, in the format `[width]x[height]`. Not set for audio. example: 1920x1080 type: string x-go-name: Size width: description: |- Width of the media in pixels. Not set for audio. example: 1920 format: int64 type: integer x-go-name: Width title: MediaDimensions models detailed properties of a piece of media. type: object x-go-name: MediaDimensions x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/model mediaFocus: properties: x: description: |- x position of the focus should be between -1 and 1 format: float type: number x-go-name: X "y": description: |- y position of the focus should be between -1 and 1 format: float type: number x-go-name: "Y" title: MediaFocus models the focal point of a piece of media. type: object 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. properties: focus: $ref: '#/definitions/mediaFocus' original: $ref: '#/definitions/mediaDimensions' small: $ref: '#/definitions/mediaDimensions' title: MediaMeta models media metadata. type: object x-go-name: MediaMeta x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/model mutedAccount: properties: acct: description: |- The account URI as discovered via webfinger. Equal to username for local users, or username@domain for remote users. example: some_user@example.org type: string x-go-name: Acct avatar: description: Web location of the account's avatar. example: https://example.org/media/some_user/avatar/original/avatar.jpeg type: string x-go-name: Avatar avatar_description: description: Description of this account's avatar, for alt text. example: A cute drawing of a smiling sloth. type: string x-go-name: AvatarDescription avatar_media_id: description: |- Database ID of the media attachment for this account's avatar image. Omitted if no avatar uploaded for this account (ie., default avatar). example: 01JAJ3XCD66K3T99JZESCR137W type: string x-go-name: AvatarMediaID avatar_static: description: |- Web location of a static version of the account's avatar. Only relevant when the account's main avatar is a video or a gif. example: https://example.org/media/some_user/avatar/static/avatar.png type: string x-go-name: AvatarStatic bot: description: Account identifies as a bot. type: boolean x-go-name: Bot created_at: description: When the account was created (ISO 8601 Datetime). example: "2021-07-30T09:20:25+00:00" type: string x-go-name: CreatedAt custom_css: description: CustomCSS to include when rendering this account's profile or statuses. type: string x-go-name: CustomCSS discoverable: description: Account has opted into discovery features. type: boolean x-go-name: Discoverable display_name: description: The account's display name. example: big jeff (he/him) type: string x-go-name: DisplayName emojis: description: |- Array of custom emojis used in this account's note or display name. Empty for blocked accounts. items: $ref: '#/definitions/emoji' type: array x-go-name: Emojis enable_rss: description: |- Account has enabled RSS feed. Key/value omitted if false. type: boolean x-go-name: EnableRSS fields: description: |- Additional metadata attached to this account's profile. Empty for blocked accounts. items: $ref: '#/definitions/field' type: array x-go-name: Fields followers_count: description: Number of accounts following this account, according to our instance. format: int64 type: integer x-go-name: FollowersCount following_count: description: Number of account's followed by this account, according to our instance. format: int64 type: integer x-go-name: FollowingCount header: description: Web location of the account's header image. example: https://example.org/media/some_user/header/original/header.jpeg type: string x-go-name: Header header_description: description: Description of this account's header, for alt text. example: A sunlit field with purple flowers. type: string x-go-name: HeaderDescription header_media_id: description: |- Database ID of the media attachment for this account's header image. Omitted if no header uploaded for this account (ie., default header). example: 01JAJ3XCD66K3T99JZESCR137W type: string x-go-name: HeaderMediaID header_static: description: |- Web location of a static version of the account's header. Only relevant when the account's main header is a video or a gif. example: https://example.org/media/some_user/header/static/header.png type: string x-go-name: HeaderStatic hide_collections: description: |- Account has opted to hide their followers/following collections. Key/value omitted if false. type: boolean x-go-name: HideCollections id: description: The account id. example: 01FBVD42CQ3ZEEVMW180SBX03B type: string x-go-name: ID last_status_at: description: When the account's most recent status was posted (ISO 8601 Date). example: "2021-07-30" type: string x-go-name: LastStatusAt locked: description: Account manually approves follow requests. type: boolean x-go-name: Locked moved: $ref: '#/definitions/account' mute_expires_at: description: |- If this account has been muted, when will the mute expire (ISO 8601 Datetime). If the mute is indefinite, this will be null. example: "2021-07-30T09:20:25+00:00" type: string x-go-name: MuteExpiresAt note: description: Bio/description of this account. type: string x-go-name: Note role: $ref: '#/definitions/accountRole' roles: description: |- Roles lists the public roles of the account on this instance. Unlike Role, this is always available, but never includes permissions details. Key/value omitted for remote accounts. items: $ref: '#/definitions/accountDisplayRole' type: array x-go-name: Roles source: $ref: '#/definitions/Source' statuses_count: description: Number of statuses posted by this account, according to our instance. format: int64 type: integer x-go-name: StatusesCount suspended: description: Account has been suspended by our instance. type: boolean x-go-name: Suspended theme: description: Filename of user-selected CSS theme to include when rendering this account's profile or statuses. Eg., `blurple-light.css`. type: string x-go-name: Theme url: description: Web location of the account's profile page. example: https://example.org/@some_user type: string x-go-name: URL username: description: The username of the account, not including domain. example: some_user type: string x-go-name: Username title: MutedAccount extends Account with a field used only by the muted user list. type: object x-go-name: MutedAccount x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/model nodeinfo: description: 'See: https://nodeinfo.diaspora.software/schema.html' properties: metadata: additionalProperties: {} description: Free form key value pairs for software specific values. Clients should not rely on any specific key present. type: object x-go-name: Metadata openRegistrations: description: Whether this server allows open self-registration. example: false type: boolean x-go-name: OpenRegistrations protocols: description: The protocols supported on this server. items: type: string type: array x-go-name: Protocols services: $ref: '#/definitions/NodeInfoServices' software: $ref: '#/definitions/NodeInfoSoftware' usage: $ref: '#/definitions/NodeInfoUsage' version: description: The schema version example: "2.0" type: string x-go-name: Version title: Nodeinfo represents a version 2.1 or version 2.0 nodeinfo schema. type: object x-go-name: Nodeinfo x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/model notification: properties: account: $ref: '#/definitions/account' created_at: description: The timestamp of the notification (ISO 8601 Datetime) type: string x-go-name: CreatedAt id: description: The id of the notification in the database. type: string x-go-name: ID status: $ref: '#/definitions/status' type: description: |- The type of event that resulted in the notification. follow = Someone followed you. `account` will be set. follow_request = Someone requested to follow you. `account` will be set. mention = Someone mentioned you in their status. `status` will be set. `account` will be set. reblog = Someone boosted one of your statuses. `status` will be set. `account` will be set. favourite = Someone favourited one of your statuses. `status` will be set. `account` will be set. poll = A poll you have voted in or created has ended. `status` will be set. `account` will be set. status = Someone you enabled notifications for has posted a status. `status` will be set. `account` will be set. admin.sign_up = Someone has signed up for a new account on the instance. `account` will be set. type: string x-go-name: Type title: Notification represents a notification of an event relevant to the user. type: object x-go-name: Notification x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/model oauthToken: properties: access_token: description: Access token used for authorization. type: string x-go-name: AccessToken created_at: description: When the OAuth token was generated (UNIX timestamp seconds). example: 1627644520 format: int64 type: integer x-go-name: CreatedAt scope: description: OAuth scopes granted by this token, space-separated. example: read write admin type: string x-go-name: Scope token_type: description: OAuth token type. Will always be 'Bearer'. example: bearer type: string x-go-name: TokenType title: Token represents an OAuth token used for authenticating with the GoToSocial API and performing actions. type: object x-go-name: Token x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/model poll: properties: emojis: description: Custom emoji to be used for rendering poll options. items: $ref: '#/definitions/emoji' type: array x-go-name: Emojis expired: description: Is the poll currently expired? type: boolean x-go-name: Expired expires_at: description: When the poll ends. (ISO 8601 Datetime). type: string x-go-name: ExpiresAt id: description: The ID of the poll in the database. example: 01FBYKMD1KBMJ0W6JF1YZ3VY5D type: string x-go-name: ID multiple: description: Does the poll allow multiple-choice answers? type: boolean x-go-name: Multiple options: description: Possible answers for the poll. items: $ref: '#/definitions/pollOption' type: array x-go-name: Options own_votes: description: |- When called with a user token, which options has the authorized user chosen? Contains an array of index values for options. Omitted when no user token provided. items: format: int64 type: integer type: array x-go-name: OwnVotes voted: description: |- When called with a user token, has the authorized user voted? Omitted when no user token provided. type: boolean x-go-name: Voted voters_count: description: How many unique accounts have voted on a multiple-choice poll. format: int64 type: integer x-go-name: VotersCount votes_count: description: How many votes have been received. format: int64 type: integer x-go-name: VotesCount title: Poll represents a poll attached to a status. type: object x-go-name: Poll x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/model pollOption: properties: title: description: The text value of the poll option. String. type: string x-go-name: Title votes_count: description: The number of received votes for this option. format: int64 type: integer x-go-name: VotesCount title: PollOption represents the current vote counts for different poll options. type: object x-go-name: PollOption x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/model report: properties: action_taken: description: Whether an action has been taken by an admin in response to this report. example: false type: boolean x-go-name: ActionTaken action_taken_at: description: |- If an action was taken, at what time was this done? (ISO 8601 Datetime) Will be null if not set / no action yet taken. example: "2021-07-30T09:20:25+00:00" type: string x-go-name: ActionTakenAt action_taken_comment: description: |- If an action was taken, what comment was made by the admin on the taken action? Will be null if not set / no action yet taken. example: Account was suspended. type: string x-go-name: ActionTakenComment category: description: Under what category was this report created? example: spam type: string x-go-name: Category comment: description: |- Comment submitted when the report was created. Will be empty if no comment was submitted. example: This person has been harassing me. type: string x-go-name: Comment created_at: description: The date when this report was created (ISO 8601 Datetime). example: "2021-07-30T09:20:25+00:00" type: string x-go-name: CreatedAt forwarded: description: Bool to indicate that report should be federated to remote instance. example: true type: boolean x-go-name: Forwarded id: description: ID of the report. example: 01FBVD42CQ3ZEEVMW180SBX03B type: string x-go-name: ID rule_ids: description: |- Array of rule IDs that were submitted along with this report. Will be empty if no rule IDs were submitted. example: - 01GPBN5YDY6JKBWE44H7YQBDCQ - 01GPBN65PDWSBPWVDD0SQCFFY3 items: type: string type: array x-go-name: RuleIDs status_ids: description: |- Array of IDs of statuses that were submitted along with this report. Will be empty if no status IDs were submitted. example: - 01GPBN5YDY6JKBWE44H7YQBDCQ - 01GPBN65PDWSBPWVDD0SQCFFY3 items: type: string type: array x-go-name: StatusIDs target_account: $ref: '#/definitions/account' title: Report models a moderation report submitted to the instance, either via the client API or via the federated API. type: object x-go-name: Report x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/model searchResult: properties: accounts: items: $ref: '#/definitions/account' type: array x-go-name: Accounts hashtags: description: Slice of strings if api v1, slice of tags if api v2. items: {} type: array x-go-name: Hashtags statuses: items: $ref: '#/definitions/status' type: array x-go-name: Statuses title: SearchResult models a search result. type: object x-go-name: SearchResult x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/model status: properties: account: $ref: '#/definitions/account' application: $ref: '#/definitions/application' bookmarked: description: This status has been bookmarked by the account viewing it. type: boolean x-go-name: Bookmarked card: $ref: '#/definitions/card' content: description: The content of this status. Should be HTML, but might also be plaintext in some cases. example:

Hey this is a status!

type: string x-go-name: Content created_at: description: The date when this status was created (ISO 8601 Datetime). example: "2021-07-30T09:20:25+00:00" type: string x-go-name: CreatedAt edited_at: description: Timestamp of when the status was last edited (ISO 8601 Datetime). example: "2021-07-30T09:20:25+00:00" type: string x-go-name: EditedAt emojis: description: Custom emoji to be used when rendering status content. items: $ref: '#/definitions/emoji' type: array x-go-name: Emojis favourited: description: This status has been favourited by the account viewing it. type: boolean x-go-name: Favourited favourites_count: description: Number of favourites/likes this status has received, according to our instance. format: int64 type: integer x-go-name: FavouritesCount filtered: description: A list of filters that matched this status and why they matched, if there are any such filters. items: $ref: '#/definitions/filterResult' type: array x-go-name: Filtered id: description: ID of the status. example: 01FBVD42CQ3ZEEVMW180SBX03B type: string x-go-name: ID in_reply_to_account_id: description: ID of the account being replied to. example: 01FBVD42CQ3ZEEVMW180SBX03B type: string x-go-name: InReplyToAccountID in_reply_to_id: description: ID of the status being replied to. example: 01FBVD42CQ3ZEEVMW180SBX03B type: string x-go-name: InReplyToID interaction_policy: $ref: '#/definitions/interactionPolicy' language: description: |- Primary language of this status (ISO 639 Part 1 two-letter language code). Will be null if language is not known. example: en type: string x-go-name: Language local_only: description: Set to "true" if status is not federated, ie., a "local only" status; omitted from response otherwise. type: boolean x-go-name: LocalOnly media_attachments: description: Media that is attached to this status. items: $ref: '#/definitions/attachment' type: array x-go-name: MediaAttachments mentions: description: Mentions of users within the status content. items: $ref: '#/definitions/Mention' type: array x-go-name: Mentions muted: description: Replies to this status have been muted by the account viewing it. type: boolean x-go-name: Muted pinned: description: This status has been pinned by the account viewing it (only relevant for your own statuses). type: boolean x-go-name: Pinned poll: $ref: '#/definitions/poll' reblog: $ref: '#/definitions/statusReblogged' reblogged: description: This status has been boosted/reblogged by the account viewing it. type: boolean x-go-name: Reblogged reblogs_count: description: Number of times this status has been boosted/reblogged, according to our instance. format: int64 type: integer x-go-name: ReblogsCount replies_count: description: Number of replies to this status, according to our instance. format: int64 type: integer x-go-name: RepliesCount sensitive: description: Status contains sensitive content. example: false type: boolean x-go-name: Sensitive spoiler_text: description: Subject, summary, or content warning for the status. example: warning nsfw type: string x-go-name: SpoilerText tags: description: Hashtags used within the status content. items: $ref: '#/definitions/tag' type: array x-go-name: Tags text: description: |- Plain-text source of a status. Returned instead of content when status is deleted, so the user may redraft from the source text without the client having to reverse-engineer the original text from the HTML content. type: string x-go-name: Text uri: description: ActivityPub URI of the status. Equivalent to the status's activitypub ID. example: https://example.org/users/some_user/statuses/01FBVD42CQ3ZEEVMW180SBX03B type: string x-go-name: URI url: description: The status's publicly available web URL. This link will only work if the visibility of the status is 'public'. example: https://example.org/@some_user/statuses/01FBVD42CQ3ZEEVMW180SBX03B type: string x-go-name: URL visibility: description: Visibility of this status. example: unlisted type: string x-go-name: Visibility title: Status models a status or post. type: object x-go-name: Status x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/model statusEdit: description: |- StatusEdit represents one historical revision of a status, containing partial information about the state of the status at that revision. properties: account: $ref: '#/definitions/account' content: description: |- The content of this status at this revision. Should be HTML, but might also be plaintext in some cases. example:

Hey this is a status!

type: string x-go-name: Content created_at: description: The date when this revision was created (ISO 8601 Datetime). example: "2021-07-30T09:20:25+00:00" type: string x-go-name: CreatedAt emojis: description: Custom emoji to be used when rendering status content. items: $ref: '#/definitions/emoji' type: array x-go-name: Emojis media_attachments: description: Media that is attached to this status. items: $ref: '#/definitions/attachment' type: array x-go-name: MediaAttachments poll: $ref: '#/definitions/poll' sensitive: description: Status marked sensitive at this revision. example: false type: boolean x-go-name: Sensitive spoiler_text: description: Subject, summary, or content warning for the status at this revision. example: warning nsfw type: string x-go-name: SpoilerText type: object x-go-name: StatusEdit x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/model statusReblogged: properties: account: $ref: '#/definitions/account' application: $ref: '#/definitions/application' bookmarked: description: This status has been bookmarked by the account viewing it. type: boolean x-go-name: Bookmarked card: $ref: '#/definitions/card' content: description: The content of this status. Should be HTML, but might also be plaintext in some cases. example:

Hey this is a status!

type: string x-go-name: Content created_at: description: The date when this status was created (ISO 8601 Datetime). example: "2021-07-30T09:20:25+00:00" type: string x-go-name: CreatedAt edited_at: description: Timestamp of when the status was last edited (ISO 8601 Datetime). example: "2021-07-30T09:20:25+00:00" type: string x-go-name: EditedAt emojis: description: Custom emoji to be used when rendering status content. items: $ref: '#/definitions/emoji' type: array x-go-name: Emojis favourited: description: This status has been favourited by the account viewing it. type: boolean x-go-name: Favourited favourites_count: description: Number of favourites/likes this status has received, according to our instance. format: int64 type: integer x-go-name: FavouritesCount filtered: description: A list of filters that matched this status and why they matched, if there are any such filters. items: $ref: '#/definitions/filterResult' type: array x-go-name: Filtered id: description: ID of the status. example: 01FBVD42CQ3ZEEVMW180SBX03B type: string x-go-name: ID in_reply_to_account_id: description: ID of the account being replied to. example: 01FBVD42CQ3ZEEVMW180SBX03B type: string x-go-name: InReplyToAccountID in_reply_to_id: description: ID of the status being replied to. example: 01FBVD42CQ3ZEEVMW180SBX03B type: string x-go-name: InReplyToID interaction_policy: $ref: '#/definitions/interactionPolicy' language: description: |- Primary language of this status (ISO 639 Part 1 two-letter language code). Will be null if language is not known. example: en type: string x-go-name: Language local_only: description: Set to "true" if status is not federated, ie., a "local only" status; omitted from response otherwise. type: boolean x-go-name: LocalOnly media_attachments: description: Media that is attached to this status. items: $ref: '#/definitions/attachment' type: array x-go-name: MediaAttachments mentions: description: Mentions of users within the status content. items: $ref: '#/definitions/Mention' type: array x-go-name: Mentions muted: description: Replies to this status have been muted by the account viewing it. type: boolean x-go-name: Muted pinned: description: This status has been pinned by the account viewing it (only relevant for your own statuses). type: boolean x-go-name: Pinned poll: $ref: '#/definitions/poll' reblog: $ref: '#/definitions/statusReblogged' reblogged: description: This status has been boosted/reblogged by the account viewing it. type: boolean x-go-name: Reblogged reblogs_count: description: Number of times this status has been boosted/reblogged, according to our instance. format: int64 type: integer x-go-name: ReblogsCount replies_count: description: Number of replies to this status, according to our instance. format: int64 type: integer x-go-name: RepliesCount sensitive: description: Status contains sensitive content. example: false type: boolean x-go-name: Sensitive spoiler_text: description: Subject, summary, or content warning for the status. example: warning nsfw type: string x-go-name: SpoilerText tags: description: Hashtags used within the status content. items: $ref: '#/definitions/tag' type: array x-go-name: Tags text: description: |- Plain-text source of a status. Returned instead of content when status is deleted, so the user may redraft from the source text without the client having to reverse-engineer the original text from the HTML content. type: string x-go-name: Text uri: description: ActivityPub URI of the status. Equivalent to the status's activitypub ID. example: https://example.org/users/some_user/statuses/01FBVD42CQ3ZEEVMW180SBX03B type: string x-go-name: URI url: description: The status's publicly available web URL. This link will only work if the visibility of the status is 'public'. example: https://example.org/@some_user/statuses/01FBVD42CQ3ZEEVMW180SBX03B type: string x-go-name: URL visibility: description: Visibility of this status. example: unlisted type: string x-go-name: Visibility title: StatusReblogged represents a reblogged status. type: object x-go-name: StatusReblogged x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/model statusSource: description: |- StatusSource represents the source text of a status as submitted to the API when it was created. properties: id: description: ID of the status. example: 01FBVD42CQ3ZEEVMW180SBX03B type: string x-go-name: ID spoiler_text: description: Plain-text version of spoiler text. type: string x-go-name: SpoilerText text: description: Plain-text source of a status. type: string x-go-name: Text type: object x-go-name: StatusSource x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/model swaggerCollection: properties: '@context': description: |- ActivityStreams JSON-LD context. A string or an array of strings, or more complex nested items. example: https://www.w3.org/ns/activitystreams x-go-name: Context first: $ref: '#/definitions/swaggerCollectionPage' id: description: ActivityStreams ID. example: https://example.org/users/some_user/statuses/106717595988259568/replies type: string x-go-name: ID last: $ref: '#/definitions/swaggerCollectionPage' type: description: ActivityStreams type. example: Collection type: string x-go-name: Type title: SwaggerCollection represents an ActivityPub Collection. type: object x-go-name: SwaggerCollection x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/activitypub/users swaggerCollectionPage: properties: id: description: ActivityStreams ID. example: https://example.org/users/some_user/statuses/106717595988259568/replies?page=true type: string x-go-name: ID items: description: Items on this page. example: - https://example.org/users/some_other_user/statuses/086417595981111564 - https://another.example.com/users/another_user/statuses/01FCN8XDV3YG7B4R42QA6YQZ9R items: type: string type: array x-go-name: Items next: description: Link to the next page. example: https://example.org/users/some_user/statuses/106717595988259568/replies?only_other_accounts=true&page=true type: string x-go-name: Next partOf: description: Collection this page belongs to. example: https://example.org/users/some_user/statuses/106717595988259568/replies type: string x-go-name: PartOf type: description: ActivityStreams type. example: CollectionPage type: string x-go-name: Type title: SwaggerCollectionPage represents one page of a collection. type: object x-go-name: SwaggerCollectionPage x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/activitypub/users swaggerFeaturedCollection: properties: '@context': description: |- ActivityStreams JSON-LD context. A string or an array of strings, or more complex nested items. example: https://www.w3.org/ns/activitystreams x-go-name: Context TotalItems: description: Number of items in this collection. example: 2 format: int64 type: integer id: description: ActivityStreams ID. example: https://example.org/users/some_user/collections/featured type: string x-go-name: ID items: description: List of status URIs. example: - https://example.org/users/some_user/statuses/01GSZ0F7Q8SJKNRF777GJD271R - https://example.org/users/some_user/statuses/01GSZ0G012CBQ7TEKX689S3QRE items: type: string type: array x-go-name: Items type: description: ActivityStreams type. example: OrderedCollection type: string x-go-name: Type title: SwaggerFeaturedCollection represents an ActivityPub OrderedCollection. type: object x-go-name: SwaggerFeaturedCollection x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/activitypub/users tag: properties: following: description: |- Following is true if the user is following this tag, false if they're not, and not present if there is no currently authenticated user. type: boolean x-go-name: Following history: description: |- History of this hashtag's usage. Currently just a stub, if provided will always be an empty array. example: [] items: {} type: array x-go-name: History name: description: 'The value of the hashtag after the # sign.' example: helloworld type: string x-go-name: Name url: description: Web link to the hashtag. example: https://example.org/tags/helloworld type: string x-go-name: URL title: Tag represents a hashtag used within the content of a status. type: object x-go-name: Tag x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/model theme: properties: description: description: User-facing description of this theme. type: string x-go-name: Description file_name: description: FileName of this theme in the themes directory. type: string x-go-name: FileName title: description: User-facing title of this theme. type: string x-go-name: Title title: Theme represents one user-selectable preset CSS theme. type: object x-go-name: Theme x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/model threadContext: description: |- ThreadContext models the tree or "thread" around a given status. properties: ancestors: description: Parents in the thread. items: $ref: '#/definitions/status' type: array x-go-name: Ancestors descendants: description: Children in the thread. items: $ref: '#/definitions/status' type: array x-go-name: Descendants type: object x-go-name: ThreadContext x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/model user: properties: admin: description: User is an admin. example: false type: boolean x-go-name: Admin approved: description: User was approved by an admin. example: true type: boolean x-go-name: Approved confirmation_sent_at: description: Time when the last "please confirm your email address" email was sent, if at all. (ISO 8601 Datetime) example: "2021-07-30T09:20:25+00:00" type: string x-go-name: ConfirmationSentAt confirmed_at: description: Time at which the email given in the `email` field was confirmed, if at all. (ISO 8601 Datetime) example: "2021-07-30T09:20:25+00:00" type: string x-go-name: ConfirmedAt created_at: description: Time this user was created. (ISO 8601 Datetime) example: "2021-07-30T09:20:25+00:00" type: string x-go-name: CreatedAt disabled: description: User's account is disabled. example: false type: boolean x-go-name: Disabled email: description: Confirmed email address of this user, if set. example: someone@example.org type: string x-go-name: Email id: description: Database ID of this user. example: 01FBVD42CQ3ZEEVMW180SBX03B type: string x-go-name: ID last_emailed_at: description: Time at which this user was last emailed, if at all. (ISO 8601 Datetime) example: "2021-07-30T09:20:25+00:00" type: string x-go-name: LastEmailedAt moderator: description: User is a moderator. example: false type: boolean x-go-name: Moderator reason: description: Reason for sign-up, if provided. example: Please! Pretty please! type: string x-go-name: Reason reset_password_sent_at: description: Time when the last "please reset your password" email was sent, if at all. (ISO 8601 Datetime) example: "2021-07-30T09:20:25+00:00" type: string x-go-name: ResetPasswordSentAt unconfirmed_email: description: Unconfirmed email address of this user, if set. example: someone.else@somewhere.else.example.org type: string x-go-name: UnconfirmedEmail title: User models fields relevant to one user. type: object x-go-name: User x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/model wellKnownResponse: description: See https://webfinger.net/ properties: aliases: items: type: string type: array x-go-name: Aliases links: items: $ref: '#/definitions/Link' type: array x-go-name: Links subject: type: string x-go-name: Subject 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 type: object 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: REPLACE_ME 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/{api_version}/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: Version of the API to use. Must be either `v1` or `v2`. If v1 is used, Hashtag results will be a slice of strings. If v2 is used, Hashtag results will be a slice of apimodel tags. in: path name: api_version required: true type: string - description: Return only items *OLDER* than the given max ID. The item with the specified ID will not be included in the response. Currently only used if 'type' is set to a specific type. in: query name: max_id type: string - description: Return only items *immediately newer* than the given min ID. The item with the specified ID will not be included in the response. Currently only used if 'type' is set to a specific type. in: query name: min_id type: string - default: 20 description: Number of each type of item to return. in: query maximum: 40 minimum: 1 name: limit type: integer - default: 0 description: Page number of results to return (starts at 0). This parameter is currently not used, page by selecting a specific query type and using maxID and minID instead. in: query maximum: 10 minimum: 0 name: offset type: integer - description: |- Query string to search for. This can be in the following forms: - `@[username]` -- search for an account with the given username on any domain. Can return multiple results. - @[username]@[domain]` -- search for a remote account with exact username and domain. Will only ever return 1 result at most. - `https://example.org/some/arbitrary/url` -- search for an account OR a status with the given URL. Will only ever return 1 result at most. - `#[hashtag_name]` -- search for a hashtag with the given hashtag name, or starting with the given hashtag name. Case insensitive. Can return multiple results. - any arbitrary string -- search for accounts or statuses containing the given string. Can return multiple results. Arbitrary string queries may include the following operators: - `from:localuser`, `from:remoteuser@instance.tld`: restrict results to statuses created by the specified account. in: query name: q required: true type: string - description: |- Type of item to return. One of: - `` -- empty string; return any/all results. - `accounts` -- return only account(s). - `statuses` -- return only status(es). - `hashtags` -- return only hashtag(s). If `type` is specified, paging can be performed using max_id and min_id parameters. If `type` is not specified, see the `offset` parameter for paging. in: query name: type type: string - default: false description: If searching query is for `@[username]@[domain]`, or a URL, allow the GoToSocial instance to resolve the search by making calls to remote instances (webfinger, ActivityPub, etc). in: query name: resolve type: boolean - default: false description: If search type includes accounts, and search query is an arbitrary string, show only accounts that the requesting account follows. If this is set to `true`, then the GoToSocial instance will enhance the search by also searching within account notes, not just in usernames and display names. in: query name: following type: boolean - default: false description: If searching for hashtags, exclude those not yet approved by instance admin. Currently this parameter is unused. in: query name: exclude_unreviewed type: boolean - description: Restrict results to statuses created by the specified account. in: query name: account_id type: string produces: - application/json responses: "200": description: Results of the search. schema: $ref: '#/definitions/searchResult' "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/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 "422": description: Unprocessable. Your account creation request cannot be processed because either too many accounts have been created on this instance in the last 24h, or the pending account backlog is full. "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}/featured_tags: get: description: 'THIS ENDPOINT IS CURRENTLY NOT FULLY IMPLEMENTED: it will always return an empty array.' operationId: accountsFeaturedTags parameters: - description: The id of the account. in: path name: id required: true type: string 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 target account's featured tags. 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: description: |- The next and previous queries can be parsed from the returned Link header. Example: ``` ; rel="next", ; rel="prev" ```` If account `hide_collections` is true, and requesting account != target account, no results will be returned. operationId: accountFollowers parameters: - description: Account ID. in: path name: id required: true type: string - description: 'Return only follower accounts *OLDER* than the given max ID. The follower account with the specified ID will not be included in the response. NOTE: the ID is of the internal follow, NOT any of the returned accounts.' in: query name: max_id type: string - description: 'Return only follower accounts *NEWER* than the given since ID. The follower account with the specified ID will not be included in the response. NOTE: the ID is of the internal follow, NOT any of the returned accounts.' in: query name: since_id type: string - description: 'Return only follower accounts *IMMEDIATELY NEWER* than the given min ID. The follower account with the specified ID will not be included in the response. NOTE: the ID is of the internal follow, NOT any of the returned accounts.' in: query name: min_id type: string - default: 40 description: Number of follower accounts to return. in: query maximum: 80 minimum: 1 name: limit type: integer produces: - application/json responses: "200": description: Array of accounts that follow this account. 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:accounts summary: See followers of account with given id. tags: - accounts /api/v1/accounts/{id}/following: get: description: |- The next and previous queries can be parsed from the returned Link header. Example: ``` ; rel="next", ; rel="prev" ```` If account `hide_collections` is true, and requesting account != target account, no results will be returned. operationId: accountFollowing parameters: - description: Account ID. in: path name: id required: true type: string - description: 'Return only following accounts *OLDER* than the given max ID. The following account with the specified ID will not be included in the response. NOTE: the ID is of the internal follow, NOT any of the returned accounts.' in: query name: max_id type: string - description: 'Return only following accounts *NEWER* than the given since ID. The following account with the specified ID will not be included in the response. NOTE: the ID is of the internal follow, NOT any of the returned accounts.' in: query name: since_id type: string - description: 'Return only following accounts *IMMEDIATELY NEWER* than the given min ID. The following account with the specified ID will not be included in the response. NOTE: the ID is of the internal follow, NOT any of the returned accounts.' in: query name: min_id type: string - default: 40 description: Number of following accounts to return. in: query maximum: 80 minimum: 1 name: limit type: integer produces: - application/json responses: "200": description: Array of accounts that are followed by this account. 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:accounts summary: See accounts followed by given account id. tags: - accounts /api/v1/accounts/{id}/lists: get: operationId: accountLists parameters: - description: Account ID. in: path name: id required: true type: string produces: - application/json responses: "200": description: Array of all lists containing this account. schema: items: $ref: '#/definitions/list' 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:lists summary: See all lists of yours that contain requested account. tags: - accounts /api/v1/accounts/{id}/mute: post: description: If account was already muted, succeeds anyway. This can be used to update the details of a mute. operationId: accountMute parameters: - description: The ID of the account to block. in: path name: id required: true type: string - default: false description: Mute notifications as well as posts. in: formData name: notifications type: boolean - default: 0 description: How long the mute should last, in seconds. If 0 or not provided, mute lasts indefinitely. in: formData name: duration type: number produces: - application/json responses: "200": description: Your relationship to the account. schema: $ref: '#/definitions/accountRelationship' "400": description: bad request "401": description: unauthorized "403": description: forbidden to moved accounts "404": description: not found "406": description: not acceptable "500": description: internal server error security: - OAuth2 Bearer: - write:mutes summary: Mute account by ID. tags: - accounts /api/v1/accounts/{id}/note: post: consumes: - multipart/form-data operationId: accountNote parameters: - description: The id of the account for which to set a note. in: path name: id required: true type: string - default: "" description: The text of the note. Omit this parameter or send an empty string to clear the note. in: formData name: comment 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:accounts summary: Set a private note for an account with the given 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 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. 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: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/{id}/unmute: post: description: If account was already unmuted (or has never been muted), succeeds anyway. operationId: accountUnmute parameters: - description: The ID of the account to unmute. 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:mutes summary: Unmute account by ID. tags: - accounts /api/v1/accounts/alias: post: consumes: - multipart/form-data description: |- This is useful when you want to move from another account this this account. In such cases, you should set the alsoKnownAs of this account to the URI of the account you want to move from. operationId: accountAlias parameters: - description: |- ActivityPub URI/IDs of target accounts to which this account is being aliased. Eg., `["https://example.org/users/some_account"]`. Use an empty array to unset alsoKnownAs, clearing the aliases. in: formData name: also_known_as_uris required: true type: string 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 "422": description: Unprocessable. Check the response body for more details. "500": description: internal server error security: - OAuth2 Bearer: - write:accounts summary: Alias your account to another account by setting alsoKnownAs to the given URI. 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/lookup: get: operationId: accountLookupGet parameters: - description: The username or Webfinger address to lookup. in: query name: acct required: true type: string produces: - application/json responses: "200": description: Result of the lookup. 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: Quickly lookup a username to see if it is available, skipping WebFinger resolution. tags: - accounts /api/v1/accounts/move: post: consumes: - multipart/form-data operationId: accountMove parameters: - description: Password of the account user, for confirmation. in: formData name: password required: true type: string - description: ActivityPub URI/ID of the target account. Eg., `https://example.org/users/some_account`. The target account must be alsoKnownAs the requesting account in order for the move to be successful. in: formData name: moved_to_uri required: true type: string responses: "202": description: The account move has been accepted and the account will be moved. "400": description: bad request "401": description: unauthorized "404": description: not found "406": description: not acceptable "422": description: Unprocessable. Check the response body for more details. "500": description: internal server error security: - OAuth2 Bearer: - write:accounts summary: Move your account to another account. tags: - accounts /api/v1/accounts/relationships: get: operationId: accountRelationships parameters: - collectionFormat: multi 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/search: get: operationId: accountSearchGet parameters: - default: 40 description: Number of results to try to return. in: query maximum: 80 minimum: 1 name: limit type: integer - default: 0 description: Page number of results to return (starts at 0). This parameter is currently not used, offsets over 0 will always return 0 results. in: query maximum: 10 minimum: 0 name: offset type: integer - description: |- Query string to search for. This can be in the following forms: - `@[username]` -- search for an account with the given username on any domain. Can return multiple results. - `@[username]@[domain]` -- search for a remote account with exact username and domain. Will only ever return 1 result at most. - any arbitrary string -- search for accounts containing the given string in their username or display name. Can return multiple results. in: query name: q required: true type: string - default: false description: If query is for `@[username]@[domain]`, or a URL, allow the GoToSocial instance to resolve the search by making calls to remote instances (webfinger, ActivityPub, etc). in: query name: resolve type: boolean - default: false description: Show only accounts that the requesting account follows. If this is set to `true`, then the GoToSocial instance will enhance the search by also searching within account notes, not just in usernames and display names. in: query name: following type: boolean produces: - application/json responses: "200": description: Results of the search. 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: Search for accounts by username and/or display name. tags: - accounts /api/v1/accounts/themes: get: operationId: accountThemes produces: - application/json responses: "200": description: Array of themes. schema: items: $ref: '#/definitions/theme' 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 preset CSS themes available to accounts on this instance. tags: - accounts /api/v1/accounts/update_credentials: patch: consumes: - multipart/form-data - application/x-www-form-urlencoded - 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 - allowEmptyValue: true description: Description of avatar image, for alt-text. in: formData name: avatar_description type: string - description: Header of the user. in: formData name: header type: file - allowEmptyValue: true description: Description of header image, for alt-text. in: formData name: header_description type: string - 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: FileName of the theme to use when rendering this account's profile or statuses. The theme must exist on this server, as indicated by /api/v1/accounts/themes. Empty string unsets theme and returns to the default GoToSocial theme. in: formData name: theme 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: Hide the account's following/followers collections. in: formData name: hide_collections type: boolean - description: |- Posts to show on the web view of the account. "public": default, show only Public visibility posts on the web. "unlisted": show Public *and* Unlisted visibility posts on the web. "none": show no posts on the web, not even Public ones. in: formData name: web_visibility type: string - description: Name of 1st profile field to be added to this account's profile. (The index may be any string; add more indexes to send more fields.) in: formData name: fields_attributes[0][name] type: string - description: Value of 1st profile field to be added to this account's profile. (The index may be any string; add more indexes to send more fields.) in: formData name: fields_attributes[0][value] type: string - description: Name of 2nd profile field to be added to this account's profile. in: formData name: fields_attributes[1][name] type: string - description: Value of 2nd profile field to be added to this account's profile. in: formData name: fields_attributes[1][value] type: string - description: Name of 3rd profile field to be added to this account's profile. in: formData name: fields_attributes[2][name] type: string - description: Value of 3rd profile field to be added to this account's profile. in: formData name: fields_attributes[2][value] type: string - description: Name of 4th profile field to be added to this account's profile. in: formData name: fields_attributes[3][name] type: string - description: Value of 4th profile field to be added to this account's profile. in: formData name: fields_attributes[3][value] type: string - description: Name of 5th profile field to be added to this account's profile. in: formData name: fields_attributes[4][name] type: string - description: Value of 5th profile field to be added to this account's profile. in: formData name: fields_attributes[4][value] type: string - description: Name of 6th profile field to be added to this account's profile. in: formData name: fields_attributes[5][name] type: string - description: Value of 6th profile field to be added to this account's profile. in: formData name: fields_attributes[5][value] type: string 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: get: description: |- Returned accounts will be ordered alphabetically (a-z) by domain + username. The next and previous queries can be parsed from the returned Link header. Example: ``` ; rel="next", ; rel="prev" ```` operationId: adminAccountsGetV1 parameters: - default: false description: Filter for local accounts. in: query name: local type: boolean - default: false description: Filter for remote accounts. in: query name: remote type: boolean - default: false description: Filter for currently active accounts. in: query name: active type: boolean - default: false description: Filter for currently pending accounts. in: query name: pending type: boolean - default: false description: Filter for currently disabled accounts. in: query name: disabled type: boolean - default: false description: Filter for currently silenced accounts. in: query name: silenced type: boolean - default: false description: Filter for currently suspended accounts. in: query name: suspended type: boolean - default: false description: Filter for accounts force-marked as sensitive. in: query name: sensitized type: boolean - description: Search for the given username. in: query name: username type: string - description: Search for the given display name. in: query name: display_name type: string - description: Filter by the given domain. in: query name: by_domain type: string - description: Lookup a user with this email. in: query name: email type: string - description: Lookup users with this IP address. in: query name: ip type: string - default: false description: Filter for staff accounts. in: query name: staff type: boolean - description: max_id in the form `[domain]/@[username]`. All results returned will be later in the alphabet than `[domain]/@[username]`. For example, if max_id = `example.org/@someone` then returned entries might contain `example.org/@someone_else`, `later.example.org/@someone`, etc. Local account IDs in this form use an empty string for the `[domain]` part, for example local account with username `someone` would be `/@someone`. in: query name: max_id type: string - description: min_id in the form `[domain]/@[username]`. All results returned will be earlier in the alphabet than `[domain]/@[username]`. For example, if min_id = `example.org/@someone` then returned entries might contain `example.org/@earlier_account`, `earlier.example.org/@someone`, etc. Local account IDs in this form use an empty string for the `[domain]` part, for example local account with username `someone` would be `/@someone`. in: query name: min_id type: string - default: 50 description: Maximum number of results to return. in: query maximum: 200 minimum: 1 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/adminAccountInfo' 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 + page through known accounts according to given filters. tags: - admin /api/v1/admin/accounts/{id}: get: operationId: adminAccountGet parameters: - description: ID of the account. in: path name: id required: true type: string produces: - application/json responses: "200": description: OK schema: $ref: '#/definitions/adminAccountInfo' "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 one account. tags: - admin /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 "409": description: 'Conflict: There is already an admin action running that conflicts with this action. Check the error message in the response body for more information. This is a temporary error; it should be possible to process this action if you try again in a bit.' "500": description: internal server error security: - OAuth2 Bearer: - admin summary: Perform an admin action on an account. tags: - admin /api/v1/admin/accounts/{id}/approve: post: operationId: adminAccountApprove parameters: - description: ID of the account. in: path name: id required: true type: string produces: - application/json responses: "200": description: The now-approved account. schema: $ref: '#/definitions/adminAccountInfo' "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: Approve pending account. tags: - admin /api/v1/admin/accounts/{id}/reject: post: operationId: adminAccountReject parameters: - description: ID of the account. in: path name: id required: true type: string - description: Comment to leave on why the account was denied. The comment will be visible to admins only. in: formData name: private_comment type: string - description: Message to include in email to applicant. Will be included only if send_email is true. in: formData name: message type: string - description: Send an email to the applicant informing them that their sign-up has been rejected. in: formData name: send_email type: boolean produces: - application/json responses: "200": description: The now-rejected account. schema: $ref: '#/definitions/adminAccountInfo' "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: Reject pending 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 maximum: 200 minimum: 0 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{1,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. 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. enum: - copy - disable - modify 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{1,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. 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 produces: - application/json responses: "200": description: Array of existing emoji categories. schema: items: $ref: '#/definitions/emojiCategory' 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/debug/apurl: get: description: Only enabled / exposed if GoToSocial was built and is running with flag DEBUG=1. operationId: debugAPUrl parameters: - description: The URL / ActivityPub ID to dereference. This should be a full URL, including protocol. Eg., `https://example.org/users/someone` in: query name: url required: true type: string produces: - application/json responses: "200": description: "" schema: $ref: '#/definitions/debugAPUrlResponse' "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: Perform a GET to the specified ActivityPub URL and return detailed debugging information. tags: - debug /api/v1/admin/debug/caches/clear: post: description: Only enabled / exposed if GoToSocial was built and is running with flag DEBUG=1. operationId: debugClearCaches produces: - application/json responses: "200": description: All good baby! "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: Sweep/clear all in-memory caches. tags: - debug /api/v1/admin/domain_allows: get: operationId: domainAllowsGet parameters: - description: If set to `true`, then each entry in the returned list of domain allows 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 allowed on your instance, so that someone else can easily import them, but you don't want them to see the database IDs of your allows, or private comments etc. in: query name: export type: boolean produces: - application/json responses: "200": description: All domain allows currently in place. schema: items: $ref: '#/definitions/domainPermission' 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 allows 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 allows, JSON-formatted, or you can leave import as `false`, and just add one domain allow. The format of the json file should be something like: `[{"domain":"example.org"},{"domain":"whatever.com","public_comment":"they smell"}]` operationId: domainAllowCreate parameters: - default: false description: Signal that a list of domain allows 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 allows to import. This is only used if `import` is set to `true`. in: formData name: domains type: file - description: Single domain to allow. 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 allow. This will be displayed alongside the domain allow if you choose to share allows. Used only if `import` is not `true`. in: formData name: public_comment type: string - description: Private comment about this domain allow. Will only be shown to other admins, so this is a useful way of internally keeping track of why a certain domain ended up allowed. Used only if `import` is not `true`. in: formData name: private_comment type: string produces: - application/json responses: "200": description: The newly created domain allow, if `import` != `true`. If a list has been imported, then an `array` of newly created domain allows will be returned instead. schema: $ref: '#/definitions/domainPermission' "400": description: bad request "401": description: unauthorized "403": description: forbidden "404": description: not found "406": description: not acceptable "409": description: 'Conflict: There is already an admin action running that conflicts with this action. Check the error message in the response body for more information. This is a temporary error; it should be possible to process this action if you try again in a bit.' "500": description: internal server error security: - OAuth2 Bearer: - admin summary: Create one or more domain allows, from a string or a file. tags: - admin /api/v1/admin/domain_allows/{id}: delete: operationId: domainAllowDelete parameters: - description: The id of the domain allow. in: path name: id required: true type: string produces: - application/json responses: "200": description: The domain allow that was just deleted. schema: $ref: '#/definitions/domainPermission' "400": description: bad request "401": description: unauthorized "403": description: forbidden "404": description: not found "406": description: not acceptable "409": description: 'Conflict: There is already an admin action running that conflicts with this action. Check the error message in the response body for more information. This is a temporary error; it should be possible to process this action if you try again in a bit.' "500": description: internal server error security: - OAuth2 Bearer: - admin summary: Delete domain allow with the given ID. tags: - admin get: operationId: domainAllowGet parameters: - description: The id of the domain allow. in: path name: id required: true type: string produces: - application/json responses: "200": description: The requested domain allow. schema: $ref: '#/definitions/domainPermission' "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 allow with the given ID. 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/domainPermission' 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/domainPermission' "400": description: bad request "401": description: unauthorized "403": description: forbidden "404": description: not found "406": description: not acceptable "409": description: 'Conflict: There is already an admin action running that conflicts with this action. Check the error message in the response body for more information. This is a temporary error; it should be possible to process this action if you try again in a bit.' "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/domainPermission' "400": description: bad request "401": description: unauthorized "403": description: forbidden "404": description: not found "406": description: not acceptable "409": description: 'Conflict: There is already an admin action running that conflicts with this action. Check the error message in the response body for more information. This is a temporary error; it should be possible to process this action if you try again in a bit.' "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/domainPermission' "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/domain_keys_expire: post: consumes: - multipart/form-data description: |- This is useful in cases where the remote domain has had to rotate their keys for whatever reason (security issue, data leak, routine safety procedure, etc), and your instance can no longer communicate with theirs properly using cached keys. A key marked as expired in this way will be lazily refetched next time a request is made to your instance signed by the owner of that key, so no further action should be required in order to reestablish communication with that domain. This endpoint is explicitly not for rotating your *own* keys, it only works for remote instances. Using this endpoint to expire keys for a domain that hasn't rotated all of their keys is not harmful and won't break federation, but it is pointless and will cause unnecessary requests to be performed. operationId: domainKeysExpire parameters: - description: |- Domain to expire keys for. Sample: example.org in: formData name: domain type: string x-go-name: Domain produces: - application/json responses: "202": description: Request accepted and will be processed. Check the logs for progress / errors. schema: $ref: '#/definitions/adminActionResponse' "400": description: bad request "401": description: unauthorized "403": description: forbidden "404": description: not found "406": description: not acceptable "409": description: 'Conflict: There is already an admin action running that conflicts with this action. Check the error message in the response body for more information. This is a temporary error; it should be possible to process this action if you try again in a bit.' "500": description: internal server error security: - OAuth2 Bearer: - admin summary: Force expiry of cached public keys for all accounts on the given domain stored in your database. tags: - admin /api/v1/admin/domain_permission_drafts: get: description: |- The drafts 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: domainPermissionDraftsGet parameters: - description: Show only drafts created by the given subscription ID. in: query name: subscription_id type: string - description: Return only drafts that target the given domain. in: query name: domain type: string - description: Filter on "block" or "allow" type drafts. in: query name: permission_type type: string - description: Return only items *OLDER* than the given max ID (for paging downwards). The item with the specified ID will not be included in the response. in: query name: max_id type: string - description: Return only items *NEWER* than the given since ID. The item with the specified ID will not be included in the response. in: query name: since_id type: string - description: Return only items immediately *NEWER* than the given min ID (for paging upwards). The item with the specified ID will not be included in the response. in: query name: min_id type: string - default: 20 description: Number of items to return. in: query maximum: 100 minimum: 1 name: limit type: integer produces: - application/json responses: "200": description: Domain permission drafts. headers: Link: description: Links to the next and previous queries. type: string schema: items: $ref: '#/definitions/domainPermission' 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 domain permission drafts. tags: - admin post: consumes: - multipart/form-data - application/json operationId: domainPermissionDraftCreate parameters: - description: Domain to create the permission draft for. in: formData name: domain type: string - description: Create a draft "allow" or a draft "block". in: formData name: permission_type type: string - description: Obfuscate the name of the domain when serving it publicly. Eg., `example.org` becomes something like `ex***e.org`. in: formData name: obfuscate type: boolean - description: Public comment about this domain permission. This will be displayed alongside the domain permission if you choose to share permissions. in: formData name: public_comment type: string - description: Private comment about this domain permission. Will only be shown to other admins, so this is a useful way of internally keeping track of why a certain domain ended up permissioned. in: formData name: private_comment type: string produces: - application/json responses: "200": description: The newly created domain permission draft. schema: $ref: '#/definitions/domainPermission' "400": description: bad request "401": description: unauthorized "403": description: forbidden "406": description: not acceptable "409": description: conflict "500": description: internal server error security: - OAuth2 Bearer: - admin summary: Create a domain permission draft with the given parameters. tags: - admin /api/v1/admin/domain_permission_drafts/{id}: get: operationId: domainPermissionDraftGet parameters: - description: ID of the domain permission draft. in: path name: id required: true type: string produces: - application/json responses: "200": description: Domain permission draft. schema: $ref: '#/definitions/domainPermission' "401": description: unauthorized "403": description: forbidden "404": description: not found "406": description: not acceptable "500": description: internal server error security: - OAuth2 Bearer: - admin summary: Get domain permission draft with the given ID. tags: - admin /api/v1/admin/domain_permission_drafts/{id}/accept: post: consumes: - multipart/form-data - application/json operationId: domainPermissionDraftAccept parameters: - description: ID of the domain permission draft. in: path name: id required: true type: string - default: false description: If a domain permission already exists with the same domain and permission type as the draft, overwrite the existing permission with fields from the draft. in: formData name: overwrite type: boolean produces: - application/json responses: "200": description: The newly created domain permission. schema: $ref: '#/definitions/domainPermission' "400": description: bad request "401": description: unauthorized "403": description: forbidden "406": description: not acceptable "409": description: conflict "500": description: internal server error security: - OAuth2 Bearer: - admin summary: Accept a domain permission draft, turning it into an enforced domain permission. tags: - admin /api/v1/admin/domain_permission_drafts/{id}/remove: post: consumes: - multipart/form-data - application/json operationId: domainPermissionDraftRemove parameters: - description: ID of the domain permission draft. in: path name: id required: true type: string - default: false description: When removing the domain permission draft, also create a domain exclude entry for the target domain, so that drafts will not be created for this domain in the future. in: formData name: exclude_target type: boolean produces: - application/json responses: "200": description: The removed domain permission draft. schema: $ref: '#/definitions/domainPermission' "400": description: bad request "401": description: unauthorized "403": description: forbidden "406": description: not acceptable "409": description: conflict "500": description: internal server error security: - OAuth2 Bearer: - admin summary: Remove a domain permission draft, optionally ignoring all future drafts targeting the given domain. tags: - admin /api/v1/admin/domain_permission_excludes: get: description: |- The excludes 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: domainPermissionExcludesGet parameters: - description: Return only excludes that target the given domain. in: query name: domain type: string - description: Return only items *OLDER* than the given max ID (for paging downwards). The item with the specified ID will not be included in the response. in: query name: max_id type: string - description: Return only items *NEWER* than the given since ID. The item with the specified ID will not be included in the response. in: query name: since_id type: string - description: Return only items immediately *NEWER* than the given min ID (for paging upwards). The item with the specified ID will not be included in the response. in: query name: min_id type: string - default: 20 description: Number of items to return. in: query maximum: 100 minimum: 1 name: limit type: integer produces: - application/json responses: "200": description: Domain permission excludes. headers: Link: description: Links to the next and previous queries. type: string schema: items: $ref: '#/definitions/domainPermission' 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 domain permission excludes. tags: - admin post: consumes: - multipart/form-data - application/json description: |- Excluded domains (and their subdomains) will not be automatically blocked or allowed when a list of domain permissions is imported or subscribed to. You can still manually create domain blocks or domain allows for excluded domains, and any new or existing domain blocks or domain allows for an excluded domain will still be enforced. operationId: domainPermissionExcludeCreate parameters: - description: Domain to create the permission exclude for. in: formData name: domain type: string - description: Private comment about this domain exclude. in: formData name: private_comment type: string produces: - application/json responses: "200": description: The newly created domain permission exclude. schema: $ref: '#/definitions/domainPermission' "400": description: bad request "401": description: unauthorized "403": description: forbidden "406": description: not acceptable "409": description: conflict "500": description: internal server error security: - OAuth2 Bearer: - admin summary: Create a domain permission exclude with the given parameters. tags: - admin /api/v1/admin/domain_permission_excludes/{id}: delete: operationId: domainPermissionExcludeDelete parameters: - description: ID of the domain permission exclude. in: path name: id required: true type: string produces: - application/json responses: "200": description: The removed domain permission exclude. schema: $ref: '#/definitions/domainPermission' "400": description: bad request "401": description: unauthorized "403": description: forbidden "406": description: not acceptable "409": description: conflict "500": description: internal server error security: - OAuth2 Bearer: - admin summary: Remove a domain permission exclude. tags: - admin get: operationId: domainPermissionExcludeGet parameters: - description: ID of the domain permission exclude. in: path name: id required: true type: string produces: - application/json responses: "200": description: Domain permission exclude. schema: $ref: '#/definitions/domainPermission' "401": description: unauthorized "403": description: forbidden "404": description: not found "406": description: not acceptable "500": description: internal server error security: - OAuth2 Bearer: - admin summary: Get domain permission exclude with the given ID. tags: - admin /api/v1/admin/domain_permission_subscriptions: get: description: |- The subscriptions 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: domainPermissionSubscriptionsGet parameters: - description: Filter on "block" or "allow" type subscriptions. in: query name: permission_type type: string - description: Return only items *OLDER* than the given max ID (for paging downwards). The item with the specified ID will not be included in the response. in: query name: max_id type: string - description: Return only items *NEWER* than the given since ID. The item with the specified ID will not be included in the response. in: query name: since_id type: string - description: Return only items immediately *NEWER* than the given min ID (for paging upwards). The item with the specified ID will not be included in the response. in: query name: min_id type: string - default: 20 description: Number of items to return. in: query maximum: 100 minimum: 1 name: limit type: integer produces: - application/json responses: "200": description: Domain permission subscriptions. headers: Link: description: Links to the next and previous queries. type: string schema: items: $ref: '#/definitions/domainPermissionSubscription' 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 domain permission subscriptions. tags: - admin post: consumes: - multipart/form-data - application/json operationId: domainPermissionSubscriptionCreate parameters: - default: 0 description: Priority of this subscription compared to others of the same permission type. 0-255 (higher = higher priority). Higher priority subscriptions will overwrite permissions generated by lower priority subscriptions. When two subscriptions have the same `priority` value, priority is indeterminate, so it's recommended to always set this value manually. in: formData maximum: 255 minimum: 0 name: priority type: number - description: Optional title for this subscription. in: formData name: title type: string - description: Type of permissions to create by parsing the targeted file/list. One of "allow" or "block". in: formData name: permission_type required: true type: string - default: true description: If true, domain permissions arising from this subscription will be created as drafts that must be approved by a moderator to take effect. If false, domain permissions from this subscription will come into force immediately. Defaults to "true". in: formData name: as_draft type: boolean - default: false description: 'If true, this domain permission subscription will "adopt" domain permissions which already exist on the instance, and which meet the following conditions: 1) they have no subscription ID (ie., they''re "orphaned") and 2) they are present in the subscribed list. Such orphaned domain permissions will be given this subscription''s subscription ID value and be managed by this subscription.' in: formData name: adopt_orphans type: boolean - description: URI to call in order to fetch the permissions list. in: formData name: uri required: true type: string - description: MIME content type to use when parsing the permissions list. One of "text/plain", "text/csv", and "application/json". in: formData name: content_type required: true type: string - description: Optional basic auth username to provide when fetching given uri. If set, will be transmitted along with `fetch_password` when doing the fetch. in: formData name: fetch_username type: string - description: Optional basic auth password to provide when fetching given uri. If set, will be transmitted along with `fetch_username` when doing the fetch. in: formData name: fetch_password type: string produces: - application/json responses: "200": description: The newly created domain permission subscription. schema: $ref: '#/definitions/domainPermissionSubscription' "400": description: bad request "401": description: unauthorized "403": description: forbidden "406": description: not acceptable "409": description: conflict "500": description: internal server error security: - OAuth2 Bearer: - admin summary: Create a domain permission subscription with the given parameters. tags: - admin /api/v1/admin/domain_permission_subscriptions/${id}: patch: consumes: - multipart/form-data - application/json operationId: domainPermissionSubscriptionUpdate parameters: - description: ID of the domain permission subscription. in: path name: id required: true type: string - description: Priority of this subscription compared to others of the same permission type. 0-255 (higher = higher priority). Higher priority subscriptions will overwrite permissions generated by lower priority subscriptions. When two subscriptions have the same `priority` value, priority is indeterminate, so it's recommended to always set this value manually. in: formData maximum: 255 minimum: 0 name: priority type: number - description: Optional title for this subscription. in: formData name: title type: string - description: URI to call in order to fetch the permissions list. in: formData name: uri type: string - default: true description: If true, domain permissions arising from this subscription will be created as drafts that must be approved by a moderator to take effect. If false, domain permissions from this subscription will come into force immediately. Defaults to "true". in: formData name: as_draft type: boolean - default: false description: 'If true, this domain permission subscription will "adopt" domain permissions which already exist on the instance, and which meet the following conditions: 1) they have no subscription ID (ie., they''re "orphaned") and 2) they are present in the subscribed list. Such orphaned domain permissions will be given this subscription''s subscription ID value and be managed by this subscription.' in: formData name: adopt_orphans type: boolean - description: MIME content type to use when parsing the permissions list. One of "text/plain", "text/csv", and "application/json". in: formData name: content_type type: string - description: Optional basic auth username to provide when fetching given uri. If set, will be transmitted along with `fetch_password` when doing the fetch. in: formData name: fetch_username type: string - description: Optional basic auth password to provide when fetching given uri. If set, will be transmitted along with `fetch_username` when doing the fetch. in: formData name: fetch_password type: string produces: - application/json responses: "200": description: The updated domain permission subscription. schema: $ref: '#/definitions/domainPermissionSubscription' "400": description: bad request "401": description: unauthorized "403": description: forbidden "406": description: not acceptable "409": description: conflict "500": description: internal server error security: - OAuth2 Bearer: - admin summary: Update a domain permission subscription with the given parameters. tags: - admin /api/v1/admin/domain_permission_subscriptions/{id}: get: operationId: domainPermissionSubscriptionGet parameters: - description: ID of the domain permission subscription. in: path name: id required: true type: string produces: - application/json responses: "200": description: Domain permission subscription. schema: $ref: '#/definitions/domainPermissionSubscription' "401": description: unauthorized "403": description: forbidden "404": description: not found "406": description: not acceptable "500": description: internal server error security: - OAuth2 Bearer: - admin summary: Get domain permission subscription with the given ID. tags: - admin /api/v1/admin/domain_permission_subscriptions/{id}/remove: post: consumes: - multipart/form-data - application/json operationId: domainPermissionSubscriptionRemove parameters: - description: ID of the domain permission subscription. in: path name: id required: true type: string - default: true description: |- When removing the domain permission subscription, also remove children of this subscription, ie., domain permissions that are managed by this subscription. If false, then children will instead be orphaned but not removed. Note that removed permissions may end up being created again later by another domain permission subscription of lower priority than the removed subscription. Likewise, orphaned children may be later adopted by another subscription. in: formData name: remove_children type: boolean produces: - application/json responses: "200": description: The removed domain permission subscription. schema: $ref: '#/definitions/domainPermissionSubscription' "400": description: bad request "401": description: unauthorized "403": description: forbidden "406": description: not acceptable "409": description: conflict "500": description: internal server error security: - OAuth2 Bearer: - admin summary: Remove a domain permission subscription. tags: - admin /api/v1/admin/domain_permission_subscriptions/preview: get: description: This view allows you to see the order in which domain permissions will actually be fetched and created. operationId: domainPermissionSubscriptionsPreviewGet parameters: - description: Filter on "block" or "allow" type subscriptions. in: query name: permission_type required: true type: string produces: - application/json responses: "200": description: Domain permission subscriptions. schema: items: $ref: '#/definitions/domainPermissionSubscription' 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 permission subscriptions of the given permission type, in priority order (highest to lowest). 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 required: true type: string - description: Optional message to include in the email. in: formData name: message 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/header_allows: get: operationId: headerFilterAllowsGet responses: "200": description: All "allow" header filters currently in place. schema: items: $ref: '#/definitions/headerFilter' type: array "400": description: bad request "401": description: unauthorized "403": description: forbidden "404": description: not found "500": description: internal server error security: - OAuth2 Bearer: - admin summary: Get all "allow" header filters currently in place. tags: - admin 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: headerFilterAllowCreate parameters: - description: The HTTP header to match against (e.g. User-Agent). in: formData name: header required: true type: string x-go-name: Header - description: The header value matching regular expression. in: formData name: regex required: true type: string x-go-name: Regex produces: - application/json responses: "200": description: The newly created "allow" header filter. schema: $ref: '#/definitions/headerFilter' "400": description: bad request "401": description: unauthorized "403": description: forbidden "500": description: internal server error security: - OAuth2 Bearer: - admin summary: Create new "allow" HTTP request header filter. tags: - admin /api/v1/admin/header_allows/{id}: delete: operationId: headerFilterAllowDelete parameters: - description: Target header filter ID. in: path name: id required: true type: string responses: "202": description: Accepted "400": description: bad request "401": description: unauthorized "403": description: forbidden "404": description: not found "500": description: internal server error security: - OAuth2 Bearer: - admin summary: Delete the "allow" header filter with the given ID. tags: - admin get: operationId: headerFilterAllowGet parameters: - description: Target header filter ID. in: path name: id required: true type: string responses: "200": description: The requested "allow" header filter. schema: $ref: '#/definitions/headerFilter' "400": description: bad request "401": description: unauthorized "403": description: forbidden "404": description: not found "500": description: internal server error security: - OAuth2 Bearer: - admin summary: Get "allow" header filter with the given ID. tags: - admin /api/v1/admin/header_blocks: get: operationId: headerFilterBlocksGet responses: "200": description: All "block" header filters currently in place. schema: items: $ref: '#/definitions/headerFilter' type: array "400": description: bad request "401": description: unauthorized "403": description: forbidden "404": description: not found "500": description: internal server error security: - OAuth2 Bearer: - admin summary: Get all "allow" header filters currently in place. tags: - admin 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: headerFilterBlockCreate parameters: - description: The HTTP header to match against (e.g. User-Agent). in: formData name: header required: true type: string x-go-name: Header - description: The header value matching regular expression. in: formData name: regex required: true type: string x-go-name: Regex produces: - application/json responses: "200": description: The newly created "block" header filter. schema: $ref: '#/definitions/headerFilter' "400": description: bad request "401": description: unauthorized "403": description: forbidden "500": description: internal server error security: - OAuth2 Bearer: - admin summary: Create new "block" HTTP request header filter. tags: - admin /api/v1/admin/header_blocks/{id}: delete: operationId: headerFilterBlockDelete parameters: - description: Target header filter ID. in: path name: id required: true type: string responses: "202": description: Accepted "400": description: bad request "401": description: unauthorized "403": description: forbidden "404": description: not found "500": description: internal server error security: - OAuth2 Bearer: - admin summary: Delete the "block" header filter with the given ID. tags: - admin get: operationId: headerFilterBlockGet parameters: - description: Target header filter ID. in: path name: id required: true type: string responses: "200": description: The requested "block" header filter. schema: $ref: '#/definitions/headerFilter' "400": description: bad request "401": description: unauthorized "403": description: forbidden "404": description: not found "500": description: internal server error security: - OAuth2 Bearer: - admin summary: Get "block" header filter with the given ID. tags: - admin /api/v1/admin/instance/rules: post: consumes: - multipart/form-data operationId: ruleCreate parameters: - description: Text body for the instance rule, plaintext. in: formData name: text required: true type: string x-go-name: Text produces: - application/json responses: "200": description: The newly-created instance rule. schema: $ref: '#/definitions/instanceRule' "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 a new instance rule. tags: - admin /api/v1/admin/instance/rules/{id}: delete: consumes: - multipart/form-data operationId: ruleDelete parameters: - description: The id of the rule to delete. in: path name: id required: true type: string produces: - application/json responses: "200": description: The deleted instance rule. schema: $ref: '#/definitions/instanceRule' "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 an existing instance rule. tags: - admin patch: consumes: - multipart/form-data operationId: ruleUpdate parameters: - description: The id of the rule to update. in: path name: id required: true type: string x-go-name: ID - description: Text body for the updated instance rule, plaintext. in: formData name: text required: true type: string x-go-name: Text produces: - application/json responses: "200": description: The updated instance rule. schema: $ref: '#/definitions/instanceRule' "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 an existing instance rule. 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 (for paging downwards). 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. in: query name: since_id type: string - description: Return only reports immediately *NEWER* than the given min ID (for paging upwards). The report with the specified ID will not be included in the response. in: query name: min_id type: string - default: 20 description: Number of reports to return. in: query maximum: 100 minimum: 1 name: limit type: integer produces: - application/json responses: "200": description: Array of reports. headers: Link: description: Links to the next and previous queries. type: string 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! Sample: 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/admin/rules: get: description: The rules will be returned in order (sorted by Order ascending). operationId: adminsRuleGet produces: - application/json responses: "200": description: An array with all the rules for the local instance. schema: items: $ref: '#/definitions/instanceRule' 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 instance rules, with IDs. tags: - admin /api/v1/admin/rules/{id}: get: operationId: adminRuleGet parameters: - description: The id of the rule. in: path name: id required: true type: string produces: - application/json responses: "200": description: The requested rule. schema: $ref: '#/definitions/instanceRule' "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 instance rule with the given id. tags: - admin /api/v1/announcements: get: description: 'THIS ENDPOINT IS CURRENTLY NOT FULLY IMPLEMENTED: it will always return an empty array.' operationId: announcementsGet produces: - application/json responses: "200": description: "" schema: items: type: object maxItems: 0 type: array "400": description: bad request "401": description: unauthorized "406": description: not acceptable "500": description: internal server error security: - OAuth2 Bearer: - read:announcements summary: Get an array of currently active announcements. tags: - announcements /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: - description: 'Return only blocked accounts *OLDER* than the given max ID. The blocked account with the specified ID will not be included in the response. NOTE: the ID is of the internal block, NOT any of the returned accounts.' in: query name: max_id type: string - description: 'Return only blocked accounts *NEWER* than the given since ID. The blocked account with the specified ID will not be included in the response. NOTE: the ID is of the internal block, NOT any of the returned accounts.' in: query name: since_id type: string - description: 'Return only blocked accounts *IMMEDIATELY NEWER* than the given min ID. The blocked account with the specified ID will not be included in the response. NOTE: the ID is of the internal block, NOT any of the returned accounts.' in: query name: min_id type: string - default: 40 description: Number of blocked accounts to return. in: query maximum: 80 minimum: 1 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: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 parameters: - default: 30 description: Number of statuses to return. in: query name: limit type: integer - description: Return only bookmarked statuses *OLDER* than the given bookmark ID. The status with the corresponding bookmark ID will not be included in the response. in: query name: max_id type: string - description: Return only bookmarked statuses *NEWER* than the given bookmark ID. The status with the corresponding bookmark ID will not be included in the response. in: query name: min_id type: string 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/conversation/{id}/read: post: operationId: conversationRead parameters: - description: ID of the conversation. in: path name: id required: true type: string produces: - application/json responses: "200": description: Updated conversation. schema: $ref: '#/definitions/conversation' "400": description: bad request "401": description: unauthorized "404": description: not found "406": description: not acceptable "422": description: unprocessable content "500": description: internal server error security: - OAuth2 Bearer: - write:conversations summary: Mark a conversation with the given ID as read. tags: - conversations /api/v1/conversations: get: description: |- The next and previous queries can be parsed from the returned Link header. Example: ``` ; rel="next", ; rel="prev" ```` operationId: conversationsGet parameters: - description: 'Return only conversations with last statuses *OLDER* than the given max ID. The conversation with the specified ID will not be included in the response. NOTE: The ID is a status ID. Use the Link header for pagination.' in: query name: max_id type: string - description: 'Return only conversations with last statuses *NEWER* than the given since ID. The conversation with the specified ID will not be included in the response. NOTE: The ID is a status ID. Use the Link header for pagination.' in: query name: since_id type: string - description: 'Return only conversations with last statuses *IMMEDIATELY NEWER* than the given min ID. The conversation with the specified ID will not be included in the response. NOTE: The ID is a status ID. Use the Link header for pagination.' in: query name: min_id type: string - default: 40 description: Number of conversations to return. in: query maximum: 80 minimum: 1 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/conversation' 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:statuses summary: Get an array of (direct message) conversations that requesting account is involved in. tags: - conversations /api/v1/conversations/{id}: delete: description: |- This doesn't delete the actual statuses in the conversation, nor does it prevent a new conversation from being created later from the same thread and participants. operationId: conversationDelete parameters: - description: ID of the conversation in: path name: id required: true type: string produces: - application/json responses: "200": description: conversation 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:conversations summary: Delete a single conversation with the given ID. tags: - conversations /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/exports/blocks.csv: get: operationId: exportBlocks produces: - text/csv responses: "200": description: CSV file of accounts that you block. "401": description: unauthorized "406": description: not acceptable "500": description: internal server error security: - OAuth2 Bearer: - read:blocks summary: Export a CSV file of accounts that you block. tags: - import-export /api/v1/exports/followers.csv: get: operationId: exportFollowers produces: - text/csv responses: "200": description: CSV file of accounts that follow you. "401": description: unauthorized "406": description: not acceptable "500": description: internal server error security: - OAuth2 Bearer: - read:follows summary: Export a CSV file of accounts that follow you. tags: - import-export /api/v1/exports/following.csv: get: operationId: exportFollowing produces: - text/csv responses: "200": description: CSV file of accounts that you follow. "401": description: unauthorized "406": description: not acceptable "500": description: internal server error security: - OAuth2 Bearer: - read:follows summary: Export a CSV file of accounts that you follow. tags: - import-export /api/v1/exports/lists.csv: get: operationId: exportLists produces: - text/csv responses: "200": description: CSV file of lists. "401": description: unauthorized "406": description: not acceptable "500": description: internal server error security: - OAuth2 Bearer: - read:lists summary: Export a CSV file of lists created by you. tags: - import-export /api/v1/exports/mutes.csv: get: operationId: exportMutes produces: - text/csv responses: "200": description: CSV file of accounts that you mute. "401": description: unauthorized "406": description: not acceptable "500": description: internal server error security: - OAuth2 Bearer: - read:mutes summary: Export a CSV file of accounts that you mute. tags: - import-export /api/v1/exports/stats: get: operationId: exportStats produces: - application/json responses: "200": description: Export stats for the requesting account. schema: $ref: '#/definitions/accountExportStats' "401": description: unauthorized "406": description: not acceptable "500": description: internal server error security: - OAuth2 Bearer: - read:account summary: Returns informational stats on the number of items that can be exported for requesting account. tags: - import-export /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: - tags /api/v1/filters: get: operationId: filtersV1Get produces: - application/json responses: "200": description: Requested filters. schema: items: $ref: '#/definitions/filterV1' 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:filters summary: Get all filters for the authenticated account. tags: - filters post: consumes: - application/json - application/xml - application/x-www-form-urlencoded operationId: filterV1Post parameters: - description: |- The text to be filtered. Sample: fnord in: formData maxLength: 40 minLength: 1 name: phrase required: true type: string - collectionFormat: multi description: |- The contexts in which the filter should be applied. Sample: home, public enum: - home - notifications - public - thread - account in: formData items: type: string minItems: 1 name: context[] required: true type: array uniqueItems: true - description: |- Number of seconds from now that the filter should expire. If omitted, filter never expires. Sample: 86400 in: formData name: expires_in type: number - default: false description: |- Should matching entities be removed from the user's timelines/views, instead of hidden? Not supported yet. Sample: false in: formData name: irreversible type: boolean - default: false description: |- Should the filter consider word boundaries? Sample: true in: formData name: whole_word type: boolean produces: - application/json responses: "200": description: New filter. schema: $ref: '#/definitions/filterV1' "400": description: bad request "401": description: unauthorized "403": description: forbidden to moved accounts "404": description: not found "406": description: not acceptable "409": description: conflict (duplicate keyword) "422": description: unprocessable content "500": description: internal server error security: - OAuth2 Bearer: - write:filters summary: Create a single filter. tags: - filters /api/v1/filters/{id}: delete: operationId: filterV1Delete parameters: - description: ID of the filter in: path name: id required: true type: string produces: - application/json responses: "200": description: filter 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:filters summary: Delete a single filter with the given ID. tags: - filters get: operationId: filterV1Get parameters: - description: ID of the filter in: path name: id required: true type: string produces: - application/json responses: "200": description: Requested filter. schema: $ref: '#/definitions/filterV1' "400": description: bad request "401": description: unauthorized "404": description: not found "406": description: not acceptable "500": description: internal server error security: - OAuth2 Bearer: - read:filters summary: Get a single filter with the given ID. tags: - filters put: consumes: - application/json - application/xml - application/x-www-form-urlencoded operationId: filterV1Put parameters: - description: ID of the filter. in: path name: id required: true type: string - description: |- The text to be filtered. Sample: fnord in: formData maxLength: 40 minLength: 1 name: phrase required: true type: string - collectionFormat: multi description: |- The contexts in which the filter should be applied. Sample: home, public enum: - home - notifications - public - thread - account in: formData items: type: string minItems: 1 name: context[] required: true type: array uniqueItems: true - description: |- Number of seconds from now that the filter should expire. If omitted, filter never expires. Sample: 86400 in: formData name: expires_in type: number - default: false description: |- Should matching entities be removed from the user's timelines/views, instead of hidden? Not supported yet. Sample: false in: formData name: irreversible type: boolean - default: false description: |- Should the filter consider word boundaries? Sample: true in: formData name: whole_word type: boolean produces: - application/json responses: "200": description: Updated filter. schema: $ref: '#/definitions/filterV1' "400": description: bad request "401": description: unauthorized "403": description: forbidden to moved accounts "404": description: not found "406": description: not acceptable "409": description: conflict (duplicate keyword) "422": description: unprocessable content "500": description: internal server error security: - OAuth2 Bearer: - write:filters summary: Update a single filter with the given ID. tags: - filters /api/v1/follow_requests: get: description: |- The next and previous queries can be parsed from the returned Link header. Example: ``` ; rel="next", ; rel="prev" ```` operationId: getFollowRequests parameters: - description: 'Return only follow requesting accounts *OLDER* than the given max ID. The follow requester with the specified ID will not be included in the response. NOTE: the ID is of the internal follow request, NOT any of the returned accounts.' in: query name: max_id type: string - description: 'Return only follow requesting accounts *NEWER* than the given since ID. The follow requester with the specified ID will not be included in the response. NOTE: the ID is of the internal follow request, NOT any of the returned accounts.' in: query name: since_id type: string - description: 'Return only follow requesting accounts *IMMEDIATELY NEWER* than the given min ID. The follow requester with the specified ID will not be included in the response. NOTE: the ID is of the internal follow request, NOT any of the returned accounts.' in: query name: min_id type: string - default: 40 description: Number of follow requesting accounts to return. in: query maximum: 80 minimum: 1 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/followed_tags: get: operationId: getFollowedTags parameters: - description: 'Return only followed tags *OLDER* than the given max ID. The followed tag with the specified ID will not be included in the response. NOTE: the ID is of the internal followed tag, NOT a tag name.' in: query name: max_id type: string - description: 'Return only followed tags *NEWER* than the given since ID. The followed tag with the specified ID will not be included in the response. NOTE: the ID is of the internal followed tag, NOT a tag name.' in: query name: since_id type: string - description: 'Return only followed tags *IMMEDIATELY NEWER* than the given min ID. The followed tag with the specified ID will not be included in the response. NOTE: the ID is of the internal followed tag, NOT a tag name.' in: query name: min_id type: string - default: 100 description: Number of followed tags to return. in: query maximum: 200 minimum: 1 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/tag' 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 all hashtags that you currently follow. tags: - tags /api/v1/import: post: consumes: - multipart/form-data description: |- This can be used to migrate data from a Mastodon-compatible CSV file to a GoToSocial account. Uploaded data will be processed asynchronously, and not all entries may be processed depending on domain blocks, user-level blocks, network availability of referenced accounts and statuses, etc. operationId: importData parameters: - description: The CSV data file to upload. in: formData name: data required: true type: file - description: |- Type of entries contained in the data file: - `following` - accounts to follow. - `blocks` - accounts to block. in: formData name: type required: true type: string - default: merge description: |- Mode to use when creating entries from the data file: - `merge` to merge entries in file with existing entries. - `overwrite` to replace existing entries with entries in file. in: formData name: mode type: string produces: - application/json responses: "202": description: Upload accepted. "400": description: bad request "401": description: unauthorized "406": description: not acceptable "500": description: internal server error security: - OAuth2 Bearer: - write:accounts summary: Upload some CSV-formatted data to your account. tags: - import-export /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 maxLength: 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 maxLength: 500 name: short_description type: string - allowEmptyValue: true description: Longer description of the instance. in: formData maxLength: 5000 name: description type: string - allowEmptyValue: true description: Terms and conditions of the instance. in: formData maxLength: 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/instanceV1' "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/instance/rules: get: description: The rules will be returned in order (sorted by Order ascending). operationId: rules produces: - application/json responses: "200": description: An array with all the rules for the local instance. schema: items: $ref: '#/definitions/instanceRule' type: array "400": description: bad request "404": description: not found "406": description: not acceptable "500": description: internal server error summary: View instance rules (public). tags: - instance /api/v1/interaction_policies/defaults: get: operationId: policiesDefaultsGet produces: - application/json responses: "200": description: A default policies object containing a policy for each status visibility. schema: $ref: '#/definitions/defaultPolicies' "401": description: unauthorized "406": description: not acceptable "500": description: internal server error security: - OAuth2 Bearer: - read:accounts summary: Get default interaction policies for new statuses created by you. tags: - interaction_policies patch: consumes: - multipart/form-data - application/x-www-form-urlencoded - application/json description: |- If submitting using form data, use the following pattern: `VISIBILITY[INTERACTION_TYPE][CONDITION][INDEX]=Value` For example: `public[can_reply][always][0]=author` Using `curl` this might look something like: `curl -F 'public[can_reply][always][0]=author' -F 'public[can_reply][always][1]=followers'` The JSON equivalent would be: `curl -H 'Content-Type: application/json' -d '{"public":{"can_reply":{"always":["author","followers"]}}}'` Any visibility level left unspecified in the request body will be returned to the default. Ie., in the example above, "public" would be updated, but "unlisted", "private", and "direct" would be reset to defaults. The server will perform some normalization on submitted policies so that you can't submit totally invalid policies. operationId: policiesDefaultsUpdate parameters: - description: Nth entry for public.can_favourite.always. in: formData name: public[can_favourite][always][0] type: string - description: Nth entry for public.can_favourite.with_approval. in: formData name: public[can_favourite][with_approval][0] type: string - description: Nth entry for public.can_reply.always. in: formData name: public[can_reply][always][0] type: string - description: Nth entry for public.can_reply.with_approval. in: formData name: public[can_reply][with_approval][0] type: string - description: Nth entry for public.can_reblog.always. in: formData name: public[can_reblog][always][0] type: string - description: Nth entry for public.can_reblog.with_approval. in: formData name: public[can_reblog][with_approval][0] type: string - description: Nth entry for unlisted.can_favourite.always. in: formData name: unlisted[can_favourite][always][0] type: string - description: Nth entry for unlisted.can_favourite.with_approval. in: formData name: unlisted[can_favourite][with_approval][0] type: string - description: Nth entry for unlisted.can_reply.always. in: formData name: unlisted[can_reply][always][0] type: string - description: Nth entry for unlisted.can_reply.with_approval. in: formData name: unlisted[can_reply][with_approval][0] type: string - description: Nth entry for unlisted.can_reblog.always. in: formData name: unlisted[can_reblog][always][0] type: string - description: Nth entry for unlisted.can_reblog.with_approval. in: formData name: unlisted[can_reblog][with_approval][0] type: string - description: Nth entry for private.can_favourite.always. in: formData name: private[can_favourite][always][0] type: string - description: Nth entry for private.can_favourite.with_approval. in: formData name: private[can_favourite][with_approval][0] type: string - description: Nth entry for private.can_reply.always. in: formData name: private[can_reply][always][0] type: string - description: Nth entry for private.can_reply.with_approval. in: formData name: private[can_reply][with_approval][0] type: string - description: Nth entry for private.can_reblog.always. in: formData name: private[can_reblog][always][0] type: string - description: Nth entry for private.can_reblog.with_approval. in: formData name: private[can_reblog][with_approval][0] type: string - description: Nth entry for direct.can_favourite.always. in: formData name: direct[can_favourite][always][0] type: string - description: Nth entry for direct.can_favourite.with_approval. in: formData name: direct[can_favourite][with_approval][0] type: string - description: Nth entry for direct.can_reply.always. in: formData name: direct[can_reply][always][0] type: string - description: Nth entry for direct.can_reply.with_approval. in: formData name: direct[can_reply][with_approval][0] type: string - description: Nth entry for direct.can_reblog.always. in: formData name: direct[can_reblog][always][0] type: string - description: Nth entry for direct.can_reblog.with_approval. in: formData name: direct[can_reblog][with_approval][0] type: string produces: - application/json responses: "200": description: Updated default policies object containing a policy for each status visibility. schema: $ref: '#/definitions/defaultPolicies' "400": description: bad request "401": description: unauthorized "406": description: not acceptable "422": description: unprocessable "500": description: internal server error security: - OAuth2 Bearer: - write:accounts summary: Update default interaction policies per visibility level for new statuses created by you. tags: - interaction_policies /api/v1/interaction_requests: get: description: |- ``` ; rel="next", ; rel="prev" ```` operationId: getInteractionRequests parameters: - description: If set, then only interactions targeting the given status_id will be included in the results. in: query name: status_id type: string - default: true description: If true or not set, pending favourites will be included in the results. At least one of favourites, replies, and reblogs must be true. in: query name: favourites type: boolean - default: true description: If true or not set, pending replies will be included in the results. At least one of favourites, replies, and reblogs must be true. in: query name: replies type: boolean - default: true description: If true or not set, pending reblogs will be included in the results. At least one of favourites, replies, and reblogs must be true. in: query name: reblogs type: boolean - description: Return only interaction requests *OLDER* than the given max ID. The interaction with the specified ID will not be included in the response. in: query name: max_id type: string - description: Return only interaction requests *NEWER* than the given since ID. The interaction with the specified ID will not be included in the response. in: query name: since_id type: string - description: Return only interaction requests *IMMEDIATELY NEWER* than the given min ID. The interaction with the specified ID will not be included in the response. in: query name: min_id type: string - default: 40 description: Number of interaction requests to return. in: query maximum: 80 minimum: 1 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/interactionRequest' 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 an array of interactions requested on your statuses by other accounts, and pending your approval. tags: - interaction_requests /api/v1/interaction_requests/{id}: get: operationId: getInteractionRequest parameters: - description: ID of the interaction request targeting you. in: path name: id required: true type: string produces: - application/json responses: "200": description: Interaction request. schema: $ref: '#/definitions/interactionRequest' "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 interaction request with the given ID. tags: - interaction_requests /api/v1/interaction_requests/{id}/authorize: post: operationId: authorizeInteractionRequest parameters: - description: ID of the interaction request targeting you. in: path name: id required: true type: string produces: - application/json responses: "200": description: The now-approved interaction request. schema: $ref: '#/definitions/interactionRequest' "400": description: bad request "401": description: unauthorized "404": description: not found "406": description: not acceptable "500": description: internal server error security: - OAuth2 Bearer: - write:statuses summary: Accept/authorize/approve an interaction request with the given ID. tags: - interaction_requests /api/v1/interaction_requests/{id}/reject: post: operationId: rejectInteractionRequest parameters: - description: ID of the interaction request targeting you. in: path name: id required: true type: string produces: - application/json responses: "200": description: The now-rejected interaction request. schema: $ref: '#/definitions/interactionRequest' "400": description: bad request "401": description: unauthorized "404": description: not found "406": description: not acceptable "500": description: internal server error security: - OAuth2 Bearer: - write:statuses summary: Reject an interaction request with the given ID. tags: - interaction_requests /api/v1/lists: get: operationId: lists produces: - application/json responses: "200": description: Array of all lists owned by the requesting user. schema: items: $ref: '#/definitions/list' 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:lists summary: Get all lists for owned by authorized user. tags: - lists post: consumes: - application/json - application/xml - application/x-www-form-urlencoded operationId: listCreate parameters: - description: |- Title of this list. Sample: Cool People in: formData name: title required: true type: string x-go-name: Title - default: list description: |- RepliesPolicy for this list. followed = Show replies to any followed user list = Show replies to members of the list none = Show replies to no one Sample: list enum: - followed - list - none in: formData name: replies_policy type: string x-go-name: RepliesPolicy - default: false description: Hide posts from members of this list from your home timeline. in: formData name: exclusive type: boolean x-go-name: Exclusive produces: - application/json responses: "200": description: The newly created list. schema: $ref: '#/definitions/list' "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:lists summary: Create a new list. tags: - lists /api/v1/lists/{id}: delete: operationId: listDelete parameters: - description: ID of the list in: path name: id required: true type: string produces: - application/json responses: "200": description: list 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:lists summary: Delete a single list with the given ID. tags: - lists get: operationId: list parameters: - description: ID of the list in: path name: id required: true type: string produces: - application/json responses: "200": description: Requested list. schema: $ref: '#/definitions/list' "400": description: bad request "401": description: unauthorized "404": description: not found "406": description: not acceptable "500": description: internal server error security: - OAuth2 Bearer: - read:lists summary: Get a single list with the given ID. tags: - lists put: consumes: - application/json - application/xml - application/x-www-form-urlencoded operationId: listUpdate parameters: - description: ID of the list in: path name: id required: true type: string - description: |- Title of this list. Sample: Cool People in: formData name: title type: string - description: |- RepliesPolicy for this list. followed = Show replies to any followed user list = Show replies to members of the list none = Show replies to no one Sample: list enum: - followed - list - none in: formData name: replies_policy type: string - description: Hide posts from members of this list from your home timeline. in: formData name: exclusive type: boolean produces: - application/json responses: "200": description: The newly updated list. schema: $ref: '#/definitions/list' "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:lists summary: Update an existing list. tags: - lists /api/v1/lists/{id}/accounts: delete: consumes: - application/json - application/xml - application/x-www-form-urlencoded operationId: removeListAccounts parameters: - description: ID of the list in: path name: id required: true type: string - collectionFormat: multi description: Array of accountIDs to modify. Each accountID must correspond to an account that the requesting account follows. in: formData items: type: string name: account_ids[] required: true type: array produces: - application/json responses: "200": description: list accounts updated "400": description: bad request "401": description: unauthorized "404": description: not found "406": description: not acceptable "500": description: internal server error security: - OAuth2 Bearer: - read:lists summary: Remove one or more accounts from the given list. tags: - lists get: description: |- 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: listAccounts parameters: - description: ID of the list in: path name: id required: true type: string - description: Return only list entries *OLDER* than the given max ID. The account from the list entry with the specified ID will not be included in the response. in: query name: max_id type: string - description: Return only list entries *NEWER* than the given since ID. The account from the list entry with the specified ID will not be included in the response. in: query name: since_id type: string - description: Return only list entries *IMMEDIATELY NEWER* than the given min ID. The account from the list entry with the specified ID will not be included in the response. in: query name: min_id type: string - default: 40 description: 'Number of accounts to return. If set to 0 explicitly, all accounts in the list will be returned, and pagination headers will not be used. This is a workaround for Mastodon API peculiarities: https://docs.joinmastodon.org/methods/lists/#query-parameters.' in: query maximum: 80 minimum: 0 name: limit type: integer produces: - application/json responses: "200": description: Array of accounts. 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:lists summary: Page through accounts in this list. tags: - lists post: consumes: - application/json - application/xml - application/x-www-form-urlencoded operationId: addListAccounts parameters: - description: ID of the list in: path name: id required: true type: string - collectionFormat: multi description: Array of accountIDs to modify. Each accountID must correspond to an account that the requesting account follows. in: formData items: type: string name: account_ids[] required: true type: array produces: - application/json responses: "200": description: list accounts updated "400": description: bad request "401": description: unauthorized "404": description: not found "406": description: not acceptable "500": description: internal server error security: - OAuth2 Bearer: - read:lists summary: Add one or more accounts to the given list. tags: - lists /api/v1/markers: get: description: Get timeline markers by name operationId: markersGet parameters: - description: Timelines to retrieve. in: query items: enum: - home - notifications type: string name: timeline type: array produces: - application/json responses: "200": description: Requested markers schema: $ref: '#/definitions/markers' "400": description: bad request "401": description: unauthorized "500": description: internal server error security: - OAuth2 Bearer: - read:statuses tags: - markers post: consumes: - multipart/form-data description: Update timeline markers by name operationId: markersPost parameters: - description: Last status ID read on the home timeline. in: formData name: home[last_read_id] type: string - description: Last notification ID read on the notifications timeline. in: formData name: notifications[last_read_id] type: string produces: - application/json responses: "200": description: Requested markers schema: $ref: '#/definitions/markers' "400": description: bad request "401": description: unauthorized "409": description: conflict (when two clients try to update the same timeline at the same time) "500": description: internal server error security: - OAuth2 Bearer: - write:statuses tags: - markers /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/mutes: get: description: |- The next and previous queries can be parsed from the returned Link header. Example: ``` ; rel="next", ; rel="prev" ```` operationId: mutesGet parameters: - description: 'Return only muted accounts *OLDER* than the given max ID. The muted account with the specified ID will not be included in the response. NOTE: the ID is of the internal mute, NOT any of the returned accounts.' in: query name: max_id type: string - description: 'Return only muted accounts *NEWER* than the given since ID. The muted account with the specified ID will not be included in the response. NOTE: the ID is of the internal mute, NOT any of the returned accounts.' in: query name: since_id type: string - description: 'Return only muted accounts *IMMEDIATELY NEWER* than the given min ID. The muted account with the specified ID will not be included in the response. NOTE: the ID is of the internal mute, NOT any of the returned accounts.' in: query name: min_id type: string - default: 40 description: Number of muted accounts to return. in: query maximum: 80 minimum: 1 name: limit type: integer produces: - application/json responses: "200": description: List of muted accounts, including when their mutes expire (if applicable). headers: Link: description: Links to the next and previous queries. type: string schema: items: $ref: '#/definitions/mutedAccount' 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:mutes summary: Get an array of accounts that requesting account has muted. tags: - mutes /api/v1/notification/{id}: get: operationId: notification parameters: - description: The ID of the notification. in: path name: id required: true type: string 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 - description: Types of notifications to include. If not provided, all notification types will be included. in: query items: enum: - follow - follow_request - mention - reblog - favourite - poll - status - admin.sign_up type: string name: types[] type: array - description: Types of notifications to exclude. in: query items: enum: - follow - follow_request - mention - reblog - favourite - poll - status - admin.sign_up 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 /api/v1/notifications/clear: 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/polls/{id}: get: operationId: poll parameters: - description: Target poll ID. in: path name: id required: true type: string produces: - application/json responses: "200": description: The requested poll. schema: $ref: '#/definitions/poll' "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 poll with given ID. tags: - polls /api/v1/polls/{id}/votes: post: operationId: pollVote parameters: - description: Target poll ID. in: path name: id required: true type: string - description: Poll choice indices on which to vote. in: formData items: type: integer name: choices required: true type: array produces: - application/json responses: "200": description: The updated poll with user vote choices. schema: $ref: '#/definitions/poll' "400": description: bad request "401": description: unauthorized "403": description: forbidden "404": description: not found "406": description: not acceptable "422": description: unprocessable entity "500": description: internal server error security: - OAuth2 Bearer: - write:statuses summary: Vote with choices in the given poll. tags: - polls /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/profile/avatar: delete: description: If the account doesn't have an avatar, the call succeeds anyway. operationId: accountAvatarDelete produces: - application/json responses: "200": description: The updated account, including profile source information. schema: $ref: '#/definitions/account' "400": description: bad request "401": description: unauthorized "403": description: forbidden "406": description: not acceptable "500": description: internal server error security: - OAuth2 Bearer: - admin summary: Delete the authenticated account's avatar. tags: - accounts /api/v1/profile/header: delete: description: If the account doesn't have a header, the call succeeds anyway. operationId: accountHeaderDelete produces: - application/json responses: "200": description: The updated account, including profile source information. schema: $ref: '#/definitions/account' "400": description: bad request "401": description: unauthorized "403": description: forbidden "406": description: not acceptable "500": description: internal server error security: - OAuth2 Bearer: - admin summary: Delete the authenticated account's header. tags: - accounts /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 (for paging downwards). 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. in: query name: since_id type: string - description: Return only reports immediately *NEWER* than the given min ID (for paging upwards). The report with the specified ID will not be included in the response. in: query name: min_id type: string - default: 20 description: Number of reports to return. in: query maximum: 100 minimum: 1 name: limit type: integer produces: - application/json responses: "200": description: Array of reports. headers: Link: description: Links to the next and previous queries. type: string 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. Sample: 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. Sample: ["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. Sample: 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? Sample: 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. Sample: 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. Sample: ["01GPBN5YDY6JKBWE44H7YQBDCQ","01GPBN65PDWSBPWVDD0SQCFFY3"] in: formData items: type: string 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/statuses: post: consumes: - application/json - 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 'interaction_policy' field can be used to set an interaction policy for this status. If submitting using form data, use the following pattern to set an interaction policy: `interaction_policy[INTERACTION_TYPE][CONDITION][INDEX]=Value` For example: `interaction_policy[can_reply][always][0]=author` Using `curl` this might look something like: `curl -F 'interaction_policy[can_reply][always][0]=author' -F 'interaction_policy[can_reply][always][1]=followers' [... other form fields ...]` The JSON equivalent would be: `curl -H 'Content-Type: application/json' -d '{"interaction_policy":{"can_reply":{"always":["author","followers"]}} [... other json fields ...]}'` The server will perform some normalization on the submitted policy so that you can't submit something totally invalid. 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: |- Array of possible poll answers. If provided, media_ids cannot be used, and poll[expires_in] must be provided. in: formData items: type: string name: poll[options][] type: array x-go-name: PollOptions - description: |- Duration the poll should be open, in seconds. If provided, media_ids cannot be used, and poll[options] must be provided. format: int64 in: formData name: poll[expires_in] type: integer x-go-name: PollExpiresIn - default: false description: Allow multiple choices on this poll. in: formData name: poll[multiple] type: boolean x-go-name: PollMultiple - default: true description: Hide vote counts until the poll ends. in: formData name: poll[hide_totals] type: boolean x-go-name: PollHideTotals - 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. enum: - public - unlisted - private - mutuals_only - direct in: formData name: visibility type: string x-go-name: Visibility - default: false description: If set to true, this status will be "local only" and will NOT be federated beyond the local timeline(s). If set to false (default), this status will be federated to your followers beyond the local timeline(s). in: formData name: local_only type: boolean x-go-name: LocalOnly - description: '***DEPRECATED***. Included for back compat only. Only used if set and local_only is not yet. If set to true, this status will be federated beyond the local timeline(s). If set to false, this status will NOT be federated beyond the local timeline(s).' in: formData name: federated type: boolean x-go-name: Federated - 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. This feature isn't implemented yet; attemping to set it will return 501 Not Implemented. 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. enum: - text/plain - text/markdown in: formData name: content_type type: string x-go-name: ContentType - description: Nth entry for interaction_policy.can_favourite.always. in: formData name: interaction_policy[can_favourite][always][0] type: string - description: Nth entry for interaction_policy.can_favourite.with_approval. in: formData name: interaction_policy[can_favourite][with_approval][0] type: string - description: Nth entry for interaction_policy.can_reply.always. in: formData name: interaction_policy[can_reply][always][0] type: string - description: Nth entry for interaction_policy.can_reply.with_approval. in: formData name: interaction_policy[can_reply][with_approval][0] type: string - description: Nth entry for interaction_policy.can_reblog.always. in: formData name: interaction_policy[can_reblog][always][0] type: string - description: Nth entry for interaction_policy.can_reblog.with_approval. in: formData name: interaction_policy[can_reblog][with_approval][0] type: string 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 "501": description: scheduled_at was set, but this feature is not yet implemented security: - OAuth2 Bearer: - write:statuses summary: Create a new status using the given form field parameters. tags: - statuses put: consumes: - application/json - 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'. operationId: statusEdit 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: |- Array of possible poll answers. If provided, media_ids cannot be used, and poll[expires_in] must be provided. in: formData items: type: string name: poll[options][] type: array x-go-name: PollOptions - description: |- Duration the poll should be open, in seconds. If provided, media_ids cannot be used, and poll[options] must be provided. format: int64 in: formData name: poll[expires_in] type: integer x-go-name: PollExpiresIn - default: false description: Allow multiple choices on this poll. in: formData name: poll[multiple] type: boolean x-go-name: PollMultiple - default: true description: Hide vote counts until the poll ends. in: formData name: poll[hide_totals] type: boolean x-go-name: PollHideTotals - 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: 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. enum: - text/plain - text/markdown in: formData name: content_type type: string x-go-name: ContentType produces: - application/json responses: "200": description: The latest status revision. 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: Edit an existing status using the given form field parameters. 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: threadContext parameters: - description: Target status ID. in: path name: id required: true type: string produces: - application/json responses: "200": description: Thread context object. schema: $ref: '#/definitions/threadContext' "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}/history: get: description: 'UNIMPLEMENTED: Currently this endpoint will always return an array of length 1, containing only the latest/current version of the status.' operationId: statusHistoryGet parameters: - description: Target status ID. in: path name: id required: true type: string produces: - application/json responses: "200": description: "" schema: items: $ref: '#/definitions/statusEdit' 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:statuses summary: View edit history of status with the given ID. tags: - statuses /api/v1/statuses/{id}/mute: post: description: |- Target status must belong to you or mention you. Status thread mutes and unmutes are idempotent. If you already mute a thread, muting it again just means it stays muted and you'll get 200 OK back. operationId: statusMute parameters: - description: Target status ID. in: path name: id required: true type: string produces: - application/json responses: "200": description: The now-muted status. schema: $ref: '#/definitions/status' "400": description: bad request; you're not part of the target status thread "401": description: unauthorized "403": description: forbidden "404": description: not found "406": description: not acceptable "500": description: internal server error security: - OAuth2 Bearer: - write:mutes summary: Mute a status's thread. This prevents notifications from being created for future replies, likes, boosts etc in the thread of which the target status is a part. 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}/source: get: operationId: statusSourceGet parameters: - description: Target status ID. in: path name: id required: true type: string produces: - application/json responses: "200": description: "" schema: items: $ref: '#/definitions/statusSource' 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:statuses summary: View source text of status with the given ID. Requester must own the 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}/unmute: post: description: |- Target status must belong to you or mention you. Status thread mutes and unmutes are idempotent. If you already unmuted a thread, unmuting it again just means it stays unmuted and you'll get 200 OK back. operationId: statusUnmute parameters: - description: Target status ID. in: path name: id required: true type: string produces: - application/json responses: "200": description: The now-unmuted status. schema: $ref: '#/definitions/status' "400": description: bad request; you're not part of the target status thread "401": description: unauthorized "403": description: forbidden "404": description: not found "406": description: not acceptable "500": description: internal server error security: - OAuth2 Bearer: - write:mutes summary: Unmute a status's thread. This reenables notifications for future replies, likes, boosts etc in the thread of which the target status is a part. 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 - description: |- ID of the list to subscribe to. Only used if stream type is 'list'. in: query name: list type: string - description: |- Name of the tag to subscribe to. Only used if stream type is 'hashtag' or 'hashtag:local'. in: query name: tag 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`: filters (including keywords and statuses) have changed. 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. If `event` = `filters_changed`, then there is no payload. 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/tags/{tag_name}: get: description: If the tag does not exist, this method will not create it in the database. operationId: getTag parameters: - description: Name of the tag (no leading `#`) in: path name: tag_name required: true type: string produces: - application/json responses: "200": description: Info about the tag. schema: $ref: '#/definitions/tag' "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 details for a hashtag, including whether you currently follow it. tags: - tags /api/v1/tags/{tag_name}/follow: post: description: 'Idempotent: if you are already following the tag, this call will still succeed.' operationId: followTag parameters: - description: Name of the tag (no leading `#`) in: path name: tag_name required: true type: string produces: - application/json responses: "200": description: Info about the tag. schema: $ref: '#/definitions/tag' "400": description: bad request "401": description: unauthorized "403": description: forbidden "500": description: internal server error security: - OAuth2 Bearer: - write:follows summary: Follow a hashtag. tags: - tags /api/v1/tags/{tag_name}/unfollow: post: description: 'Idempotent: if you are not following the tag, this call will still succeed.' operationId: unfollowTag parameters: - description: Name of the tag (no leading `#`) in: path name: tag_name required: true type: string produces: - application/json responses: "200": description: Info about the tag. schema: $ref: '#/definitions/tag' "400": description: bad request "401": description: unauthorized "403": description: forbidden "404": description: unauthorized "500": description: internal server error security: - OAuth2 Bearer: - write:follows summary: Unfollow a hashtag. tags: - tags /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/list/{id}: 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: listTimeline parameters: - description: ID of the list in: path name: id required: true type: string - 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 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:lists summary: See statuses/posts from the given list timeline. 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/timelines/tag/{tag_name}: 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: tagTimeline parameters: - description: Name of the tag in: path name: tag_name required: true type: string - 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 maximum: 40 minimum: 1 name: limit type: integer 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 that use the given hashtag (case insensitive). tags: - timelines /api/v1/user: get: operationId: getUser produces: - application/json responses: "200": description: The requested user. schema: $ref: '#/definitions/user' "400": description: bad request "401": description: unauthorized "403": description: forbidden "406": description: not acceptable "500": description: internal error security: - OAuth2 Bearer: - read:user summary: Get your own user model. tags: - user /api/v1/user/email_change: post: consumes: - application/json - application/xml - application/x-www-form-urlencoded operationId: userEmailChange parameters: - description: User's current password, for verification. in: formData name: password required: true type: string x-go-name: Password - description: Desired new email address. in: formData name: new_email required: true type: string x-go-name: NewEmail produces: - application/json responses: "202": description: 'Accepted: email change is processing; check your inbox to confirm new address.' schema: $ref: '#/definitions/user' "400": description: bad request "401": description: unauthorized "403": description: forbidden "406": description: not acceptable "409": description: 'Conflict: desired email address already in use' "500": description: internal error security: - OAuth2 Bearer: - write:user summary: Request changing the email address of authenticated user. tags: - user /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 "422": description: unprocessable request because instance is running with OIDC backend "500": description: internal error security: - OAuth2 Bearer: - write:user summary: Change the password of authenticated user. tags: - user /api/v2/admin/accounts: get: description: |- Returned accounts will be ordered alphabetically (a-z) by domain + username. The next and previous queries can be parsed from the returned Link header. Example: ``` ; rel="next", ; rel="prev" ```` operationId: adminAccountsGetV2 parameters: - description: Filter for `local` or `remote` accounts. in: query name: origin type: string - description: Filter for `active`, `pending`, `disabled`, `silenced`, or `suspended` accounts. in: query name: status type: string - description: Filter for accounts with staff permissions (users that can manage reports). in: query name: permissions type: string - description: Filter for users with these roles. in: query items: type: string name: role_ids[] type: array - description: Lookup users invited by the account with this ID. in: query name: invited_by type: string - description: Search for the given username. in: query name: username type: string - description: Search for the given display name. in: query name: display_name type: string - description: Filter by the given domain. in: query name: by_domain type: string - description: Lookup a user with this email. in: query name: email type: string - description: Lookup users with this IP address. in: query name: ip type: string - description: max_id in the form `[domain]/@[username]`. All results returned will be later in the alphabet than `[domain]/@[username]`. For example, if max_id = `example.org/@someone` then returned entries might contain `example.org/@someone_else`, `later.example.org/@someone`, etc. Local account IDs in this form use an empty string for the `[domain]` part, for example local account with username `someone` would be `/@someone`. in: query name: max_id type: string - description: min_id in the form `[domain]/@[username]`. All results returned will be earlier in the alphabet than `[domain]/@[username]`. For example, if min_id = `example.org/@someone` then returned entries might contain `example.org/@earlier_account`, `earlier.example.org/@someone`, etc. Local account IDs in this form use an empty string for the `[domain]` part, for example local account with username `someone` would be `/@someone`. in: query name: min_id type: string - default: 50 description: Maximum number of results to return. in: query maximum: 200 minimum: 1 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/adminAccountInfo' 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 + page through known accounts according to given filters. tags: - admin /api/v2/filters: get: operationId: filtersV2Get produces: - application/json responses: "200": description: Requested filters. schema: items: $ref: '#/definitions/filterV2' 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:filters summary: Get all filters for the authenticated account. tags: - filters post: consumes: - application/json - application/xml - application/x-www-form-urlencoded operationId: filterV2Post parameters: - description: |- The name of the filter. Sample: illuminati nonsense in: formData maxLength: 200 minLength: 1 name: title required: true type: string - collectionFormat: multi description: |- The contexts in which the filter should be applied. Sample: home, public enum: - home - notifications - public - thread - account in: formData items: type: string minItems: 1 name: context[] required: true type: array uniqueItems: true - description: |- Number of seconds from now that the filter should expire. If omitted, filter never expires. Sample: 86400 in: formData name: expires_in type: number - default: warn description: |- The action to be taken when a status matches this filter. Sample: warn enum: - warn - hide in: formData name: filter_action type: string - collectionFormat: multi description: Keywords to be added (if not using id param) or updated (if using id param). in: formData items: type: string name: keywords_attributes[][keyword] type: array - collectionFormat: multi description: Should each keyword consider word boundaries? in: formData items: type: boolean name: keywords_attributes[][whole_word] type: array - collectionFormat: multi description: Statuses to be added to the filter. in: formData items: type: string name: statuses_attributes[][status_id] type: array produces: - application/json responses: "200": description: New filter. schema: $ref: '#/definitions/filterV2' "400": description: bad request "401": description: unauthorized "403": description: forbidden to moved accounts "404": description: not found "406": description: not acceptable "409": description: conflict (duplicate title, keyword, or status) "422": description: unprocessable content "500": description: internal server error security: - OAuth2 Bearer: - write:filters summary: Create a single filter. tags: - filters /api/v2/filters/{id}: delete: operationId: filterV2Delete parameters: - description: ID of the filter in: path name: id required: true type: string produces: - application/json responses: "200": description: filter 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:filters summary: Delete a single filter with the given ID. tags: - filters get: operationId: filterV2Get parameters: - description: ID of the filter in: path name: id required: true type: string produces: - application/json responses: "200": description: Requested filter. schema: $ref: '#/definitions/filterV2' "400": description: bad request "401": description: unauthorized "404": description: not found "406": description: not acceptable "500": description: internal server error security: - OAuth2 Bearer: - read:filters summary: Get a single filter with the given ID. tags: - filters put: consumes: - application/json - application/xml - application/x-www-form-urlencoded description: |- Note that this is actually closer to a PATCH operation: only provided fields will be updated, and omitted fields will remain set to previous values. operationId: filterV2Put parameters: - description: ID of the filter. in: path name: id required: true type: string - description: |- The name of the filter. Sample: illuminati nonsense in: formData maxLength: 200 minLength: 1 name: title required: true type: string - collectionFormat: multi description: Keywords to be added to the created filter. in: formData items: type: string name: keywords_attributes[][keyword] type: array - collectionFormat: multi description: Should each keyword consider word boundaries? in: formData items: type: boolean name: keywords_attributes[][whole_word] type: array - collectionFormat: multi description: Statuses to be added to the newly created filter. in: formData items: type: string name: statuses_attributes[][status_id] type: array - collectionFormat: multi description: |- The contexts in which the filter should be applied. Sample: home, public enum: - home - notifications - public - thread - account in: formData items: type: string minItems: 1 name: context[] required: true type: array uniqueItems: true - description: |- Number of seconds from now that the filter should expire. Sample: 86400 in: formData name: expires_in type: number - description: |- The action to be taken when a status matches this filter. Sample: warn enum: - warn - hide in: formData name: filter_action type: string produces: - application/json responses: "200": description: Updated filter. schema: $ref: '#/definitions/filterV2' "400": description: bad request "401": description: unauthorized "403": description: forbidden to moved accounts "404": description: not found "406": description: not acceptable "409": description: conflict (duplicate title, keyword, or status) "422": description: unprocessable content "500": description: internal server error security: - OAuth2 Bearer: - write:filters summary: Update a single filter with the given ID. tags: - filters /api/v2/filters/{id}/keywords: get: operationId: filterKeywordsGet parameters: - description: ID of the filter in: path name: id required: true type: string produces: - application/json responses: "200": description: Requested filter keywords. schema: items: $ref: '#/definitions/filterKeyword' 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:filters summary: Get all filter keywords for a given filter. tags: - filters post: consumes: - application/json - application/xml - application/x-www-form-urlencoded operationId: filterKeywordPost parameters: - description: ID of the filter to add the filtered status to. in: path name: id required: true type: string - description: |- The text to be filtered Sample: fnord in: formData maxLength: 40 minLength: 1 name: keyword required: true type: string - default: false description: |- Should the filter consider word boundaries? Sample: true in: formData name: whole_word type: boolean produces: - application/json responses: "200": description: New filter keyword. schema: $ref: '#/definitions/filterKeyword' "400": description: bad request "401": description: unauthorized "403": description: forbidden to moved accounts "404": description: not found "406": description: not acceptable "409": description: conflict (duplicate keyword) "422": description: unprocessable content "500": description: internal server error security: - OAuth2 Bearer: - write:filters summary: Add a filter keyword to an existing filter. tags: - filters /api/v2/filters/{id}/statuses: get: operationId: filterStatusesGet parameters: - description: ID of the filter in: path name: id required: true type: string produces: - application/json responses: "200": description: Requested filter statuses. schema: items: $ref: '#/definitions/filterStatus' 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:filters summary: Get all filter statuses for a given filter. tags: - filters post: consumes: - application/json - application/xml - application/x-www-form-urlencoded operationId: filterStatusPost parameters: - description: ID of the filter to add the filtered status to. in: path name: id required: true type: string - description: |- The ID of the status to filter. Sample: 01HXA2NE0K8T1C70K90E74GYD0 in: formData name: status_id required: true type: string produces: - application/json responses: "200": description: New filter status. schema: $ref: '#/definitions/filterStatus' "400": description: bad request "401": description: unauthorized "403": description: forbidden to moved accounts "404": description: not found "406": description: not acceptable "409": description: conflict (duplicate status) "422": description: unprocessable content "500": description: internal server error security: - OAuth2 Bearer: - write:filters summary: Add a filter status to an existing filter. tags: - filters /api/v2/filters/keywords/{id}: delete: operationId: filterKeywordDelete parameters: - description: ID of the filter keyword in: path name: id required: true type: string produces: - application/json responses: "200": description: filter keyword 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:filters summary: Delete a single filter keyword with the given ID. tags: - filters get: operationId: filterKeywordGet parameters: - description: ID of the filter keyword in: path name: id required: true type: string produces: - application/json responses: "200": description: Requested filter keyword. schema: $ref: '#/definitions/filterKeyword' "400": description: bad request "401": description: unauthorized "404": description: not found "406": description: not acceptable "500": description: internal server error security: - OAuth2 Bearer: - read:filters summary: Get a single filter keyword with the given ID. tags: - filters /api/v2/filters/keywords{id}: put: consumes: - application/json - application/xml - application/x-www-form-urlencoded operationId: filterKeywordPut parameters: - description: ID of the filter keyword to update. in: path name: id required: true type: string - description: |- The text to be filtered Sample: fnord in: formData maxLength: 40 minLength: 1 name: keyword required: true type: string - description: |- Should the filter consider word boundaries? Sample: true in: formData name: whole_word type: boolean produces: - application/json responses: "200": description: Updated filter keyword. schema: $ref: '#/definitions/filterKeyword' "400": description: bad request "401": description: unauthorized "403": description: forbidden to moved accounts "404": description: not found "406": description: not acceptable "409": description: conflict (duplicate keyword) "422": description: unprocessable content "500": description: internal server error security: - OAuth2 Bearer: - write:filters summary: Update a single filter keyword with the given ID. tags: - filters /api/v2/filters/statuses/{id}: delete: operationId: filterStatusDelete parameters: - description: ID of the filter status in: path name: id required: true type: string produces: - application/json responses: "200": description: filter status 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:filters summary: Delete a single filter status with the given ID. tags: - filters get: operationId: filterStatusGet parameters: - description: ID of the filter status in: path name: id required: true type: string produces: - application/json responses: "200": description: Requested filter status. schema: $ref: '#/definitions/filterStatus' "400": description: bad request "401": description: unauthorized "404": description: not found "406": description: not acceptable "500": description: internal server error security: - OAuth2 Bearer: - read:filters summary: Get a single filter status with the given ID. tags: - filters /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 /livez: get: operationId: liveGet responses: "200": description: OK summary: Returns code 200 with no body if GoToSocial is "live", ie., able to respond to HTTP requests. tags: - health head: operationId: liveHead responses: "200": description: OK summary: Returns code 200 if GoToSocial is "live", ie., able to respond to HTTP requests. tags: - health /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 /readyz: get: description: If GtS is not ready, 500 Internal Error will be returned, and an error will be logged (but not returned to the caller, to avoid leaking internals). operationId: readyGet responses: "200": description: OK "500": description: Not ready. Check logs for error message. summary: Returns code 200 with no body if GoToSocial is "ready", ie., able to connect to the database backend and do a simple SELECT. tags: - health head: description: If GtS is not ready, 500 Internal Error will be returned, and an error will be logged (but not returned to the caller, to avoid leaking internals). operationId: readyHead responses: "200": description: OK summary: Returns code 200 with no body if GoToSocial is "ready", ie., able to connect to the database backend and do a simple SELECT. tags: - health /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 parameters: - description: Account name of the user in: path name: username required: true type: string 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:filters: grant read access to filters read:follows: grant read access to follows read:lists: grant read access to lists read:media: grant read access to media read:mutes: grant read access to mutes 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:filters: grants write access to filters write:follows: grants write access to follows write:lists: grants write access to lists write:media: grants write access to media write:mutes: grants write access to mutes 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"