mirrors
/
gotosocial
mirror of
1
Fork 0
Code Issues Releases Activity
gotosocial/docs/api/swagger.yaml

3902 lines
122 KiB
YAML
Raw Blame History

basePath: /
definitions:
FileHeader:
properties:
Filename:
type: string
Header:
$ref: '#/definitions/MIMEHeader'
Size:
format: int64
type: integer
title: A FileHeader describes a file part of a multipart request.
type: object
x-go-package: mime/multipart
Link:
description: See https://webfinger.net/
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
MIMEHeader:
additionalProperties:
items:
type: string
type: array
description: |-
A MIMEHeader represents a MIME-style header mapping
keys to sets of values.
type: object
x-go-package: net/textproto
Mention:
properties:
acct:
description: |-
The account URI as discovered via webfinger.
Equal to username for local users, or username@domain for remote users.
example: some_user@example.org
type: string
x-go-name: Acct
id:
description: The ID of the mentioned account.
example: 01FBYJHQWQZAVWFRK9PDYTKGMB
type: string
x-go-name: ID
url:
description: The web URL of the mentioned account's profile.
example: https://example.org/@some_user
type: string
x-go-name: URL
username:
description: The username of the mentioned account.
example: some_user
type: string
x-go-name: Username
title: Mention represents a mention of another account.
type: object
x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/model
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:
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:
title: NodeInfoUsers is a stub for usage information, currently empty.
type: object
x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/model
Source:
description: Returned as an additional entity when verifying and updated credentials,
as an attribute of Account.
properties:
fields:
description: Metadata about the account.
items:
$ref: '#/definitions/field'
type: array
x-go-name: Fields
follow_requests_count:
description: The number of pending follow requests.
format: int64
type: integer
x-go-name: FollowRequestsCount
language:
description: The default posting language for new statuses.
type: string
x-go-name: Language
note:
description: Profile bio.
type: string
x-go-name: Note
privacy:
$ref: '#/definitions/statusVisibility'
sensitive:
description: Whether new statuses should be marked sensitive by default.
type: boolean
x-go-name: Sensitive
title: Source represents display or publishing preferences of user's own account.
type: object
x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/model
StatusCreateRequest:
properties:
format:
$ref: '#/definitions/statusFormat'
in_reply_to_id:
description: |-
ID of the status being replied to, if status is a reply.
in: formData
type: string
x-go-name: InReplyToID
language:
description: |-
ISO 639 language code for this status.
in: formData
type: string
x-go-name: Language
media_ids:
description: |-
Array of Attachment ids to be attached as media.
If provided, status becomes optional, and poll cannot be used.
in: formData
items:
type: string
type: array
x-go-name: MediaIDs
scheduled_at:
description: |-
ISO 8601 Datetime at which to schedule a status.
Providing this paramter will cause ScheduledStatus to be returned instead of Status.
Must be at least 5 minutes in the future.
in: formData
type: string
x-go-name: ScheduledAt
sensitive:
description: |-
Status and attached media should be marked as sensitive.
in: formData
type: boolean
x-go-name: Sensitive
spoiler_text:
description: |-
Text to be shown as a warning or subject before the actual content.
Statuses are generally collapsed behind this field.
in: formData
type: string
x-go-name: SpoilerText
status:
description: |-
Text content of the status.
If media_ids is provided, this becomes optional.
Attaching a poll is optional while status is provided.
in: formData
type: string
x-go-name: Status
visibility:
$ref: '#/definitions/statusVisibility'
title: StatusCreateRequest models status creation parameters.
type: object
x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/model
account:
description: The modelled account can be either a remote account, or one on this
instance.
properties:
acct:
description: |-
The account URI as discovered via webfinger.
Equal to username for local users, or username@domain for remote users.
example: some_user@example.org
type: string
x-go-name: Acct
avatar:
description: Web location of the account's avatar.
example: https://example.org/media/some_user/avatar/original/avatar.jpeg
type: string
x-go-name: Avatar
avatar_static:
description: |-
Web location of a static version of the account's avatar.
Only relevant when the account's main avatar is a video or a gif.
example: https://example.org/media/some_user/avatar/static/avatar.png
type: string
x-go-name: AvatarStatic
bot:
description: Account identifies as a bot.
type: boolean
x-go-name: Bot
created_at:
description: When the account was created (ISO 8601 Datetime).
example: "2021-07-30T09:20:25+00:00"
type: string
x-go-name: CreatedAt
discoverable:
description: Account has opted into discovery features.
type: boolean
x-go-name: Discoverable
display_name:
description: The account's display name.
example: big jeff (he/him)
type: string
x-go-name: DisplayName
emojis:
description: Array of custom emojis used in this account's note or display
name.
items:
$ref: '#/definitions/emoji'
type: array
x-go-name: Emojis
fields:
description: Additional metadata attached to this account's profile.
items:
$ref: '#/definitions/field'
type: array
x-go-name: Fields
followers_count:
description: Number of accounts following this account, according to our instance.
format: int64
type: integer
x-go-name: FollowersCount
following_count:
description: Number of account's followed by this account, according to our
instance.
format: int64
type: integer
x-go-name: FollowingCount
header:
description: Web location of the account's header image.
example: https://example.org/media/some_user/header/original/header.jpeg
type: string
x-go-name: Header
header_static:
description: |-
Web location of a static version of the account's header.
Only relevant when the account's main header is a video or a gif.
example: https://example.org/media/some_user/header/static/header.png
type: string
x-go-name: HeaderStatic
id:
description: The account id.
example: 01FBVD42CQ3ZEEVMW180SBX03B
type: string
x-go-name: ID
last_status_at:
description: When the account's most recent status was posted (ISO 8601 Datetime).
example: "2021-07-30T09:20:25+00:00"
type: string
x-go-name: LastStatusAt
locked:
description: Account manually approves follow requests.
type: boolean
x-go-name: Locked
mute_expires_at:
description: If this account has been muted, when will the mute expire (ISO
8601 Datetime).
example: "2021-07-30T09:20:25+00:00"
type: string
x-go-name: MuteExpiresAt
note:
description: Bio/description of this account.
type: string
x-go-name: Note
source:
$ref: '#/definitions/Source'
statuses_count:
description: Number of statuses posted by this account, according to our instance.
format: int64
type: integer
x-go-name: StatusesCount
suspended:
description: Account has been suspended by our instance.
type: boolean
x-go-name: Suspended
url:
description: Web location of the account's profile page.
example: https://example.org/@some_user
type: string
x-go-name: URL
username:
description: The username of the account, not including domain.
example: some_user
type: string
x-go-name: Username
title: Account models a fediverse account.
type: object
x-go-name: Account
x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/model
accountRelationship:
properties:
blocked_by:
description: This account is blocking you.
type: boolean
x-go-name: BlockedBy
blocking:
description: You are blocking this account.
type: boolean
x-go-name: Blocking
domain_blocking:
description: You are blocking this account's domain.
type: boolean
x-go-name: DomainBlocking
endorsed:
description: You are featuring this account on your profile.
type: boolean
x-go-name: Endorsed
followed_by:
description: This account follows you.
type: boolean
x-go-name: FollowedBy
following:
description: You are following this account.
type: boolean
x-go-name: Following
id:
description: The account id.
example: 01FBW9XGEP7G6K88VY4S9MPE1R
type: string
x-go-name: ID
muting:
description: You are muting this account.
type: boolean
x-go-name: Muting
muting_notifications:
description: You are muting notifications from this account.
type: boolean
x-go-name: MutingNotifications
note:
description: Your note on this account.
type: string
x-go-name: Note
notifying:
description: You are seeing notifications when this account posts.
type: boolean
x-go-name: Notifying
requested:
description: You have requested to follow this account, and the request is
pending.
type: boolean
x-go-name: Requested
showing_reblogs:
description: You are seeing reblogs/boosts from this account in your home
timeline.
type: boolean
x-go-name: ShowingReblogs
title: Relationship represents a relationship between accounts.
type: object
x-go-name: Relationship
x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/model
advancedStatusCreateForm:
description: |-
AdvancedStatusCreateForm wraps the mastodon-compatible status create form along with the GTS advanced
visibility settings.
properties:
boostable:
description: This status can be boosted/reblogged.
type: boolean
x-go-name: Boostable
federated:
description: This status will be federated beyond the local timeline(s).
type: boolean
x-go-name: Federated
format:
$ref: '#/definitions/statusFormat'
in_reply_to_id:
description: |-
ID of the status being replied to, if status is a reply.
in: formData
type: string
x-go-name: InReplyToID
language:
description: |-
ISO 639 language code for this status.
in: formData
type: string
x-go-name: Language
likeable:
description: This status can be liked/faved.
type: boolean
x-go-name: Likeable
media_ids:
description: |-
Array of Attachment ids to be attached as media.
If provided, status becomes optional, and poll cannot be used.
in: formData
items:
type: string
type: array
x-go-name: MediaIDs
replyable:
description: This status can be replied to.
type: boolean
x-go-name: Replyable
scheduled_at:
description: |-
ISO 8601 Datetime at which to schedule a status.
Providing this paramter will cause ScheduledStatus to be returned instead of Status.
Must be at least 5 minutes in the future.
in: formData
type: string
x-go-name: ScheduledAt
sensitive:
description: |-
Status and attached media should be marked as sensitive.
in: formData
type: boolean
x-go-name: Sensitive
spoiler_text:
description: |-
Text to be shown as a warning or subject before the actual content.
Statuses are generally collapsed behind this field.
in: formData
type: string
x-go-name: SpoilerText
status:
description: |-
Text content of the status.
If media_ids is provided, this becomes optional.
Attaching a poll is optional while status is provided.
in: formData
type: string
x-go-name: Status
visibility:
$ref: '#/definitions/statusVisibility'
type: object
x-go-name: AdvancedStatusCreateForm
x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/model
advancedVisibilityFlagsForm:
description: |-
AdvancedVisibilityFlagsForm allows a few more advanced flags to be set on new statuses, in addition
to the standard mastodon-compatible ones.
properties:
boostable:
description: This status can be boosted/reblogged.
type: boolean
x-go-name: Boostable
federated:
description: This status will be federated beyond the local timeline(s).
type: boolean
x-go-name: Federated
likeable:
description: This status can be liked/faved.
type: boolean
x-go-name: Likeable
replyable:
description: This status can be replied to.
type: boolean
x-go-name: Replyable
type: object
x-go-name: AdvancedVisibilityFlagsForm
x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/model
announcement:
properties:
all_day:
description: Announcement doesn't have begin time and end time, but begin
day and end day.
type: boolean
x-go-name: AllDay
content:
description: |-
The body of the announcement.
Should be HTML formatted.
example: <p>This is an announcement. No malarky.</p>
type: string
x-go-name: Content
emoji:
description: Emojis used in this announcement.
items:
$ref: '#/definitions/emoji'
type: array
x-go-name: Emojis
ends_at:
description: |-
When the announcement should stop being displayed (ISO 8601 Datetime).
If the announcement has no end time, this will be omitted or empty.
example: "2021-07-30T09:20:25+00:00"
type: string
x-go-name: EndsAt
id:
description: The ID of the announcement.
example: 01FC30T7X4TNCZK0TH90QYF3M4
type: string
x-go-name: ID
mentions:
description: Mentions this announcement contains.
items:
$ref: '#/definitions/Mention'
type: array
x-go-name: Mentions
published:
description: |-
Announcement is 'published', ie., visible to users.
Announcements that are not published should be shown only to admins.
type: boolean
x-go-name: Published
published_at:
description: When the announcement was first published (ISO 8601 Datetime).
example: "2021-07-30T09:20:25+00:00"
type: string
x-go-name: PublishedAt
reactions:
description: Reactions to this announcement.
items:
$ref: '#/definitions/announcementReaction'
type: array
x-go-name: Reactions
read:
description: Requesting account has seen this announcement.
type: boolean
x-go-name: Read
starts_at:
description: |-
When the announcement should begin to be displayed (ISO 8601 Datetime).
If the announcement has no start time, this will be omitted or empty.
example: "2021-07-30T09:20:25+00:00"
type: string
x-go-name: StartsAt
statuses:
description: Statuses contained in this announcement.
items:
$ref: '#/definitions/status'
type: array
x-go-name: Statuses
tags:
description: Tags used in this announcement.
items:
$ref: '#/definitions/tag'
type: array
x-go-name: Tags
updated_at:
description: When the announcement was last updated (ISO 8601 Datetime).
example: "2021-07-30T09:20:25+00:00"
type: string
x-go-name: UpdatedAt
title: Announcement models an admin announcement for the instance.
type: object
x-go-name: Announcement
x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/model
announcementReaction:
properties:
count:
description: The total number of users who have added this reaction.
example: 5
format: int64
type: integer
x-go-name: Count
me:
description: This reaction belongs to the account viewing it.
type: boolean
x-go-name: Me
name:
description: The emoji used for the reaction. Either a unicode emoji, or a
custom emoji's shortcode.
example: blobcat_uwu
type: string
x-go-name: Name
static_url:
description: |-
Web link to a non-animated image of the custom emoji.
Empty for unicode emojis.
example: https://example.org/custom_emojis/statuc/blobcat_uwu.png
type: string
x-go-name: StaticURL
url:
description: |-
Web link to the image of the custom emoji.
Empty for unicode emojis.
example: https://example.org/custom_emojis/original/blobcat_uwu.png
type: string
x-go-name: URL
title: AnnouncementReaction models a user reaction to an announcement.
type: object
x-go-name: AnnouncementReaction
x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/model
application:
properties:
client_id:
description: Client ID associated with this application.
type: string
x-go-name: ClientID
client_secret:
description: Client secret associated with this application.
type: string
x-go-name: ClientSecret
id:
description: The ID of the application.
example: 01FBVD42CQ3ZEEVMW180SBX03B
type: string
x-go-name: ID
name:
description: The name of the application.
example: Tusky
type: string
x-go-name: Name
redirect_uri:
description: Post-authorization redirect URI for the application (OAuth2).
example: https://example.org/callback?some=query
type: string
x-go-name: RedirectURI
vapid_key:
description: Push API key for this application.
type: string
x-go-name: VapidKey
website:
description: The website associated with the application (url)
example: https://tusky.app
type: string
x-go-name: Website
title: Application models an api application.
type: object
x-go-name: Application
x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/model
attachment:
properties:
blurhash:
description: |-
A hash computed by the BlurHash algorithm, for generating colorful preview thumbnails when media has not been downloaded yet.
See https://github.com/woltapp/blurhash
type: string
x-go-name: Blurhash
description:
description: Alt text that describes what is in the media attachment.
example: This is a picture of a kitten.
type: string
x-go-name: Description
id:
description: The ID of the attachment.
example: 01FC31DZT1AYWDZ8XTCRWRBYRK
type: string
x-go-name: ID
meta:
$ref: '#/definitions/mediaMeta'
preview_remote_url:
description: |-
The location of a scaled-down preview of the attachment on the remote server.
Only defined for instances other than our own.
example: https://some-other-server.org/attachments/small/ahhhhh.jpeg
type: string
x-go-name: PreviewRemoteURL
preview_url:
description: The location of a scaled-down preview of the attachment.
example: https://example.org/fileserver/some_id/attachments/some_id/small/attachment.jpeg
type: string
x-go-name: PreviewURL
remote_url:
description: |-
The location of the full-size original attachment on the remote server.
Only defined for instances other than our own.
example: https://some-other-server.org/attachments/original/ahhhhh.jpeg
type: string
x-go-name: RemoteURL
text_url:
description: |-
A shorter URL for the attachment.
Not currently used.
type: string
x-go-name: TextURL
type:
description: The type of the attachment.
example: image
type: string
x-go-name: Type
url:
description: The location of the original full-size attachment.
example: https://example.org/fileserver/some_id/attachments/some_id/original/attachment.jpeg
type: string
x-go-name: URL
title: Attachment models a media attachment.
type: object
x-go-name: Attachment
x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/model
card:
properties:
author_name:
description: The author of the original resource.
example: weewee@buzzfeed.com
type: string
x-go-name: AuthorName
author_url:
description: A link to the author of the original resource.
example: https://buzzfeed.com/authors/weewee
type: string
x-go-name: AuthorURL
blurhash:
description: A hash computed by the BlurHash algorithm, for generating colorful
preview thumbnails when media has not been downloaded yet.
type: string
x-go-name: Blurhash
description:
description: Description of preview.
example: Is water wet? We're not sure. In this article, we ask an expert...
type: string
x-go-name: Description
embed_url:
description: Used for photo embeds, instead of custom html.
type: string
x-go-name: EmbedURL
height:
description: Height of preview, in pixels.
format: int64
type: integer
x-go-name: Height
html:
description: HTML to be used for generating the preview card.
type: string
x-go-name: HTML
image:
description: Preview thumbnail.
example: https://example.org/fileserver/preview/thumb.jpg
type: string
x-go-name: Image
provider_name:
description: The provider of the original resource.
example: Buzzfeed
type: string
x-go-name: ProviderName
provider_url:
description: A link to the provider of the original resource.
example: https://buzzfeed.com
type: string
x-go-name: ProviderURL
title:
description: Title of linked resource.
example: Buzzfeed - Is Water Wet?
type: string
x-go-name: Title
type:
description: The type of the preview card.
example: link
type: string
x-go-name: Type
url:
description: Location of linked resource.
example: https://buzzfeed.com/some/fuckin/buzzfeed/article
type: string
x-go-name: URL
width:
description: Width of preview, in pixels.
format: int64
type: integer
x-go-name: Width
title: Card represents a rich preview card that is generated using OpenGraph tags
from a URL.
type: object
x-go-name: Card
x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/model
domainBlock:
description: DomainBlock represents a block on one domain
properties:
created_at:
description: Time at which this block was created (ISO 8601 Datetime).
example: "2021-07-30T09:20:25+00:00"
type: string
x-go-name: CreatedAt
created_by:
description: ID of the account that created this domain block.
example: 01FBW2758ZB6PBR200YPDDJK4C
type: string
x-go-name: CreatedBy
domain:
description: The hostname of the blocked domain.
example: example.org
type: string
x-go-name: Domain
id:
description: The ID of the domain block.
example: 01FBW21XJA09XYX51KV5JVBW0F
readOnly: true
type: string
x-go-name: ID
obfuscate:
description: |-
Obfuscate the domain name when serving this domain block publicly.
A useful anti-harassment tool.
example: false
type: boolean
x-go-name: Obfuscate
private_comment:
description: Private comment for this block, visible to our instance admins
only.
example: they are poopoo
type: string
x-go-name: PrivateComment
public_comment:
description: Public comment for this block, visible if domain blocks are served
publicly.
example: they smell
type: string
x-go-name: PublicComment
subscription_id:
description: The ID of the subscription that created/caused this domain block.
example: 01FBW25TF5J67JW3HFHZCSD23K
type: string
x-go-name: SubscriptionID
type: object
x-go-name: DomainBlock
x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/model
domainBlockCreateRequest:
properties:
domain:
description: hostname/domain to block
type: string
x-go-name: Domain
domains:
$ref: '#/definitions/FileHeader'
obfuscate:
description: whether the domain should be obfuscated when being displayed
publicly
type: boolean
x-go-name: Obfuscate
private_comment:
description: private comment for other admins on why the domain was blocked
type: string
x-go-name: PrivateComment
public_comment:
description: public comment on the reason for the domain block
type: string
x-go-name: PublicComment
title: DomainBlockCreateRequest is the form submitted as a POST to /api/v1/admin/domain_blocks
to create a new block.
type: object
x-go-name: DomainBlockCreateRequest
x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/model
emoji:
properties:
category:
description: Used for sorting custom emoji in the picker.
example: blobcats
type: string
x-go-name: Category
shortcode:
description: The name of the custom emoji.
example: blobcat_uwu
type: string
x-go-name: Shortcode
static_url:
description: A link to a static copy of the custom emoji.
example: https://example.org/fileserver/emojis/blogcat_uwu.png
type: string
x-go-name: StaticURL
url:
description: Web URL of the custom emoji.
example: https://example.org/fileserver/emojis/blogcat_uwu.gif
type: string
x-go-name: URL
visible_in_picker:
description: Emoji is visible in the emoji picker of the instance.
example: true
type: boolean
x-go-name: VisibleInPicker
title: Emoji represents a custom emoji.
type: object
x-go-name: Emoji
x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/model
emojiCreateRequest:
properties:
Image:
$ref: '#/definitions/FileHeader'
Shortcode:
description: Desired shortcode for the emoji, without surrounding colons.
This must be unique for the domain.
example: blobcat_uwu
type: string
title: EmojiCreateRequest represents a request to create a custom emoji made through
the admin API.
type: object
x-go-name: EmojiCreateRequest
x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/model
field:
properties:
name:
description: The key/name of this field.
example: pronouns
type: string
x-go-name: Name
value:
description: The value of this field.
example: they/them
type: string
x-go-name: Value
verified_at:
description: If this field has been verified, when did this occur? (ISO 8601
Datetime).
example: "2021-07-30T09:20:25+00:00"
type: string
x-go-name: VerifiedAt
title: Field represents a name/value pair to display on an account's profile.
type: object
x-go-name: Field
x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/model
instance:
properties:
approval_required:
description: New account registrations require admin approval.
type: boolean
x-go-name: ApprovalRequired
contact_account:
$ref: '#/definitions/account'
description:
description: |-
Description of the instance.
Should be HTML formatted, but might be plaintext.
This should be displayed on the 'about' page for an instance.
type: string
x-go-name: Description
email:
description: An email address that may be used for inquiries.
example: admin@example.org
type: string
x-go-name: Email
invites_enabled:
description: Invites are enabled on this instance.
type: boolean
x-go-name: InvitesEnabled
languages:
description: Primary language of the instance.
example: en
items:
type: string
type: array
x-go-name: Languages
max_toot_chars:
description: |-
Maximum allowed length of a post on this instance, in characters.
This is provided for compatibility with Tusky and other apps.
example: 5000
format: uint64
type: integer
x-go-name: MaxTootChars
registrations:
description: New account registrations are enabled on this instance.
type: boolean
x-go-name: Registrations
short_description:
description: |-
A shorter description of the instance.
Should be HTML formatted, but might be plaintext.
This should be displayed on the instance splash/landing page.
type: string
x-go-name: ShortDescription
stats:
additionalProperties:
format: int64
type: integer
description: 'Statistics about the instance: number of posts, accounts, etc.'
type: object
x-go-name: Stats
thumbnail:
description: URL of the instance avatar/banner image.
example: https://example.org/files/instance/thumbnail.jpeg
type: string
x-go-name: Thumbnail
title:
description: The title of the instance.
example: GoToSocial Example Instance
type: string
x-go-name: Title
uri:
description: The URI of the instance.
example: https://example.org
type: string
x-go-name: URI
urls:
$ref: '#/definitions/instanceURLs'
version:
description: |-
The version of GoToSocial installed on the instance.
This will contain at least a semantic version number.
It may also contain, after a space, the short git commit ID of the running software.
example: 0.1.1 cb85f65
type: string
x-go-name: Version
title: Instance models information about this or another instance.
type: object
x-go-name: Instance
x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/model
instanceURLs:
properties:
streaming_api:
description: Websockets address for status and notification streaming.
example: wss://example.org
type: string
x-go-name: StreamingAPI
title: InstanceURLs models instance-relevant URLs for client application consumption.
type: object
x-go-name: InstanceURLs
x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/model
mediaDimensions:
properties:
aspect:
description: |-
Aspect ratio of the media.
Equal to width / height.
example: 1.777777778
format: float
type: number
x-go-name: Aspect
bitrate:
description: Bitrate of the media in bits per second.
example: 1000000
format: int64
type: integer
x-go-name: Bitrate
duration:
description: |-
Duration of the media in seconds.
Only set for video and audio.
example: 5.43
format: float
type: number
x-go-name: Duration
frame_rate:
description: |-
Framerate of the media.
Only set for video and gifs.
example: "30"
type: string
x-go-name: FrameRate
height:
description: |-
Height of the media in pixels.
Not set for audio.
example: 1080
format: int64
type: integer
x-go-name: Height
size:
description: |-
Size of the media, in the format `[width]x[height]`.
Not set for audio.
example: 1920x1080
type: string
x-go-name: Size
width:
description: |-
Width of the media in pixels.
Not set for audio.
example: 1920
format: int64
type: integer
x-go-name: Width
title: MediaDimensions models detailed properties of a piece of media.
type: object
x-go-name: MediaDimensions
x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/model
mediaFocus:
properties:
x:
description: |-
x position of the focus
should be between -1 and 1
format: float
type: number
x-go-name: X
"y":
description: |-
y position of the focus
should be between -1 and 1
format: float
type: number
x-go-name: "Y"
title: MediaFocus models the focal point of a piece of media.
type: object
x-go-name: MediaFocus
x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/model
mediaMeta:
description: This can be metadata about an image, an audio file, video, etc.
properties:
aspect:
description: |-
Aspect ratio of the media.
Equal to width / height.
example: 1.777777778
format: float
type: number
x-go-name: Aspect
audio_bitrate:
type: string
x-go-name: AudioBitrate
audio_channels:
type: string
x-go-name: AudioChannels
audio_encode:
type: string
x-go-name: AudioEncode
duration:
description: |-
Duration of the media in seconds.
Only set for video and audio.
example: 5.43
format: float
type: number
x-go-name: Duration
focus:
$ref: '#/definitions/mediaFocus'
fps:
description: |-
Framerate of the media.
Only set for video and gifs.
example: 30
format: uint16
type: integer
x-go-name: FPS
height:
description: |-
Height of the media in pixels.
Not set for audio.
example: 1080
format: int64
type: integer
x-go-name: Height
length:
type: string
x-go-name: Length
original:
$ref: '#/definitions/mediaDimensions'
size:
description: |-
Size of the media, in the format `[width]x[height]`.
Not set for audio.
example: 1920x1080
type: string
x-go-name: Size
small:
$ref: '#/definitions/mediaDimensions'
width:
description: |-
Width of the media in pixels.
Not set for audio.
example: 1920
format: int64
type: integer
x-go-name: Width
title: MediaMeta models media metadata.
type: object
x-go-name: MediaMeta
x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/model
nodeinfo:
description: 'See: https://nodeinfo.diaspora.software/schema.html'
properties:
metadata:
additionalProperties:
type: object
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
oauthToken:
properties:
access_token:
description: Access token used for authorization.
type: string
x-go-name: AccessToken
created_at:
description: When the OAuth token was generated (UNIX timestamp seconds).
example: 1627644520
format: int64
type: integer
x-go-name: CreatedAt
scope:
description: OAuth scopes granted by this token, space-separated.
example: read write admin
type: string
x-go-name: Scope
token_type:
description: OAuth token type. Will always be 'Bearer'.
example: bearer
type: string
x-go-name: TokenType
title: Token represents an OAuth token used for authenticating with the GoToSocial
API and performing actions.
type: object
x-go-name: Token
x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/model
poll:
properties:
emojis:
description: Custom emoji to be used for rendering poll options.
items:
$ref: '#/definitions/emoji'
type: array
x-go-name: Emojis
expired:
description: Is the poll currently expired?
type: boolean
x-go-name: Expired
expires_at:
description: When the poll ends. (ISO 8601 Datetime), or null if the poll
does not end
type: string
x-go-name: ExpiresAt
id:
description: The ID of the poll in the database.
example: 01FBYKMD1KBMJ0W6JF1YZ3VY5D
type: string
x-go-name: ID
multiple:
description: Does the poll allow multiple-choice answers?
type: boolean
x-go-name: Multiple
options:
description: Possible answers for the poll.
items:
$ref: '#/definitions/pollOptions'
type: array
x-go-name: Options
own_votes:
description: When called with a user token, which options has the authorized
user chosen? Contains an array of index values for options.
items:
format: int64
type: integer
type: array
x-go-name: OwnVotes
voted:
description: When called with a user token, has the authorized user voted?
type: boolean
x-go-name: Voted
voters_count:
description: How many unique accounts have voted on a multiple-choice poll.
Null if multiple is false.
format: int64
type: integer
x-go-name: VotersCount
votes_count:
description: How many votes have been received.
format: int64
type: integer
x-go-name: VotesCount
title: Poll represents a poll attached to a status.
type: object
x-go-name: Poll
x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/model
pollOptions:
properties:
title:
description: The text value of the poll option. String.
type: string
x-go-name: Title
votes_count:
description: |-
The number of received votes for this option.
Number, or null if results are not published yet.
format: int64
type: integer
x-go-name: VotesCount
title: PollOptions represents the current vote counts for different poll options.
type: object
x-go-name: PollOptions
x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/model
searchResult:
properties:
accounts:
items:
$ref: '#/definitions/account'
type: array
x-go-name: Accounts
hashtags:
items:
$ref: '#/definitions/tag'
type: array
x-go-name: Hashtags
statuses:
items:
$ref: '#/definitions/status'
type: array
x-go-name: Statuses
title: SearchResult models a search result.
type: object
x-go-name: SearchResult
x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/model
status:
properties:
account:
$ref: '#/definitions/account'
application:
$ref: '#/definitions/application'
bookmarked:
description: This status has been bookmarked by the account viewing it.
type: boolean
x-go-name: Bookmarked
card:
$ref: '#/definitions/card'
content:
description: The content of this status. Should be HTML, but might also be
plaintext in some cases.
example: <p>Hey this is a status!</p>
type: string
x-go-name: Content
created_at:
description: The date when this status was created (ISO 8601 Datetime).
example: "2021-07-30T09:20:25+00:00"
type: string
x-go-name: CreatedAt
emojis:
description: Custom emoji to be used when rendering status content.
items:
$ref: '#/definitions/emoji'
type: array
x-go-name: Emojis
favourited:
description: This status has been favourited by the account viewing it.
type: boolean
x-go-name: Favourited
favourites_count:
description: Number of favourites/likes this status has received, according
to our instance.
format: int64
type: integer
x-go-name: FavouritesCount
id:
description: ID of the status.
example: 01FBVD42CQ3ZEEVMW180SBX03B
type: string
x-go-name: ID
in_reply_to_account_id:
description: ID of the account being replied to.
example: 01FBVD42CQ3ZEEVMW180SBX03B
type: string
x-go-name: InReplyToAccountID
in_reply_to_id:
description: ID of the status being replied to.
example: 01FBVD42CQ3ZEEVMW180SBX03B
type: string
x-go-name: InReplyToID
language:
description: Primary language of this status (ISO 639 Part 1 two-letter language
code).
example: en
type: string
x-go-name: Language
media_attachments:
description: Media that is attached to this status.
items:
$ref: '#/definitions/attachment'
type: array
x-go-name: MediaAttachments
mentions:
description: Mentions of users within the status content.
items:
$ref: '#/definitions/Mention'
type: array
x-go-name: Mentions
muted:
description: Replies to this status have been muted by the account viewing
it.
type: boolean
x-go-name: Muted
pinned:
description: This status has been pinned by the account viewing it (only relevant
for your own statuses).
type: boolean
x-go-name: Pinned
poll:
$ref: '#/definitions/poll'
reblog:
$ref: '#/definitions/statusReblogged'
reblogged:
description: This status has been boosted/reblogged by the account viewing
it.
type: boolean
x-go-name: Reblogged
reblogs_count:
description: Number of times this status has been boosted/reblogged, according
to our instance.
format: int64
type: integer
x-go-name: ReblogsCount
replies_count:
description: Number of replies to this status, according to our instance.
format: int64
type: integer
x-go-name: RepliesCount
sensitive:
description: Status contains sensitive content.
example: false
type: boolean
x-go-name: Sensitive
spoiler_text:
description: Subject, summary, or content warning for the status.
example: warning nsfw
type: string
x-go-name: SpoilerText
tags:
description: Hashtags used within the status content.
items:
$ref: '#/definitions/tag'
type: array
x-go-name: Tags
text:
description: |-
Plain-text source of a status. Returned instead of content when status is deleted,
so the user may redraft from the source text without the client having to reverse-engineer
the original text from the HTML content.
type: string
x-go-name: Text
uri:
description: ActivityPub URI of the status. Equivalent to the status's activitypub
ID.
example: https://example.org/users/some_user/statuses/01FBVD42CQ3ZEEVMW180SBX03B
type: string
x-go-name: URI
url:
description: The status's publicly available web URL. This link will only
work if the visibility of the status is 'public'.
example: https://example.org/@some_user/statuses/01FBVD42CQ3ZEEVMW180SBX03B
type: string
x-go-name: URL
visibility:
$ref: '#/definitions/statusVisibility'
title: Status models a status or post.
type: object
x-go-name: Status
x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/model
statusContext:
properties:
ancestors:
description: Parents in the thread.
items:
$ref: '#/definitions/status'
type: array
x-go-name: Ancestors
descendants:
description: Children in the thread.
items:
$ref: '#/definitions/status'
type: array
x-go-name: Descendants
title: Context models the tree around a given status.
type: object
x-go-name: Context
x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/model
statusFormat:
description: Can be either plain or markdown. Empty will default to plain.
title: StatusFormat is the format in which to parse the submitted status.
type: string
x-go-name: StatusFormat
x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/model
statusReblogged:
properties:
account:
$ref: '#/definitions/account'
application:
$ref: '#/definitions/application'
bookmarked:
description: This status has been bookmarked by the account viewing it.
type: boolean
x-go-name: Bookmarked
card:
$ref: '#/definitions/card'
content:
description: The content of this status. Should be HTML, but might also be
plaintext in some cases.
example: <p>Hey this is a status!</p>
type: string
x-go-name: Content
created_at:
description: The date when this status was created (ISO 8601 Datetime).
example: "2021-07-30T09:20:25+00:00"
type: string
x-go-name: CreatedAt
emojis:
description: Custom emoji to be used when rendering status content.
items:
$ref: '#/definitions/emoji'
type: array
x-go-name: Emojis
favourited:
description: This status has been favourited by the account viewing it.
type: boolean
x-go-name: Favourited
favourites_count:
description: Number of favourites/likes this status has received, according
to our instance.
format: int64
type: integer
x-go-name: FavouritesCount
id:
description: ID of the status.
example: 01FBVD42CQ3ZEEVMW180SBX03B
type: string
x-go-name: ID
in_reply_to_account_id:
description: ID of the account being replied to.
example: 01FBVD42CQ3ZEEVMW180SBX03B
type: string
x-go-name: InReplyToAccountID
in_reply_to_id:
description: ID of the status being replied to.
example: 01FBVD42CQ3ZEEVMW180SBX03B
type: string
x-go-name: InReplyToID
language:
description: Primary language of this status (ISO 639 Part 1 two-letter language
code).
example: en
type: string
x-go-name: Language
media_attachments:
description: Media that is attached to this status.
items:
$ref: '#/definitions/attachment'
type: array
x-go-name: MediaAttachments
mentions:
description: Mentions of users within the status content.
items:
$ref: '#/definitions/Mention'
type: array
x-go-name: Mentions
muted:
description: Replies to this status have been muted by the account viewing
it.
type: boolean
x-go-name: Muted
pinned:
description: This status has been pinned by the account viewing it (only relevant
for your own statuses).
type: boolean
x-go-name: Pinned
poll:
$ref: '#/definitions/poll'
reblog:
$ref: '#/definitions/statusReblogged'
reblogged:
description: This status has been boosted/reblogged by the account viewing
it.
type: boolean
x-go-name: Reblogged
reblogs_count:
description: Number of times this status has been boosted/reblogged, according
to our instance.
format: int64
type: integer
x-go-name: ReblogsCount
replies_count:
description: Number of replies to this status, according to our instance.
format: int64
type: integer
x-go-name: RepliesCount
sensitive:
description: Status contains sensitive content.
example: false
type: boolean
x-go-name: Sensitive
spoiler_text:
description: Subject, summary, or content warning for the status.
example: warning nsfw
type: string
x-go-name: SpoilerText
tags:
description: Hashtags used within the status content.
items:
$ref: '#/definitions/tag'
type: array
x-go-name: Tags
text:
description: |-
Plain-text source of a status. Returned instead of content when status is deleted,
so the user may redraft from the source text without the client having to reverse-engineer
the original text from the HTML content.
type: string
x-go-name: Text
uri:
description: ActivityPub URI of the status. Equivalent to the status's activitypub
ID.
example: https://example.org/users/some_user/statuses/01FBVD42CQ3ZEEVMW180SBX03B
type: string
x-go-name: URI
url:
description: The status's publicly available web URL. This link will only
work if the visibility of the status is 'public'.
example: https://example.org/@some_user/statuses/01FBVD42CQ3ZEEVMW180SBX03B
type: string
x-go-name: URL
visibility:
$ref: '#/definitions/statusVisibility'
title: StatusReblogged represents a reblogged status.
type: object
x-go-name: StatusReblogged
x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/model
statusVisibility:
title: Visibility models the visibility of a status.
type: string
x-go-name: Visibility
x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/model
swaggerCollection:
properties:
'@context':
description: ActivityStreams context.
example: https://www.w3.org/ns/activitystreams
type: string
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/s2s/user
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/s2s/user
tag:
properties:
name:
description: 'The value of the hashtag after the # sign.'
example: helloworld
type: string
x-go-name: Name
url:
description: Web link to the hashtag.
example: https://example.org/tags/helloworld
type: string
x-go-name: URL
title: Tag represents a hashtag used within the content of a status.
type: object
x-go-name: Tag
x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/model
updateField:
description: By default, max 4 fields and 255 characters per property/value.
properties:
name:
description: Name of the field
type: string
x-go-name: Name
value:
description: Value of the field
type: string
x-go-name: Value
title: UpdateField is to be used specifically in an UpdateCredentialsRequest.
type: object
x-go-name: UpdateField
x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/model
updateSource:
properties:
language:
description: Default language to use for authored statuses. (ISO 6391)
type: string
x-go-name: Language
privacy:
description: Default post privacy for authored statuses.
type: string
x-go-name: Privacy
sensitive:
description: Mark authored statuses as sensitive by default.
type: boolean
x-go-name: Sensitive
title: UpdateSource is to be used specifically in an UpdateCredentialsRequest.
type: object
x-go-name: UpdateSource
x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/model
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
description: GoToSocial Swagger documentation.
license:
name: AGPL3
url: https://www.gnu.org/licenses/agpl-3.0.en.html
title: GoToSocial
version: REPLACE_ME
paths:
/.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: Directs callers to /nodeinfo/2.0.
tags:
- nodeinfo
/.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/json
responses:
"200":
description: ""
schema:
$ref: '#/definitions/wellKnownResponse'
summary: Handles webfinger account lookup requests.
tags:
- webfinger
/api/v1/accounts:
post:
consumes:
- application/json
- application/xml
- application/x-www-form-urlencoded
description: |-
The parameters can also be given in the body of the request, as JSON, if the content-type is set to 'application/json'.
The parameters can also be given in the body of the request, as XML, if the content-type is set to 'application/xml'.
operationId: accountCreate
parameters:
- description: Text that will be reviewed by moderators if registrations require
manual approval.
in: query
name: reason
type: string
x-go-name: Reason
- description: The desired username for the account.
in: query
name: username
type: string
x-go-name: Username
- description: The email address to be used for login.
in: query
name: email
type: string
x-go-name: Email
- description: The password to be used for login. This will be hashed before
storage.
in: query
name: password
type: string
x-go-name: Password
- description: The user agrees to the terms, conditions, and policies of the
instance.
in: query
name: agreement
type: boolean
x-go-name: Agreement
- description: The language of the confirmation email that will be sent.
in: query
name: locale
type: string
x-go-name: Locale
produces:
- application/json
responses:
"200":
description: An OAuth2 access token for the newly-created account.
schema:
$ref: '#/definitions/oauthToken'
"400":
description: bad request
"401":
description: unauthorized
"404":
description: not found
"500":
description: internal error
security:
- OAuth2 Application:
- write:accounts
summary: Create a new account using an application token.
tags:
- accounts
/api/v1/accounts/{id}:
get:
operationId: accountGet
parameters:
- description: The id of the requested account.
in: path
name: id
required: true
type: string
produces:
- application/json
responses:
"200":
description: ""
schema:
$ref: '#/definitions/account'
"400":
description: bad request
"401":
description: unauthorized
"404":
description: not found
security:
- OAuth2 Bearer:
- read:accounts
summary: Get information about an account with the given ID.
tags:
- accounts
/api/v1/accounts/{id}/block:
post:
operationId: accountBlock
parameters:
- description: The id of the account to block.
in: path
name: id
required: true
type: string
produces:
- application/json
responses:
"200":
description: Your relationship to this account.
schema:
$ref: '#/definitions/accountRelationship'
"400":
description: bad request
"401":
description: unauthorized
"404":
description: not found
security:
- OAuth2 Bearer:
- write:blocks
summary: Block account with id.
tags:
- accounts
/api/v1/accounts/{id}/follow:
post:
consumes:
- application/json
- application/xml
- application/x-www-form-urlencoded
description: |-
The parameters can also be given in the body of the request, as JSON, if the content-type is set to 'application/json'.
The parameters can also be given in the body of the request, as XML, if the content-type is set to 'application/xml'.
operationId: accountFollow
parameters:
- description: ID of the account to follow.
in: path
name: id
required: true
type: string
- default: true
description: Show reblogs from this account.
in: formData
name: reblogs
type: boolean
x-go-name: Reblogs
- default: false
description: Notify when this account posts.
in: formData
name: notify
type: boolean
x-go-name: Notify
produces:
- application/json
responses:
"200":
description: Your relationship to this account.
schema:
$ref: '#/definitions/accountRelationship'
"400":
description: bad request
"401":
description: unauthorized
"404":
description: not found
security:
- OAuth2 Bearer:
- write:follows
summary: Follow account with id.
tags:
- accounts
/api/v1/accounts/{id}/followers:
get:
operationId: accountFollowers
parameters:
- description: Account ID.
in: path
name: id
required: true
type: string
produces:
- application/json
responses:
"200":
description: Array of accounts that follow this account.
schema:
items:
$ref: '#/definitions/account'
type: array
"400":
description: bad request
"401":
description: unauthorized
"404":
description: not found
security:
- OAuth2 Bearer:
- read:accounts
summary: See followers of account with given id.
tags:
- accounts
/api/v1/accounts/{id}/following:
get:
operationId: accountFollowing
parameters:
- description: Account ID.
in: path
name: id
required: true
type: string
produces:
- application/json
responses:
"200":
description: Array of accounts that are followed by this account.
schema:
items:
$ref: '#/definitions/account'
type: array
"400":
description: bad request
"401":
description: unauthorized
"404":
description: not found
security:
- OAuth2 Bearer:
- read:accounts
summary: See accounts followed by given account id.
tags:
- accounts
/api/v1/accounts/{id}/statuses:
get:
description: The statuses will be returned in descending chronological order
(newest first), with sequential IDs (bigger = newer).
operationId: accountStatuses
parameters:
- description: Account ID.
in: path
name: id
required: true
type: string
- default: 30
description: Number of statuses to return.
in: query
name: limit
type: integer
- default: false
description: Exclude statuses that are a reply to another status.
in: query
name: exclude_replies
type: boolean
- default: false
description: Exclude statuses that are a reblog/boost of another status.
in: query
name: exclude_reblogs
type: boolean
- description: |-
Return only statuses *OLDER* than the given max status ID.
The status with the specified ID will not be included in the response.
in: query
name: max_id
type: string
- description: |-
Return only statuses *NEWER* than the given min status ID.
The status with the specified ID will not be included in the response.
in: query
name: min_id
type: string
- default: false
description: Show only pinned statuses. In other words, exclude statuses that
are not pinned to the given account ID.
in: query
name: pinned_only
type: boolean
- default: false
description: Show only statuses with media attachments.
in: query
name: only_media
type: boolean
- default: false
description: Show only statuses with a privacy setting of 'public'.
in: query
name: only_public
type: boolean
produces:
- application/json
responses:
"200":
description: Array of statuses.
schema:
items:
$ref: '#/definitions/status'
type: array
"400":
description: bad request
"401":
description: unauthorized
"404":
description: not found
security:
- OAuth2 Bearer:
- read:accounts
summary: See statuses posted by the requested account.
tags:
- accounts
/api/v1/accounts/{id}/unblock:
post:
operationId: accountUnblock
parameters:
- description: The id of the account to unblock.
in: path
name: id
required: true
type: string
produces:
- application/json
responses:
"200":
description: Your relationship to this account.
schema:
$ref: '#/definitions/accountRelationship'
"400":
description: bad request
"401":
description: unauthorized
"404":
description: not found
security:
- OAuth2 Bearer:
- write:blocks
summary: Unblock account with ID.
tags:
- accounts
/api/v1/accounts/{id}/unfollow:
post:
operationId: accountUnfollow
parameters:
- description: The id of the account to unfollow.
in: path
name: id
required: true
type: string
produces:
- application/json
responses:
"200":
description: Your relationship to this account.
schema:
$ref: '#/definitions/accountRelationship'
"400":
description: bad request
"401":
description: unauthorized
"404":
description: not found
security:
- OAuth2 Bearer:
- write:follows
summary: Unfollow account with id.
tags:
- accounts
/api/v1/accounts/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
security:
- OAuth2 Bearer:
- write:accounts
summary: Delete your account.
tags:
- accounts
/api/v1/accounts/relationships:
get:
operationId: accountRelationships
parameters:
- description: Account IDs.
in: query
items:
type: string
name: id
required: true
type: array
produces:
- application/json
responses:
"200":
description: Array of account relationships.
schema:
items:
$ref: '#/definitions/accountRelationship'
type: array
"400":
description: bad request
"401":
description: unauthorized
"404":
description: not found
security:
- OAuth2 Bearer:
- read:accounts
summary: See your account's relationships with the given account IDs.
tags:
- accounts
/api/v1/accounts/update_credentials:
patch:
consumes:
- multipart/form-data
operationId: accountUpdate
parameters:
- description: Account should be made discoverable and shown in the profile
directory (if enabled).
in: formData
name: discoverable
type: boolean
- description: Account is flagged as a bot.
in: formData
name: bot
type: boolean
- allowEmptyValue: true
description: The display name to use for the account.
in: formData
name: display_name
type: string
- allowEmptyValue: true
description: Bio/description of this account.
in: formData
name: note
type: string
- description: Avatar of the user.
in: formData
name: avatar
type: file
- description: Header of the user.
in: formData
name: header
type: file
- description: Require manual approval of follow requests.
in: formData
name: locked
type: boolean
- description: Default post privacy for authored statuses.
in: formData
name: source[privacy]
type: string
- description: Mark authored statuses as sensitive by default.
in: formData
name: source[sensitive]
type: boolean
- description: Default language to use for authored statuses (ISO 6391).
in: formData
name: source[language]
type: string
produces:
- application/json
responses:
"200":
description: The newly updated account.
schema:
$ref: '#/definitions/account'
"400":
description: bad request
"401":
description: unauthorized
security:
- OAuth2 Bearer:
- write:accounts
summary: Update your account.
tags:
- accounts
/api/v1/accounts/verify_credentials:
get:
operationId: accountVerify
produces:
- application/json
responses:
"200":
description: ""
schema:
$ref: '#/definitions/account'
"400":
description: bad request
"401":
description: unauthorized
"404":
description: not found
security:
- OAuth2 Bearer:
- read:accounts
summary: Verify a token by returning account details pertaining to it.
tags:
- accounts
/api/v1/admin/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. One of: disable, silence, 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
security:
- OAuth2 Bearer:
- admin
summary: Perform an admin action on an account.
tags:
- admin
/api/v1/admin/custom_emojis:
post:
consumes:
- multipart/form-data
operationId: emojiCreate
parameters:
- description: |-
The code to use for the emoji, which will be used by instance denizens to select it.
This must be unique on the instance.
in: formData
name: shortcode
pattern: \w{2,30}
required: true
type: string
- description: A png or gif image of the emoji. Animated pngs work too!
in: formData
name: image
required: true
type: file
produces:
- application/json
responses:
"200":
description: The newly-created emoji.
schema:
$ref: '#/definitions/emoji'
"400":
description: bad request
"403":
description: forbidden
"409":
description: conflict -- domain/shortcode combo for emoji already exists
security:
- OAuth2 Bearer:
- admin
summary: Upload and create a new instance emoji.
tags:
- admin
/api/v1/admin/domain_blocks:
get:
operationId: domainBlocksGet
parameters:
- description: |-
If set to true, then each entry in the returned list of domain blocks will only consist of
the fields 'domain' and 'public_comment'. This is perfect for when you want to save and share
a list of all the domains you have blocked on your instance, so that someone else can easily import them,
but you don't need them to see the database IDs of your blocks, or private comments etc.
in: query
name: export
type: boolean
produces:
- application/json
responses:
"200":
description: All domain blocks currently in place.
schema:
items:
$ref: '#/definitions/domainBlock'
type: array
"400":
description: bad request
"403":
description: forbidden
"404":
description: not found
security:
- OAuth2 Bearer:
- admin
summary: View all domain blocks currently in place.
tags:
- admin
post:
consumes:
- multipart/form-data
description: |-
Note that you have two options when using this endpoint: either you can set `import` to true
and upload a file containing multiple domain blocks, JSON-formatted, or you can leave import as
false, and just add one domain block.
The format of the json file should be something like: `[{"domain":"example.org"},{"domain":"whatever.com","public_comment":"they smell"}]`
operationId: domainBlockCreate
parameters:
- description: |-
Signal that a list of domain blocks is being imported as a file.
If set to true, then 'domains' must be present as a JSON-formatted file.
If set to false, then 'domains' will be ignored, and 'domain' must be present.
in: query
name: import
type: boolean
- description: |-
JSON-formatted list of domain blocks to import.
This is only used if `import` is set to true.
in: formData
name: domains
type: file
- description: |-
Single domain to block.
Used only if `import` is not true.
in: formData
name: domain
type: string
- description: |-
Obfuscate the name of the domain when serving it publicly.
Eg., 'example.org' becomes something like 'ex***e.org'.
Used only if `import` is not true.
in: formData
name: obfuscate
type: boolean
- description: |-
Public comment about this domain block.
Will be displayed alongside the domain block if you choose to share blocks.
Used only if `import` is not true.
in: formData
name: public_comment
type: string
- description: |-
Private comment about this domain block. Will only be shown to other admins, so this
is a useful way of internally keeping track of why a certain domain ended up blocked.
Used only if `import` is not true.
in: formData
name: private_comment
type: string
produces:
- application/json
responses:
"200":
description: |-
The newly created domain block, if `import` != `true`.
Note that if a list has been imported, then an `array` of newly created domain blocks will be returned instead.
schema:
$ref: '#/definitions/domainBlock'
"400":
description: bad request
"403":
description: forbidden
security:
- OAuth2 Bearer:
- admin
summary: Create one or more domain blocks, from a string or a file.
tags:
- admin
/api/v1/admin/domain_blocks/{id}:
delete:
operationId: domainBlockDelete
parameters:
- description: The id of the domain block.
in: path
name: id
required: true
type: string
produces:
- application/json
responses:
"200":
description: The domain block that was just deleted.
schema:
$ref: '#/definitions/domainBlock'
"400":
description: bad request
"403":
description: forbidden
"404":
description: not found
security:
- OAuth2 Bearer:
- admin
summary: Delete domain block with the given ID.
tags:
- admin
get:
operationId: domainBlockGet
parameters:
- description: The id of the domain block.
in: path
name: id
required: true
type: string
produces:
- application/json
responses:
"200":
description: The requested domain block.
schema:
$ref: '#/definitions/domainBlock'
"400":
description: bad request
"403":
description: forbidden
"404":
description: not found
security:
- OAuth2 Bearer:
- admin
summary: View domain block with the given ID.
tags:
- admin
/api/v1/apps:
post:
consumes:
- application/json
- application/xml
- application/x-www-form-urlencoded
description: |-
The registered application can be used to obtain an application token.
This can then be used to register a new account, or (through user auth) obtain an access token.
The parameters can also be given in the body of the request, as JSON, if the content-type is set to 'application/json'.
The parameters can also be given in the body of the request, as XML, if the content-type is set to 'application/xml'.
operationId: appCreate
parameters:
- description: The name of the application.
in: formData
name: client_name
required: true
type: string
x-go-name: ClientName
- description: |-
Where the user should be redirected after authorization.
To display the authorization code to the user instead of redirecting to a web page, use `urn:ietf:wg:oauth:2.0:oob` in this parameter.
in: formData
name: redirect_uris
required: true
type: string
x-go-name: RedirectURIs
- description: |-
Space separated list of scopes.
If no scopes are provided, defaults to `read`.
in: formData
name: scopes
type: string
x-go-name: Scopes
- description: A URL to the web page of the app (optional).
in: formData
name: website
type: string
x-go-name: Website
produces:
- application/json
responses:
"200":
description: The newly-created application.
schema:
$ref: '#/definitions/application'
"400":
description: bad request
"401":
description: unauthorized
"422":
description: unprocessable
"500":
description: internal error
summary: Register a new application on this instance.
tags:
- apps
/api/v1/blocks:
get:
description: |-
The next and previous queries can be parsed from the returned Link header.
Example:
```
<https://example.org/api/v1/blocks?limit=80&max_id=01FC0SKA48HNSVR6YKZCQGS2V8>; rel="next", <https://example.org/api/v1/blocks?limit=80&min_id=01FC0SKW5JK2Q4EVAV2B462YY0>; rel="prev"
````
operationId: blocksGet
parameters:
- default: 20
description: Number of blocks to return.
in: query
name: limit
type: integer
- description: |-
Return only blocks *OLDER* than the given max block ID.
The block with the specified ID will not be included in the response.
in: query
name: max_id
type: string
- description: |-
Return only blocks *NEWER* than the given since block ID.
The block with the specified ID will not be included in the response.
in: query
name: since_id
type: string
produces:
- application/json
responses:
"200":
description: ""
headers:
Link:
description: Links to the next and previous queries.
type: string
schema:
items:
$ref: '#/definitions/account'
type: array
"400":
description: bad request
"401":
description: unauthorized
"404":
description: not found
security:
- OAuth2 Bearer:
- read:blocks
summary: Get an array of accounts that requesting account has blocked.
tags:
- blocks
/api/v1/follow_requests:
get:
description: |-
The next and previous queries can be parsed from the returned Link header.
Example:
```
<https://example.org/api/v1/follow_requests?limit=80&max_id=01FC0SKA48HNSVR6YKZCQGS2V8>; rel="next", <https://example.org/api/v1/follow_requests?limit=80&min_id=01FC0SKW5JK2Q4EVAV2B462YY0>; rel="prev"
````
operationId: getFollowRequests
parameters:
- default: 40
description: Number of accounts to return.
in: query
name: limit
type: integer
produces:
- application/json
responses:
"200":
description: ""
headers:
Link:
description: Links to the next and previous queries.
type: string
schema:
items:
$ref: '#/definitions/account'
type: array
"400":
description: bad request
"401":
description: unauthorized
"403":
description: forbidden
"404":
description: not found
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
"403":
description: forbidden
"404":
description: not found
"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
"403":
description: forbidden
"404":
description: not found
"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:
description: |-
This is mostly provided for Mastodon application compatibility, since many apps that work with Mastodon use `/api/v1/instance` to inform their connection parameters.
However, it can also be used by other instances for gathering instance information and representing instances in some UI or other.
operationId: instanceGet
produces:
- application/json
responses:
"200":
description: Instance information.
schema:
$ref: '#/definitions/instance'
"500":
description: internal error
summary: View instance information.
tags:
- instance
patch:
consumes:
- multipart/form-data
description: This requires admin permissions on the instance.
operationId: instanceUpdate
parameters:
- allowEmptyValue: true
description: Title to use for the instance.
in: formData
maximum: 40
name: title
type: string
- allowEmptyValue: true
description: |-
Username of the contact account.
This must be the username of an instance admin.
in: formData
name: contact_username
type: string
- allowEmptyValue: true
description: Email address to use as the instance contact.
in: formData
name: contact_email
type: string
- allowEmptyValue: true
description: Short description of the instance.
in: formData
maximum: 500
name: short_description
type: string
- allowEmptyValue: true
description: Longer description of the instance.
in: formData
maximum: 5000
name: description
type: string
- allowEmptyValue: true
description: Terms and conditions of the instance.
in: formData
maximum: 5000
name: terms
type: string
- description: Avatar of the instance.
in: formData
name: avatar
type: file
- description: Header of the instance.
in: formData
name: header
type: file
produces:
- application/json
responses:
"200":
description: The newly updated instance.
schema:
$ref: '#/definitions/instance'
"400":
description: bad request
"401":
description: unauthorized
security:
- OAuth2 Bearer:
- admin
summary: Update your instance information and/or upload a new avatar/header
for the instance.
tags:
- instance
/api/v1/media:
post:
consumes:
- multipart/form-data
operationId: mediaCreate
parameters:
- description: |-
Image or media description to use as alt-text on the attachment.
This is very useful for users of screenreaders.
May or may not be required, depending on your instance settings.
in: formData
name: description
type: string
- description: |-
Focus of the media file.
If present, it should be in the form of two comma-separated floats between -1 and 1.
For example: `-0.5,0.25`.
in: formData
name: focus
type: string
- description: The media attachment to upload.
in: formData
name: file
required: true
type: file
produces:
- application/json
responses:
"200":
description: The newly-created media attachment.
schema:
$ref: '#/definitions/attachment'
"400":
description: bad request
"401":
description: unauthorized
"403":
description: forbidden
"422":
description: unprocessable
security:
- OAuth2 Bearer:
- write:media
summary: Upload a new media attachment.
tags:
- media
/api/v1/media/{id}:
get:
operationId: mediaGet
parameters:
- description: id of the attachment
in: path
name: id
required: true
type: string
produces:
- application/json
responses:
"200":
description: The requested media attachment.
schema:
$ref: '#/definitions/attachment'
"400":
description: bad request
"401":
description: unauthorized
"403":
description: forbidden
"422":
description: unprocessable
security:
- OAuth2 Bearer:
- read:media
summary: Get a media attachment that you own.
tags:
- media
put:
consumes:
- application/json
- application/xml
- application/x-www-form-urlencoded
description: |-
You must own the media attachment, and the attachment must not yet be attached to a status.
The parameters can also be given in the body of the request, as JSON, if the content-type is set to 'application/json'.
The parameters can also be given in the body of the request, as XML, if the content-type is set to 'application/xml'.
operationId: mediaUpdate
parameters:
- description: id of the attachment to update
in: path
name: id
required: true
type: string
- allowEmptyValue: true
description: |-
Image or media description to use as alt-text on the attachment.
This is very useful for users of screenreaders.
May or may not be required, depending on your instance settings.
in: formData
name: description
type: string
- allowEmptyValue: true
description: |-
Focus of the media file.
If present, it should be in the form of two comma-separated floats between -1 and 1.
For example: `-0.5,0.25`.
in: formData
name: focus
type: string
produces:
- application/json
responses:
"200":
description: The newly-updated media attachment.
schema:
$ref: '#/definitions/attachment'
"400":
description: bad request
"401":
description: unauthorized
"403":
description: forbidden
"422":
description: unprocessable
security:
- OAuth2 Bearer:
- write:media
summary: Update a media attachment.
tags:
- media
/api/v1/search:
get:
description: If statuses are in the result, they will be returned in descending
chronological order (newest first), with sequential IDs (bigger = newer).
operationId: searchGet
parameters:
- description: If type is `statuses`, then statuses returned will be authored
only by this account.
in: query
name: account_id
type: string
x-go-name: AccountID
- description: |-
Return results *older* than this id.
The entry with this ID will not be included in the search results.
in: query
name: max_id
type: string
x-go-name: MaxID
- description: |-
Return results *newer* than this id.
The entry with this ID will not be included in the search results.
in: query
name: min_id
type: string
x-go-name: MinID
- description: |-
Type of the search query to perform.
Must be one of: `accounts`, `hashtags`, `statuses`.
in: query
name: type
required: true
type: string
x-go-name: Type
- default: false
description: Filter out tags that haven't been reviewed and approved by an
instance admin.
in: query
name: exclude_unreviewed
type: boolean
x-go-name: ExcludeUnreviewed
- description: |-
String to use as a search query.
For accounts, this should be in the format `@someaccount@some.instance.com`, or the format `https://some.instance.com/@someaccount`
For a status, this can be in the format: `https://some.instance.com/@someaccount/SOME_ID_OF_A_STATUS`
in: query
name: q
required: true
type: string
x-go-name: Query
- default: false
description: Attempt to resolve the query by performing a remote webfinger
lookup, if the query includes a remote host.
in: query
name: resolve
type: boolean
x-go-name: Resolve
- default: 20
description: Maximum number of results to load, per type.
format: int64
in: query
maximum: 40
minimum: 1
name: limit
type: integer
x-go-name: Limit
- default: 0
description: Offset for paginating search results.
format: int64
in: query
name: offset
type: integer
x-go-name: Offset
- default: false
description: Only include accounts that the searching account is following.
in: query
name: following
type: boolean
x-go-name: Following
responses:
"200":
description: Results of the search.
schema:
items:
$ref: '#/definitions/searchResult'
type: array
"400":
description: bad request
"401":
description: unauthorized
security:
- OAuth2 Bearer:
- read:search
summary: Search for statuses, accounts, or hashtags, on this instance or elsewhere.
tags:
- search
/api/v1/statuses:
post:
consumes:
- application/json
- application/xml
- application/x-www-form-urlencoded
description: |-
The parameters can also be given in the body of the request, as JSON, if the content-type is set to 'application/json'.
The parameters can also be given in the body of the request, as XML, if the content-type is set to 'application/xml'.
operationId: statusCreate
parameters:
- description: |-
Text content of the status.
If media_ids is provided, this becomes optional.
Attaching a poll is optional while status is provided.
in: formData
name: status
type: string
x-go-name: Status
- description: |-
Array of Attachment ids to be attached as media.
If provided, status becomes optional, and poll cannot be used.
in: formData
items:
type: string
name: media_ids
type: array
x-go-name: MediaIDs
- description: ID of the status being replied to, if status is a reply.
in: formData
name: in_reply_to_id
type: string
x-go-name: InReplyToID
- description: Status and attached media should be marked as sensitive.
in: formData
name: sensitive
type: boolean
x-go-name: Sensitive
- description: |-
Text to be shown as a warning or subject before the actual content.
Statuses are generally collapsed behind this field.
in: formData
name: spoiler_text
type: string
x-go-name: SpoilerText
- description: Visibility of the posted status.
in: formData
name: visibility
type: string
x-go-name: Visibility
- description: |-
ISO 8601 Datetime at which to schedule a status.
Providing this paramter will cause ScheduledStatus to be returned instead of Status.
Must be at least 5 minutes in the future.
in: formData
name: scheduled_at
type: string
x-go-name: ScheduledAt
- description: ISO 639 language code for this status.
in: formData
name: language
type: string
x-go-name: Language
- description: Format to use when parsing this status.
in: formData
name: format
type: string
x-go-name: Format
produces:
- application/json
responses:
"200":
description: The newly created status.
schema:
$ref: '#/definitions/status'
"400":
description: bad request
"401":
description: unauthorized
"404":
description: not found
"500":
description: internal error
security:
- OAuth2 Bearer:
- write:statuses
summary: Create a new status.
tags:
- statuses
/api/v1/statuses/{id}:
delete:
description: |-
The deleted status will be returned in the response. The `text` field will contain the original text of the status as it was submitted.
This is useful when doing a 'delete and redraft' type operation.
operationId: statusDelete
parameters:
- description: Target status ID.
in: path
name: id
required: true
type: string
produces:
- application/json
responses:
"200":
description: The newly deleted status.
schema:
$ref: '#/definitions/status'
"400":
description: bad request
"401":
description: unauthorized
"403":
description: forbidden
"404":
description: not found
security:
- OAuth2 Bearer:
- write:statuses
summary: Delete status with the given ID. The status must belong to you.
tags:
- statuses
get:
operationId: statusGet
parameters:
- description: Target status ID.
in: path
name: id
required: true
type: string
produces:
- application/json
responses:
"200":
description: The requested created status.
schema:
$ref: '#/definitions/status'
"400":
description: bad request
"401":
description: unauthorized
"404":
description: not found
"500":
description: internal error
security:
- OAuth2 Bearer:
- read:statuses
summary: View status with the given ID.
tags:
- statuses
/api/v1/statuses/{id}/context:
get:
description: The returned statuses will be ordered in a thread structure, so
they are suitable to be displayed in the order in which they were returned.
operationId: statusContext
parameters:
- description: Target status ID.
in: path
name: id
required: true
type: string
produces:
- application/json
responses:
"200":
description: Status context object.
schema:
$ref: '#/definitions/statusContext'
"400":
description: bad request
"401":
description: unauthorized
"403":
description: forbidden
"404":
description: not found
security:
- OAuth2 Bearer:
- read:statuses
summary: Return ancestors and descendants of the given status.
tags:
- statuses
/api/v1/statuses/{id}/favourite:
post:
operationId: statusFave
parameters:
- description: Target status ID.
in: path
name: id
required: true
type: string
produces:
- application/json
responses:
"200":
description: The newly faved status.
schema:
$ref: '#/definitions/status'
"400":
description: bad request
"401":
description: unauthorized
"403":
description: forbidden
"404":
description: not found
security:
- OAuth2 Bearer:
- write:statuses
summary: Star/like/favourite the given status, if permitted.
tags:
- statuses
/api/v1/statuses/{id}/favourited_by:
get:
operationId: statusFavedBy
parameters:
- description: Target status ID.
in: path
name: id
required: true
type: string
produces:
- application/json
responses:
"200":
description: ""
schema:
items:
$ref: '#/definitions/account'
type: array
"400":
description: bad request
"401":
description: unauthorized
"403":
description: forbidden
"404":
description: not found
security:
- OAuth2 Bearer:
- read:accounts
summary: View accounts that have faved/starred/liked the target status.
tags:
- statuses
/api/v1/statuses/{id}/reblog:
post:
description: |-
If the target status is rebloggable/boostable, it will be shared with your followers.
This is equivalent to an activitypub 'announce' activity.
operationId: statusReblog
parameters:
- description: Target status ID.
in: path
name: id
required: true
type: string
produces:
- application/json
responses:
"200":
description: The boost of the status.
schema:
$ref: '#/definitions/status'
"400":
description: bad request
"401":
description: unauthorized
"403":
description: forbidden
"404":
description: not found
security:
- OAuth2 Bearer:
- write:statuses
summary: Reblog/boost status with the given ID.
tags:
- statuses
/api/v1/statuses/{id}/reblogged_by:
get:
operationId: statusBoostedBy
parameters:
- description: Target status ID.
in: path
name: id
required: true
type: string
produces:
- application/json
responses:
"200":
description: ""
schema:
items:
$ref: '#/definitions/account'
type: array
"400":
description: bad request
"401":
description: unauthorized
"403":
description: forbidden
"404":
description: not found
security:
- OAuth2 Bearer:
- read:accounts
summary: View accounts that have reblogged/boosted the target status.
tags:
- statuses
/api/v1/statuses/{id}/unfavourite:
post:
operationId: statusUnfave
parameters:
- description: Target status ID.
in: path
name: id
required: true
type: string
produces:
- application/json
responses:
"200":
description: The unfaved status.
schema:
$ref: '#/definitions/status'
"400":
description: bad request
"401":
description: unauthorized
"403":
description: forbidden
"404":
description: not found
security:
- OAuth2 Bearer:
- write:statuses
summary: Unstar/unlike/unfavourite the given status.
tags:
- statuses
/api/v1/statuses/{id}/unreblog:
post:
operationId: statusUnreblog
parameters:
- description: Target status ID.
in: path
name: id
required: true
type: string
produces:
- application/json
responses:
"200":
description: The unboosted status.
schema:
$ref: '#/definitions/status'
"400":
description: bad request
"401":
description: unauthorized
"403":
description: forbidden
"404":
description: not found
security:
- OAuth2 Bearer:
- write:statuses
summary: Unreblog/unboost status with the given ID.
tags:
- statuses
/api/v1/streaming:
get:
description: |-
The scheme used should *always* be `wss`. The streaming basepath can be viewed at `/api/v1/instance`.
On a successful connection, a code `101` will be returned, which indicates that the connection is being upgraded to a secure websocket connection.
As long as the connection is open, various message types will be streamed into it.
GoToSocial will ping the connection every 30 seconds to check whether the client is still receiving.
If the ping fails, or something else goes wrong during transmission, then the connection will be dropped, and the client will be expected to start it again.
operationId: streamGet
parameters:
- description: Access token for the requesting account.
in: query
name: access_token
required: true
type: string
- description: |-
Type of stream to request.
Options are:
`user`: receive updates for the account's home timeline.
`public`: receive updates for the public timeline.
`public:local`: receive updates for the local timeline.
`hashtag`: receive updates for a given hashtag.
`hashtag:local`: receive local updates for a given hashtag.
`list`: receive updates for a certain list of accounts.
`direct`: receive updates for direct messages.
in: query
name: stream
required: true
type: string
produces:
- application/json
responses:
"101":
description: ""
schema:
properties:
event:
description: |-
The type of event being received.
`update`: a new status has been received.
`notification`: a new notification has been received.
`delete`: a status has been deleted.
`filters_changed`: not implemented.
enum:
- update
- notification
- delete
- filters_changed
type: string
payload:
description: |-
The payload of the streamed message.
Different depending on the `event` type.
If present, it should be parsed as a string.
If `event` = `update`, then the payload will be a JSON string of a status.
If `event` = `notification`, then the payload will be a JSON string of a notification.
If `event` = `delete`, then the payload will be a status ID.
example: '{"id":"01FC3TZ5CFG6H65GCKCJRKA669","created_at":"2021-08-02T16:25:52Z","sensitive":false,"spoiler_text":"","visibility":"public","language":"en","uri":"https://gts.superseriousbusiness.org/users/dumpsterqueer/statuses/01FC3TZ5CFG6H65GCKCJRKA669","url":"https://gts.superseriousbusiness.org/@dumpsterqueer/statuses/01FC3TZ5CFG6H65GCKCJRKA669","replies_count":0,"reblogs_count":0,"favourites_count":0,"favourited":false,"reblogged":false,"muted":false,"bookmarked":fals…//gts.superseriousbusiness.org/fileserver/01JNN207W98SGG3CBJ76R5MVDN/header/original/019036W043D8FXPJKSKCX7G965.png","header_static":"https://gts.superseriousbusiness.org/fileserver/01JNN207W98SGG3CBJ76R5MVDN/header/small/019036W043D8FXPJKSKCX7G965.png","followers_count":33,"following_count":28,"statuses_count":126,"last_status_at":"2021-08-02T16:25:52Z","emojis":[],"fields":[]},"media_attachments":[],"mentions":[],"tags":[],"emojis":[],"card":null,"poll":null,"text":"a"}'
type: string
stream:
items:
enum:
- user
- public
- public:local
- hashtag
- hashtag:local
- list
- direct
type: string
type: array
type: object
"400":
description: bad request
"401":
description: unauthorized
schemes:
- wss
security:
- OAuth2 Bearer:
- read:streaming
summary: Initiate a websocket connection for live streaming of statuses and
notifications.
tags:
- streaming
/api/v1/timelines/home:
get:
description: |-
The statuses will be returned in descending chronological order (newest first), with sequential IDs (bigger = newer).
The returned Link header can be used to generate the previous and next queries when scrolling up or down a timeline.
Example:
```
<https://example.org/api/v1/timelines/home?limit=20&max_id=01FC3GSQ8A3MMJ43BPZSGEG29M>; rel="next", <https://example.org/api/v1/timelines/home?limit=20&min_id=01FC3KJW2GYXSDDRA6RWNDM46M>; rel="prev"
````
operationId: homeTimeline
parameters:
- description: |-
Return only statuses *OLDER* than the given max status ID.
The status with the specified ID will not be included in the response.
in: query
name: max_id
type: string
- description: |-
Return only statuses *NEWER* than the given since status ID.
The status with the specified ID will not be included in the response.
in: query
name: since_id
type: string
- description: |-
Return only statuses *NEWER* than the given since status ID.
The status with the specified ID will not be included in the response.
in: query
name: min_id
type: string
- default: 20
description: Number of statuses to return.
in: query
name: limit
type: integer
- default: false
description: Show only statuses posted by local accounts.
in: query
name: local
type: boolean
produces:
- application/json
responses:
"200":
description: Array of statuses.
headers:
Link:
description: Links to the next and previous queries.
type: string
schema:
items:
$ref: '#/definitions/status'
type: array
"400":
description: bad request
"401":
description: unauthorized
security:
- OAuth2 Bearer:
- read:statuses
summary: See statuses/posts by accounts you follow.
tags:
- timelines
/api/v1/timelines/public:
get:
description: |-
The statuses will be returned in descending chronological order (newest first), with sequential IDs (bigger = newer).
The returned Link header can be used to generate the previous and next queries when scrolling up or down a timeline.
Example:
```
<https://example.org/api/v1/timelines/public?limit=20&max_id=01FC3GSQ8A3MMJ43BPZSGEG29M>; rel="next", <https://example.org/api/v1/timelines/public?limit=20&min_id=01FC3KJW2GYXSDDRA6RWNDM46M>; rel="prev"
````
operationId: publicTimeline
parameters:
- description: |-
Return only statuses *OLDER* than the given max status ID.
The status with the specified ID will not be included in the response.
in: query
name: max_id
type: string
- description: |-
Return only statuses *NEWER* than the given since status ID.
The status with the specified ID will not be included in the response.
in: query
name: since_id
type: string
- description: |-
Return only statuses *NEWER* than the given since status ID.
The status with the specified ID will not be included in the response.
in: query
name: min_id
type: string
- default: 20
description: Number of statuses to return.
in: query
name: limit
type: integer
- default: false
description: Show only statuses posted by local accounts.
in: query
name: local
type: boolean
produces:
- application/json
responses:
"200":
description: Array of statuses.
headers:
Link:
description: Links to the next and previous queries.
type: string
schema:
items:
$ref: '#/definitions/status'
type: array
"400":
description: bad request
"401":
description: unauthorized
security:
- OAuth2 Bearer:
- read:statuses
summary: See public statuses/posts that your instance is aware of.
tags:
- timelines
/api/v1/user/password_change:
post:
consumes:
- application/json
- application/xml
- application/x-www-form-urlencoded
description: |-
The parameters can also be given in the body of the request, as JSON, if the content-type is set to 'application/json'.
The parameters can also be given in the body of the request, as XML, if the content-type is set to 'application/xml'.
operationId: userPasswordChange
parameters:
- description: User's previous password.
in: formData
name: old_password
required: true
type: string
x-go-name: OldPassword
- description: |-
Desired new password.
If the password does not have high enough entropy, it will be rejected.
See https://github.com/wagslane/go-password-validator
in: formData
name: new_password
required: true
type: string
x-go-name: NewPassword
produces:
- application/json
responses:
"200":
description: Change successful
"400":
description: bad request
"401":
description: unauthorized
"403":
description: forbidden
"500":
description: internal error
security:
- OAuth2 Bearer:
- write:user
summary: Change the password of authenticated user.
tags:
- user
/nodeinfo/2.0:
get:
description: 'See: https://nodeinfo.diaspora.software/schema.html'
operationId: nodeInfoGet
produces:
- application/json; profile="http://nodeinfo.diaspora.software/ns/schema/2.0#"
responses:
"200":
description: ""
schema:
$ref: '#/definitions/nodeinfo'
summary: Returns a compliant nodeinfo response to node info queries.
tags:
- nodeinfo
/users/{username}/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:media: grant read access to media
read:search: grant read access to searches
read:statuses: grants read access to statuses
read:streaming: grants read access to streaming api
read:user: grants read access to user-level info
write: grants write access to everything
write:accounts: grants write access to accounts
write:blocks: grants write access to blocks
write:follows: grants write access to follows
write:media: grants write access to media
write:statuses: grants write access to statuses
write:user: grants write access to user-level info
tokenUrl: https://example.org/oauth/token
type: oauth2
swagger: "2.0"
Reference in New Issue View Git Blame Copy Permalink