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
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_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_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 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
moved:
$ref: '#/definitions/account'
note:
description: Bio/description of this account.
type: string
x-go-name: Note
role:
$ref: '#/definitions/accountRole'
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
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:
name:
type: string
x-go-name: Name
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.
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
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
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
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'
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_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'
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
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_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
list:
properties:
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: 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:
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_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_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 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
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'
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
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
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
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
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
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
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:
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}/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: 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{2,30}
required: true
type: string
- description: A png or gif image of the emoji. Animated pngs work too! To ensure compatibility with other fedi implementations, emoji size limit is 50kb by default.
in: formData
name: image
required: true
type: file
- description: Category in which to place the new emoji. 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{2,30}
type: string
- description: A new png or gif image to use for the emoji. Animated pngs work too! To ensure compatibility with other fedi implementations, emoji size limit is 50kb by default. Works for LOCAL emojis only.
in: formData
name: image
type: file
- description: Category in which to place the emoji. 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/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/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/conversations:
get:
description: |-
NOT IMPLEMENTED YET: Will currently always return an array of length 0.
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 *OLDER* than the given max ID. The conversation with the specified ID will not be included in the response. NOTE: the ID is of the internal conversation, use the Link header for pagination.'
in: query
name: max_id
type: string
- description: 'Return only conversations *NEWER* than the given since ID. The conversation with the specified ID will not be included in the response. NOTE: the ID is of the internal conversation, use the Link header for pagination.'
in: query
name: since_id
type: string
- description: 'Return only conversations *IMMEDIATELY NEWER* than the given min ID. The conversation with the specified ID will not be included in the response. NOTE: the ID is of the internal conversation, 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/custom_emojis:
get:
operationId: customEmojisGet
produces:
- application/json
responses:
"200":
description: Array of custom emojis.
schema:
items:
$ref: '#/definitions/emoji'
type: array
"401":
description: unauthorized
"406":
description: not acceptable
"500":
description: internal server error
security:
- OAuth2 Bearer:
- read:custom_emojis
summary: Get an array of custom emojis available on the instance.
tags:
- custom_emojis
/api/v1/favourites:
get:
description: |-
The next and previous queries can be parsed from the returned Link header.
Example:
```
; rel="next", ; rel="prev"
````
operationId: favouritesGet
parameters:
- default: 20
description: Number of statuses to return.
in: query
name: limit
type: integer
- description: Return only favourited statuses *OLDER* than the given favourite ID. The status with the corresponding fave ID will not be included in the response.
in: query
name: max_id
type: string
- description: Return only favourited statuses *NEWER* than the given favourite ID. The status with the corresponding fave ID will not be included in the response.
in: query
name: min_id
type: string
produces:
- application/json
responses:
"200":
description: ""
headers:
Link:
description: Links to the next and previous queries.
type: string
schema:
items:
$ref: '#/definitions/status'
type: array
"400":
description: bad request
"401":
description: unauthorized
"404":
description: not found
"406":
description: not acceptable
"500":
description: internal server error
security:
- OAuth2 Bearer:
- read:favourites
summary: Get an array of statuses that the requesting account has favourited.
tags:
- favourites
/api/v1/featured_tags:
get:
description: 'THIS ENDPOINT IS CURRENTLY NOT FULLY IMPLEMENTED: it will always return an empty array.'
operationId: getFeaturedTags
produces:
- application/json
responses:
"200":
description: ""
schema:
items:
type: object
type: array
"400":
description: bad request
"401":
description: unauthorized
"404":
description: not found
"406":
description: not acceptable
"500":
description: internal server error
security:
- OAuth2 Bearer:
- read:accounts
summary: Get an array of all hashtags that you currently have featured on your profile.
tags:
- featured_tags
/api/v1/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/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/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
in: formData
name: replies_policy
type: string
x-go-name: RepliesPolicy
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
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/xml
- application/x-www-form-urlencoded
description: |-
The parameters can also be given in the body of the request, as JSON, if the content-type is set to 'application/json'.
The parameters can also be given in the body of the request, as XML, if the content-type is set to 'application/xml'.
operationId: statusCreate
parameters:
- description: |-
Text content of the status.
If media_ids is provided, this becomes optional.
Attaching a poll is optional while status is provided.
in: formData
name: status
type: string
x-go-name: Status
- description: |-
Array of Attachment ids to be attached as media.
If provided, status becomes optional, and poll cannot be used.
If the status is being submitted as a form, the key is 'media_ids[]',
but if it's json or xml, the key is 'media_ids'.
in: formData
items:
type: string
name: media_ids
type: array
x-go-name: MediaIDs
- description: |-
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
- 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.
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: This status will be federated beyond the local timeline(s).
in: formData
name: federated
type: boolean
x-go-name: Federated
produces:
- application/json
responses:
"200":
description: The newly created status.
schema:
$ref: '#/definitions/status'
"400":
description: bad request
"401":
description: unauthorized
"403":
description: forbidden
"404":
description: not found
"406":
description: not acceptable
"500":
description: internal server error
security:
- OAuth2 Bearer:
- write:statuses
summary: Create a new status.
tags:
- statuses
/api/v1/statuses/{id}:
delete:
description: |-
The deleted status will be returned in the response. The `text` field will contain the original text of the status as it was submitted.
This is useful when doing a 'delete and redraft' type operation.
operationId: statusDelete
parameters:
- description: Target status ID.
in: path
name: id
required: true
type: string
produces:
- application/json
responses:
"200":
description: The status that was just deleted.
schema:
$ref: '#/definitions/status'
"400":
description: bad request
"401":
description: unauthorized
"403":
description: forbidden
"404":
description: not found
"406":
description: not acceptable
"500":
description: internal server error
security:
- OAuth2 Bearer:
- write:statuses
summary: Delete status with the given ID. The status must belong to you.
tags:
- statuses
get:
operationId: statusGet
parameters:
- description: Target status ID.
in: path
name: id
required: true
type: string
produces:
- application/json
responses:
"200":
description: The requested status.
schema:
$ref: '#/definitions/status'
"400":
description: bad request
"401":
description: unauthorized
"403":
description: forbidden
"404":
description: not found
"406":
description: not acceptable
"500":
description: internal server error
security:
- OAuth2 Bearer:
- read:statuses
summary: View status with the given ID.
tags:
- statuses
/api/v1/statuses/{id}/bookmark:
post:
operationId: statusBookmark
parameters:
- description: Target status ID.
in: path
name: id
required: true
type: string
produces:
- application/json
responses:
"200":
description: The status.
schema:
$ref: '#/definitions/status'
"400":
description: bad request
"401":
description: unauthorized
"403":
description: forbidden
"404":
description: not found
"406":
description: not acceptable
"500":
description: internal server error
security:
- OAuth2 Bearer:
- write:statuses
summary: Bookmark status with the given ID.
tags:
- statuses
/api/v1/statuses/{id}/context:
get:
description: The returned statuses will be ordered in a thread structure, so they are suitable to be displayed in the order in which they were returned.
operationId: 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/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
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"