basePath: / definitions: FileHeader: properties: Filename: type: string Header: $ref: '#/definitions/MIMEHeader' Size: format: int64 type: integer title: A FileHeader describes a file part of a multipart request. type: object x-go-package: mime/multipart MIMEHeader: additionalProperties: items: type: string type: array description: |- A MIMEHeader represents a MIME-style header mapping keys to sets of values. type: object x-go-package: net/textproto 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 Source: description: Returned as an additional entity when verifying and updated credentials, as an attribute of Account. properties: 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: $ref: '#/definitions/statusVisibility' sensitive: description: Whether new statuses should be marked sensitive by default. type: boolean x-go-name: Sensitive title: Source represents display or publishing preferences of user's own account. type: object x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/model StatusCreateRequest: properties: format: $ref: '#/definitions/statusFormat' in_reply_to_id: description: |- ID of the status being replied to, if status is a reply. in: formData type: string x-go-name: InReplyToID language: description: |- ISO 639 language code for this status. in: formData type: string x-go-name: Language media_ids: description: |- Array of Attachment ids to be attached as media. If provided, status becomes optional, and poll cannot be used. in: formData items: type: string type: array x-go-name: MediaIDs scheduled_at: description: |- ISO 8601 Datetime at which to schedule a status. Providing this paramter will cause ScheduledStatus to be returned instead of Status. Must be at least 5 minutes in the future. in: formData type: string x-go-name: ScheduledAt sensitive: description: |- Status and attached media should be marked as sensitive. in: formData type: boolean x-go-name: Sensitive spoiler_text: description: |- Text to be shown as a warning or subject before the actual content. Statuses are generally collapsed behind this field. in: formData type: string x-go-name: SpoilerText status: 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 type: string x-go-name: Status visibility: $ref: '#/definitions/statusVisibility' title: StatusCreateRequest models status creation parameters. 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_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 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. items: $ref: '#/definitions/emoji' type: array x-go-name: Emojis fields: description: Additional metadata attached to this account's profile. 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_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 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 Datetime). example: "2021-07-30T09:20:25+00:00" type: string x-go-name: LastStatusAt locked: description: Account manually approves follow requests. type: boolean x-go-name: Locked mute_expires_at: description: If this account has been muted, when will the mute expire (ISO 8601 Datetime). 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 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 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 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 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 advancedStatusCreateForm: description: |- AdvancedStatusCreateForm wraps the mastodon-compatible status create form along with the GTS advanced visibility settings. properties: boostable: description: This status can be boosted/reblogged. type: boolean x-go-name: Boostable federated: description: This status will be federated beyond the local timeline(s). type: boolean x-go-name: Federated format: $ref: '#/definitions/statusFormat' in_reply_to_id: description: |- ID of the status being replied to, if status is a reply. in: formData type: string x-go-name: InReplyToID language: description: |- ISO 639 language code for this status. in: formData type: string x-go-name: Language likeable: description: This status can be liked/faved. type: boolean x-go-name: Likeable media_ids: description: |- Array of Attachment ids to be attached as media. If provided, status becomes optional, and poll cannot be used. in: formData items: type: string type: array x-go-name: MediaIDs replyable: description: This status can be replied to. type: boolean x-go-name: Replyable scheduled_at: description: |- ISO 8601 Datetime at which to schedule a status. Providing this paramter will cause ScheduledStatus to be returned instead of Status. Must be at least 5 minutes in the future. in: formData type: string x-go-name: ScheduledAt sensitive: description: |- Status and attached media should be marked as sensitive. in: formData type: boolean x-go-name: Sensitive spoiler_text: description: |- Text to be shown as a warning or subject before the actual content. Statuses are generally collapsed behind this field. in: formData type: string x-go-name: SpoilerText status: 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 type: string x-go-name: Status visibility: $ref: '#/definitions/statusVisibility' type: object x-go-name: AdvancedStatusCreateForm x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/model advancedVisibilityFlagsForm: description: |- AdvancedVisibilityFlagsForm allows a few more advanced flags to be set on new statuses, in addition to the standard mastodon-compatible ones. properties: boostable: description: This status can be boosted/reblogged. type: boolean x-go-name: Boostable federated: description: This status will be federated beyond the local timeline(s). type: boolean x-go-name: Federated likeable: description: This status can be liked/faved. type: boolean x-go-name: Likeable replyable: description: This status can be replied to. type: boolean x-go-name: Replyable type: object x-go-name: AdvancedVisibilityFlagsForm x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/model announcement: properties: all_day: description: Announcement doesn't have begin time and end time, but begin day and end day. type: boolean x-go-name: AllDay content: description: |- The body of the announcement. Should be HTML formatted. example:

This is an announcement. No malarky.

type: string x-go-name: Content emoji: description: Emojis used in this announcement. items: $ref: '#/definitions/emoji' type: array x-go-name: Emojis ends_at: description: |- When the announcement should stop being displayed (ISO 8601 Datetime). If the announcement has no end time, this will be omitted or empty. example: "2021-07-30T09:20:25+00:00" type: string x-go-name: EndsAt id: description: The ID of the announcement. example: 01FC30T7X4TNCZK0TH90QYF3M4 type: string x-go-name: ID mentions: description: Mentions this announcement contains. items: $ref: '#/definitions/Mention' type: array x-go-name: Mentions published: description: |- Announcement is 'published', ie., visible to users. Announcements that are not published should be shown only to admins. type: boolean x-go-name: Published published_at: description: When the announcement was first published (ISO 8601 Datetime). example: "2021-07-30T09:20:25+00:00" type: string x-go-name: PublishedAt reactions: description: Reactions to this announcement. items: $ref: '#/definitions/announcementReaction' type: array x-go-name: Reactions read: description: Requesting account has seen this announcement. type: boolean x-go-name: Read starts_at: description: |- When the announcement should begin to be displayed (ISO 8601 Datetime). If the announcement has no start time, this will be omitted or empty. example: "2021-07-30T09:20:25+00:00" type: string x-go-name: StartsAt statuses: description: Statuses contained in this announcement. items: $ref: '#/definitions/status' type: array x-go-name: Statuses tags: description: Tags used in this announcement. items: $ref: '#/definitions/tag' type: array x-go-name: Tags updated_at: description: When the announcement was last updated (ISO 8601 Datetime). example: "2021-07-30T09:20:25+00:00" type: string x-go-name: UpdatedAt title: Announcement models an admin announcement for the instance. type: object x-go-name: Announcement x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/model announcementReaction: properties: count: description: The total number of users who have added this reaction. example: 5 format: int64 type: integer x-go-name: Count me: description: This reaction belongs to the account viewing it. type: boolean x-go-name: Me name: description: The emoji used for the reaction. Either a unicode emoji, or a custom emoji's shortcode. example: blobcat_uwu type: string x-go-name: Name static_url: description: |- Web link to a non-animated image of the custom emoji. Empty for unicode emojis. example: https://example.org/custom_emojis/statuc/blobcat_uwu.png type: string x-go-name: StaticURL url: description: |- Web link to the image of the custom emoji. Empty for unicode emojis. example: https://example.org/custom_emojis/original/blobcat_uwu.png type: string x-go-name: URL title: AnnouncementReaction models a user reaction to an announcement. type: object x-go-name: AnnouncementReaction 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. Not currently used. 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 domainBlock: description: DomainBlock represents a block on one domain properties: created_at: description: Time at which this block 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 block. example: 01FBW2758ZB6PBR200YPDDJK4C type: string x-go-name: CreatedBy domain: description: The hostname of the blocked domain. example: example.org type: string x-go-name: Domain id: description: The ID of the domain block. example: 01FBW21XJA09XYX51KV5JVBW0F readOnly: true type: string x-go-name: ID obfuscate: description: |- Obfuscate the domain name when serving this domain block publicly. A useful anti-harassment tool. example: false type: boolean x-go-name: Obfuscate private_comment: description: Private comment for this block, visible to our instance admins only. example: they are poopoo type: string x-go-name: PrivateComment public_comment: description: Public comment for this block, visible if domain blocks are served publicly. example: they smell type: string x-go-name: PublicComment subscription_id: description: The ID of the subscription that created/caused this domain block. example: 01FBW25TF5J67JW3HFHZCSD23K type: string x-go-name: SubscriptionID type: object x-go-name: DomainBlock x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/model domainBlockCreateRequest: properties: domain: description: hostname/domain to block type: string x-go-name: Domain domains: $ref: '#/definitions/FileHeader' obfuscate: description: whether the domain should be obfuscated when being displayed publicly type: boolean x-go-name: Obfuscate private_comment: description: private comment for other admins on why the domain was blocked type: string x-go-name: PrivateComment public_comment: description: public comment on the reason for the domain block type: string x-go-name: PublicComment title: DomainBlockCreateRequest is the form submitted as a POST to /api/v1/admin/domain_blocks to create a new block. type: object x-go-name: DomainBlockCreateRequest 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 emojiCreateRequest: properties: Image: $ref: '#/definitions/FileHeader' Shortcode: description: Desired shortcode for the emoji, without surrounding colons. This must be unique for the domain. example: blobcat_uwu type: string title: EmojiCreateRequest represents a request to create a custom emoji made through the admin API. type: object x-go-name: EmojiCreateRequest 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 instance: properties: approval_required: description: New account registrations require admin approval. type: boolean x-go-name: ApprovalRequired contact_account: $ref: '#/definitions/account' 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 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 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 stats: additionalProperties: format: int64 type: integer description: 'Statistics about the instance: number of posts, accounts, etc.' type: object x-go-name: Stats thumbnail: description: URL of the instance avatar/banner image. example: https://example.org/files/instance/thumbnail.jpeg type: string x-go-name: Thumbnail 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://example.org type: string x-go-name: URI urls: $ref: '#/definitions/instanceURLs' 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: Instance models information about this or another instance. type: object x-go-name: Instance x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/model instanceURLs: properties: streaming_api: description: Websockets address for status and notification streaming. example: wss://example.org type: string x-go-name: StreamingAPI title: InstanceURLs models instance-relevant URLs for client application consumption. type: object x-go-name: InstanceURLs 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: int64 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: aspect: description: |- Aspect ratio of the media. Equal to width / height. example: 1.777777778 format: float type: number x-go-name: Aspect audio_bitrate: type: string x-go-name: AudioBitrate audio_channels: type: string x-go-name: AudioChannels audio_encode: type: string x-go-name: AudioEncode 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 focus: $ref: '#/definitions/mediaFocus' fps: description: |- Framerate of the media. Only set for video and gifs. example: 30 format: uint16 type: integer x-go-name: FPS height: description: |- Height of the media in pixels. Not set for audio. example: 1080 format: int64 type: integer x-go-name: Height length: type: string x-go-name: Length original: $ref: '#/definitions/mediaDimensions' size: description: |- Size of the media, in the format `[width]x[height]`. Not set for audio. example: 1920x1080 type: string x-go-name: Size small: $ref: '#/definitions/mediaDimensions' width: description: |- Width of the media in pixels. Not set for audio. example: 1920 format: int64 type: integer x-go-name: Width title: MediaMeta models media metadata. type: object x-go-name: MediaMeta 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), or null if the poll does not end 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/pollOptions' 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. items: format: int64 type: integer type: array x-go-name: OwnVotes voted: description: When called with a user token, has the authorized user voted? type: boolean x-go-name: Voted voters_count: description: How many unique accounts have voted on a multiple-choice poll. Null if multiple is false. 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 pollOptions: 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. Number, or null if results are not published yet. format: int64 type: integer x-go-name: VotesCount title: PollOptions represents the current vote counts for different poll options. type: object x-go-name: PollOptions x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/model searchResult: properties: accounts: items: $ref: '#/definitions/account' type: array x-go-name: Accounts hashtags: items: $ref: '#/definitions/tag' 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 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 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 language: description: Primary language of this status (ISO 639 Part 1 two-letter language code). example: en type: string x-go-name: Language 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: $ref: '#/definitions/statusVisibility' title: Status models a status or post. type: object x-go-name: Status x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/model statusContext: 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 title: Context models the tree around a given status. type: object x-go-name: Context x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/model statusFormat: description: Can be either plain or markdown. Empty will default to plain. title: StatusFormat is the format in which to parse the submitted status. type: string x-go-name: StatusFormat 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 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 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 language: description: Primary language of this status (ISO 639 Part 1 two-letter language code). example: en type: string x-go-name: Language 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: $ref: '#/definitions/statusVisibility' title: StatusReblogged represents a reblogged status. type: object x-go-name: StatusReblogged x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/model statusVisibility: title: Visibility models the visibility of a status. type: string x-go-name: Visibility x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/model swaggerStatusRepliesCollection: properties: '@context': description: ActivityStreams context. example: https://www.w3.org/ns/activitystreams type: string x-go-name: Context first: $ref: '#/definitions/swaggerStatusRepliesCollectionPage' id: description: ActivityStreams ID. example: https://example.org/users/some_user/statuses/106717595988259568/replies type: string x-go-name: ID type: description: ActivityStreams type. example: Collection type: string x-go-name: Type title: SwaggerStatusRepliesCollection represents a response to GET /users/{username}/statuses/{status}/replies. type: object x-go-name: SwaggerStatusRepliesCollection x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/s2s/user swaggerStatusRepliesCollectionPage: 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: SwaggerStatusRepliesCollectionPage represents one page of a collection. type: object x-go-name: SwaggerStatusRepliesCollectionPage x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/s2s/user tag: properties: 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 updateField: description: By default, max 4 fields and 255 characters per property/value. properties: name: description: Name of the field type: string x-go-name: Name value: description: Value of the field type: string x-go-name: Value title: UpdateField is to be used specifically in an UpdateCredentialsRequest. type: object x-go-name: UpdateField x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/model updateSource: properties: language: description: Default language to use for authored statuses. (ISO 6391) type: string x-go-name: Language privacy: description: Default post privacy for authored statuses. type: string x-go-name: Privacy sensitive: description: Mark authored statuses as sensitive by default. type: boolean x-go-name: Sensitive title: UpdateSource is to be used specifically in an UpdateCredentialsRequest. type: object x-go-name: UpdateSource x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/model host: example.org info: contact: email: admin@gotosocial.org name: GoToSocial Authors description: GoToSocial Swagger documentation. license: name: AGPL3 url: https://www.gnu.org/licenses/agpl-3.0.en.html title: GoToSocial version: 0.0.1 paths: /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 "500": description: internal 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: "" schema: $ref: '#/definitions/account' "400": description: bad request "401": description: unauthorized "404": description: not found 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 this account. schema: $ref: '#/definitions/accountRelationship' "400": description: bad request "401": description: unauthorized "404": description: not found security: - OAuth2 Bearer: - write:blocks summary: Block account with id. tags: - accounts /api/v1/accounts/{id}/follow: post: consumes: - application/json - application/xml - application/x-www-form-urlencoded description: |- The parameters can also be given in the body of the request, as JSON, if the content-type is set to 'application/json'. The parameters can also be given in the body of the request, as XML, if the content-type is set to 'application/xml'. 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 x-go-name: Reblogs - default: false description: Notify when this account posts. in: formData name: notify type: boolean x-go-name: Notify 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 security: - OAuth2 Bearer: - write:follows summary: Follow account with id. tags: - accounts /api/v1/accounts/{id}/followers: get: operationId: accountFollowers parameters: - description: Account ID. in: path name: id required: true type: string produces: - application/json responses: "200": description: Array of accounts that follow this account. schema: items: $ref: '#/definitions/account' type: array "400": description: bad request "401": description: unauthorized "404": description: not found security: - OAuth2 Bearer: - read:accounts summary: See followers of account with given id. tags: - accounts /api/v1/accounts/{id}/following: get: operationId: accountFollowing parameters: - description: Account ID. in: path name: id required: true type: string produces: - application/json responses: "200": description: Array of accounts that are followed by this account. schema: items: $ref: '#/definitions/account' type: array "400": description: bad request "401": description: unauthorized "404": description: not found security: - OAuth2 Bearer: - read:accounts summary: See accounts followed by given account id. tags: - accounts /api/v1/accounts/{id}/statuses: get: description: The statuses will be returned in descending chronological order (newest first), with sequential IDs (bigger = newer). operationId: accountStatuses parameters: - description: Account ID. in: path name: id required: true type: string - default: 30 description: Number of statuses to return. in: query name: limit type: integer - default: false description: Exclude statuses that are a reply to another status. in: query name: exclude_replies type: boolean - 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 - default: false description: Show only pinned statuses. In other words,e xclude statuses that are not pinned to the given account ID. in: query name: pinned_only type: boolean - default: false description: Show only statuses with media attachments. in: query name: media_only type: boolean produces: - application/json responses: "200": description: Array of statuses. schema: items: $ref: '#/definitions/status' type: array "400": description: bad request "401": description: unauthorized "404": description: not found 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 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 security: - OAuth2 Bearer: - write:follows summary: Unfollow account with id. tags: - accounts /api/v1/accounts/relationships: get: operationId: accountRelationships parameters: - description: Account IDs. in: query items: type: string name: id required: true type: array produces: - application/json responses: "200": description: Array of account relationships. schema: items: $ref: '#/definitions/accountRelationship' type: array "400": description: bad request "401": description: unauthorized "404": description: not found security: - OAuth2 Bearer: - read:accounts summary: See your account's relationships with the given account IDs. tags: - accounts /api/v1/accounts/update_credentials: patch: consumes: - multipart/form-data operationId: accountUpdate parameters: - description: Account should be made discoverable and shown in the profile directory (if enabled). in: formData name: discoverable type: boolean - description: Account is flagged as a bot. in: formData name: bot type: boolean - allowEmptyValue: true description: The display name to use for the account. in: formData name: display_name type: string - allowEmptyValue: true description: Bio/description of this account. in: formData name: note type: string - description: Avatar of the user. in: formData name: avatar type: file - description: Header of the user. in: formData name: header type: file - description: Require manual approval of follow requests. in: formData name: locked type: boolean - description: Default post privacy for authored statuses. in: formData name: source[privacy] type: string - description: Mark authored statuses as sensitive by default. in: formData name: source[sensitive] type: boolean - description: Default language to use for authored statuses (ISO 6391). in: formData name: source[language] type: string produces: - application/json responses: "200": description: The newly updated account. schema: $ref: '#/definitions/account' "400": description: bad request "401": description: unauthorized 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 security: - OAuth2 Bearer: - read:accounts summary: Verify a token by returning account details pertaining to it. tags: - accounts /api/v1/admin/custom_emojis: post: consumes: - multipart/form-data operationId: emojiCreate parameters: - description: |- The code to use for the emoji, which will be used by instance denizens to select it. This must be unique on the instance. in: formData name: shortcode pattern: \w{2,30} required: true type: string - description: A png or gif image of the emoji. Animated pngs work too! in: formData name: image required: true type: file produces: - application/json responses: "200": description: The newly-created emoji. schema: $ref: '#/definitions/emoji' "400": description: bad request "403": description: forbidden security: - OAuth2 Bearer: - admin summary: Upload and create a new instance emoji. 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 need them to see the database IDs of your blocks, or private comments etc. in: query name: export type: boolean produces: - application/json responses: "200": description: All domain blocks currently in place. schema: items: $ref: '#/definitions/domainBlock' type: array "400": description: bad request "403": description: forbidden "404": description: not found security: - OAuth2 Bearer: - admin summary: View all domain blocks currently in place. tags: - admin post: consumes: - multipart/form-data description: |- Note that 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: - 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. 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`. Note that if a list has been imported, then an `array` of newly created domain blocks will be returned instead. schema: $ref: '#/definitions/domainBlock' "400": description: bad request "403": description: forbidden security: - OAuth2 Bearer: - admin summary: Create one or more domain blocks, from a string or a file. tags: - admin /api/v1/admin/domain_blocks/{id}: delete: operationId: domainBlockDelete parameters: - description: The id of the domain block. in: path name: id required: true type: string produces: - application/json responses: "200": description: The domain block that was just deleted. schema: $ref: '#/definitions/domainBlock' "400": description: bad request "403": description: forbidden "404": description: not found security: - OAuth2 Bearer: - admin summary: Delete domain block with the given ID. tags: - admin get: operationId: domainBlockGet parameters: - description: The id of the domain block. in: path name: id required: true type: string produces: - application/json responses: "200": description: The requested domain block. schema: $ref: '#/definitions/domainBlock' "400": description: bad request "403": description: forbidden "404": description: not found security: - OAuth2 Bearer: - admin summary: View domain block with the given ID. tags: - admin /api/v1/apps: post: consumes: - application/json - application/xml - application/x-www-form-urlencoded description: |- The registered application can be used to obtain an application token. This can then be used to register a new account, or (through user auth) obtain an access token. The parameters can also be given in the body of the request, as JSON, if the content-type is set to 'application/json'. The parameters can also be given in the body of the request, as XML, if the content-type is set to 'application/xml'. operationId: appCreate parameters: - description: The name of the application. in: formData name: client_name required: true type: string x-go-name: ClientName - description: |- Where the user should be redirected after authorization. To display the authorization code to the user instead of redirecting to a web page, use `urn:ietf:wg:oauth:2.0:oob` in this parameter. in: formData name: redirect_uris required: true type: string x-go-name: RedirectURIs - description: |- Space separated list of scopes. If no scopes are provided, defaults to `read`. in: formData name: scopes type: string x-go-name: Scopes - description: A URL to the web page of the app (optional). in: formData name: website type: string x-go-name: Website produces: - application/json responses: "200": description: The newly-created application. schema: $ref: '#/definitions/application' "400": description: bad request "401": description: unauthorized "422": description: unprocessable "500": description: internal error summary: Register a new application on this instance. tags: - apps /api/v1/blocks: get: description: |- The next and previous queries can be parsed from the returned Link header. Example: ``` ; rel="next", ; rel="prev" ```` operationId: blocksGet parameters: - default: 20 description: Number of blocks to return. in: query name: limit type: integer - description: |- Return only blocks *OLDER* than the given max block ID. The block with the specified ID will not be included in the response. in: query name: max_id type: string - description: |- Return only blocks *NEWER* than the given since block ID. The block with the specified ID will not be included in the response. in: query name: since_id type: string produces: - application/json responses: "200": description: "" headers: Link: description: Links to the next and previous queries. type: string schema: items: $ref: '#/definitions/account' type: array "400": description: bad request "401": description: unauthorized "404": description: not found security: - OAuth2 Bearer: - read:blocks summary: Get an array of accounts that requesting account has blocked. tags: - blocks /api/v1/instance: get: description: |- This is mostly provided for Mastodon application compatibility, since many apps that work with Mastodon use `/api/v1/instance` to inform their connection parameters. However, it can also be used by other instances for gathering instance information and representing instances in some UI or other. operationId: instanceGet produces: - application/json responses: "200": description: Instance information. schema: $ref: '#/definitions/instance' "500": description: internal error summary: View instance information. tags: - instance patch: consumes: - multipart/form-data description: This requires admin permissions on the instance. operationId: instanceUpdate parameters: - allowEmptyValue: true description: Title to use for the instance. in: formData maximum: 40 name: title type: string - allowEmptyValue: true description: |- Username of the contact account. This must be the username of an instance admin. in: formData name: contact_username type: string - allowEmptyValue: true description: Email address to use as the instance contact. in: formData name: contact_email type: string - allowEmptyValue: true description: Short description of the instance. in: formData maximum: 500 name: short_description type: string - allowEmptyValue: true description: Longer description of the instance. in: formData maximum: 5000 name: description type: string - allowEmptyValue: true description: Terms and conditions of the instance. in: formData maximum: 5000 name: terms type: string - description: Avatar of the instance. in: formData name: avatar type: file - description: Header of the instance. in: formData name: header type: file produces: - application/json responses: "200": description: The newly updated instance. schema: $ref: '#/definitions/instance' "400": description: bad request "401": description: unauthorized security: - OAuth2 Bearer: - admin summary: Update your instance information and/or upload a new avatar/header for the instance. tags: - instance /api/v1/media: post: consumes: - multipart/form-data operationId: mediaCreate parameters: - 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 - 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 "403": description: forbidden "422": description: unprocessable security: - OAuth2 Bearer: - write:media summary: Upload a new media attachment. tags: - media /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 "403": description: forbidden "422": description: unprocessable 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 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 "403": description: forbidden "422": description: unprocessable security: - OAuth2 Bearer: - write:media summary: Update a media attachment. tags: - media /api/v1/search: get: description: If statuses are in the result, they will be returned in descending chronological order (newest first), with sequential IDs (bigger = newer). operationId: searchGet parameters: - description: If type is `statuses`, then statuses returned will be authored only by this account. in: query name: account_id type: string x-go-name: AccountID - description: |- Return results *older* than this id. The entry with this ID will not be included in the search results. in: query name: max_id type: string x-go-name: MaxID - description: |- Return results *newer* than this id. The entry with this ID will not be included in the search results. in: query name: min_id type: string x-go-name: MinID - description: |- Type of the search query to perform. Must be one of: `accounts`, `hashtags`, `statuses`. in: query name: type required: true type: string x-go-name: Type - default: false description: Filter out tags that haven't been reviewed and approved by an instance admin. in: query name: exclude_unreviewed type: boolean x-go-name: ExcludeUnreviewed - description: |- String to use as a search query. For accounts, this should be in the format `@someaccount@some.instance.com`, or the format `https://some.instance.com/@someaccount` For a status, this can be in the format: `https://some.instance.com/@someaccount/SOME_ID_OF_A_STATUS` in: query name: q required: true type: string x-go-name: Query - default: false description: Attempt to resolve the query by performing a remote webfinger lookup, if the query includes a remote host. in: query name: resolve type: boolean x-go-name: Resolve - default: 20 description: Maximum number of results to load, per type. format: int64 in: query maximum: 40 minimum: 1 name: limit type: integer x-go-name: Limit - default: 0 description: Offset for paginating search results. format: int64 in: query name: offset type: integer x-go-name: Offset - default: false description: Only include accounts that the searching account is following. in: query name: following type: boolean x-go-name: Following responses: "200": description: Results of the search. schema: items: $ref: '#/definitions/searchResult' type: array "400": description: bad request "401": description: unauthorized security: - OAuth2 Bearer: - read:search summary: Search for statuses, accounts, or hashtags, on this instance or elsewhere. tags: - search /api/v1/statuses: post: consumes: - application/json - application/xml - application/x-www-form-urlencoded description: |- The parameters can also be given in the body of the request, as JSON, if the content-type is set to 'application/json'. The parameters can also be given in the body of the request, as XML, if the content-type is set to 'application/xml'. operationId: statusCreate parameters: - description: |- Text content of the status. If media_ids is provided, this becomes optional. Attaching a poll is optional while status is provided. in: formData name: status type: string x-go-name: Status - description: |- Array of Attachment ids to be attached as media. If provided, status becomes optional, and poll cannot be used. in: formData items: type: string name: media_ids type: array x-go-name: MediaIDs - description: ID of the status being replied to, if status is a reply. in: formData name: in_reply_to_id type: string x-go-name: InReplyToID - description: Status and attached media should be marked as sensitive. in: formData name: sensitive type: boolean x-go-name: Sensitive - description: |- Text to be shown as a warning or subject before the actual content. Statuses are generally collapsed behind this field. in: formData name: spoiler_text type: string x-go-name: SpoilerText - description: Visibility of the posted status. in: formData name: visibility type: string x-go-name: Visibility - description: |- ISO 8601 Datetime at which to schedule a status. Providing this paramter will cause ScheduledStatus to be returned instead of Status. Must be at least 5 minutes in the future. in: formData name: scheduled_at type: string x-go-name: ScheduledAt - description: ISO 639 language code for this status. in: formData name: language type: string x-go-name: Language - description: Format to use when parsing this status. in: formData name: format type: string x-go-name: Format produces: - application/json responses: "200": description: The newly created status. schema: $ref: '#/definitions/status' "400": description: bad request "401": description: unauthorized "404": description: not found "500": description: internal error security: - OAuth2 Bearer: - write:statuses summary: Create a new status. tags: - statuses /api/v1/statuses/{id}: delete: description: |- The deleted status will be returned in the response. The `text` field will contain the original text of the status as it was submitted. This is useful when doing a 'delete and redraft' type operation. operationId: statusDelete parameters: - description: Target status ID. in: path name: id required: true type: string produces: - application/json responses: "200": description: The newly deleted status. schema: $ref: '#/definitions/status' "400": description: bad request "401": description: unauthorized "403": description: forbidden "404": description: not found 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 created status. schema: $ref: '#/definitions/status' "400": description: bad request "401": description: unauthorized "404": description: not found "500": description: internal error security: - OAuth2 Bearer: - read:statuses summary: View status with the given ID. tags: - statuses /api/v1/statuses/{id}/context: get: description: The returned statuses will be ordered in a thread structure, so they are suitable to be displayed in the order in which they were returned. operationId: statusContext parameters: - description: Target status ID. in: path name: id required: true type: string produces: - application/json responses: "200": description: Status context object. schema: $ref: '#/definitions/statusContext' "400": description: bad request "401": description: unauthorized "403": description: forbidden "404": description: not found 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 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 security: - OAuth2 Bearer: - read:accounts summary: View accounts that have faved/starred/liked the target status. 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 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}/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 security: - OAuth2 Bearer: - write:statuses summary: Unstar/unlike/unfavourite the given status. 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 security: - OAuth2 Bearer: - write:statuses summary: Unreblog/unboost status with the given ID. tags: - statuses /api/v1/streaming: get: description: |- The scheme used should *always* be `wss`. The streaming basepath can be viewed at `/api/v1/instance`. On a successful connection, a code `101` will be returned, which indicates that the connection is being upgraded to a secure websocket connection. As long as the connection is open, various message types will be streamed into it. GoToSocial will ping the connection every 30 seconds to check whether the client is still receiving. If the ping fails, or something else goes wrong during transmission, then the connection will be dropped, and the client will be expected to start it again. operationId: streamGet parameters: - description: Access token for the requesting account. in: query name: access_token required: true type: string - description: |- Type of stream to request. Options are: `user`: receive updates for the account's home timeline. `public`: receive updates for the public timeline. `public:local`: receive updates for the local timeline. `hashtag`: receive updates for a given hashtag. `hashtag:local`: receive local updates for a given hashtag. `list`: receive updates for a certain list of accounts. `direct`: receive updates for direct messages. in: query name: stream required: true type: string produces: - application/json responses: "101": description: "" schema: properties: event: description: |- The type of event being received. `update`: a new status has been received. `notification`: a new notification has been received. `delete`: a status has been deleted. `filters_changed`: not implemented. enum: - update - notification - delete - filters_changed type: string payload: description: |- The payload of the streamed message. Different depending on the `event` type. If present, it should be parsed as a string. If `event` = `update`, then the payload will be a JSON string of a status. If `event` = `notification`, then the payload will be a JSON string of a notification. If `event` = `delete`, then the payload will be a status ID. example: '{"id":"01FC3TZ5CFG6H65GCKCJRKA669","created_at":"2021-08-02T16:25:52Z","sensitive":false,"spoiler_text":"","visibility":"public","language":"en","uri":"https://gts.superseriousbusiness.org/users/dumpsterqueer/statuses/01FC3TZ5CFG6H65GCKCJRKA669","url":"https://gts.superseriousbusiness.org/@dumpsterqueer/statuses/01FC3TZ5CFG6H65GCKCJRKA669","replies_count":0,"reblogs_count":0,"favourites_count":0,"favourited":false,"reblogged":false,"muted":false,"bookmarked":fals…//gts.superseriousbusiness.org/fileserver/01JNN207W98SGG3CBJ76R5MVDN/header/original/019036W043D8FXPJKSKCX7G965.png","header_static":"https://gts.superseriousbusiness.org/fileserver/01JNN207W98SGG3CBJ76R5MVDN/header/small/019036W043D8FXPJKSKCX7G965.png","followers_count":33,"following_count":28,"statuses_count":126,"last_status_at":"2021-08-02T16:25:52Z","emojis":[],"fields":[]},"media_attachments":[],"mentions":[],"tags":[],"emojis":[],"card":null,"poll":null,"text":"a"}' type: string stream: items: enum: - user - public - public:local - hashtag - hashtag:local - list - direct type: string type: array type: object "400": description: bad request "401": description: unauthorized schemes: - wss security: - OAuth2 Bearer: - read:streaming summary: Initiate a websocket connection for live streaming of statuses and notifications. tags: - streaming /api/v1/timelines/home: get: description: |- The statuses will be returned in descending chronological order (newest first), with sequential IDs (bigger = newer). The returned Link header can be used to generate the previous and next queries when scrolling up or down a timeline. Example: ``` ; rel="next", ; rel="prev" ```` operationId: homeTimeline parameters: - description: |- Return only statuses *OLDER* than the given max status ID. The status with the specified ID will not be included in the response. in: query name: max_id type: string - description: |- Return only statuses *NEWER* than the given since status ID. The status with the specified ID will not be included in the response. in: query name: since_id type: string - description: |- Return only statuses *NEWER* than the given since status ID. The status with the specified ID will not be included in the response. in: query name: min_id type: string - default: 20 description: Number of statuses to return. in: query name: limit type: integer - default: false description: Show only statuses posted by local accounts. in: query name: local type: boolean produces: - application/json responses: "200": description: Array of statuses. headers: Link: description: Links to the next and previous queries. type: string schema: items: $ref: '#/definitions/status' type: array "400": description: bad request "401": description: unauthorized security: - OAuth2 Bearer: - read:statuses summary: See statuses/posts by accounts you follow. tags: - timelines /api/v1/timelines/public: get: description: |- The statuses will be returned in descending chronological order (newest first), with sequential IDs (bigger = newer). The returned Link header can be used to generate the previous and next queries when scrolling up or down a timeline. Example: ``` ; rel="next", ; rel="prev" ```` operationId: publicTimeline parameters: - description: |- Return only statuses *OLDER* than the given max status ID. The status with the specified ID will not be included in the response. in: query name: max_id type: string - description: |- Return only statuses *NEWER* than the given since status ID. The status with the specified ID will not be included in the response. in: query name: since_id type: string - description: |- Return only statuses *NEWER* than the given since status ID. The status with the specified ID will not be included in the response. in: query name: min_id type: string - default: 20 description: Number of statuses to return. in: query name: limit type: integer - default: false description: Show only statuses posted by local accounts. in: query name: local type: boolean produces: - application/json responses: "200": description: Array of statuses. headers: Link: description: Links to the next and previous queries. type: string schema: items: $ref: '#/definitions/status' type: array "400": description: bad request "401": description: unauthorized security: - OAuth2 Bearer: - read:statuses summary: See public statuses/posts that your instance is aware of. tags: - timelines /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/swaggerStatusRepliesCollection' "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:media: grant read access to media read:search: grant read access to searches read:statuses: grants read access to statuses read:streaming: grants read access to streaming api write: grants write access to everything write:accounts: grants write access to accounts write:blocks: grants write access to blocks write:follows: grants write access to follows write:media: grants write access to media write:statuses: grants write access to statuses tokenUrl: https://example.org/oauth/token type: oauth2 swagger: "2.0"