gotosocial/docs/api/swagger.yaml

1674 lines
52 KiB
YAML
Raw Normal View 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
MIMEHeader:
additionalProperties:
items:
type: string
type: array
description: |-
A MIMEHeader represents a MIME-style header mapping
keys to sets of values.
type: object
x-go-package: net/textproto
Mention:
properties:
acct:
description: |-
The account URI as discovered via webfinger.
Equal to username for local users, or username@domain for remote users.
example: some_user@example.org
type: string
x-go-name: Acct
id:
description: The ID of the mentioned account.
example: 01FBYJHQWQZAVWFRK9PDYTKGMB
type: string
x-go-name: ID
url:
description: The web URL of the mentioned account's profile.
example: https://example.org/@some_user
type: string
x-go-name: URL
username:
description: The username of the mentioned account.
example: some_user
type: string
x-go-name: Username
title: Mention represents a mention of another account.
type: object
x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/model
Source:
description: |-
Returned as an additional entity when verifying and updated credentials, as an attribute of Account.
See https://docs.joinmastodon.org/entities/source/
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
account:
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 such as the profile
directory.
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 represents a fediverse account of some kind, either a remote one
or one on this instance.
type: object
x-go-name: Account
x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/model
accountCreateRequest:
properties:
agreement:
description: The user agrees to the terms, conditions, and policies of the
instance.
type: boolean
x-go-name: Agreement
email:
description: The email address to be used for login.
type: string
x-go-name: Email
locale:
description: The language of the confirmation email that will be sent.
type: string
x-go-name: Locale
password:
description: The password to be used for login. This will be hashed before
storage.
type: string
x-go-name: Password
reason:
description: Text that will be reviewed by moderators if registrations require
manual approval.
type: string
x-go-name: Reason
username:
description: The desired username for the account.
type: string
x-go-name: Username
title: AccountCreateRequest represents the form submitted during a POST request
to /api/v1/accounts.
type: object
x-go-name: AccountCreateRequest
x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/model
accountFollowRequest:
description: AccountFollowRequest is for parsing requests at /api/v1/accounts/:id/follow
properties:
TargetAccountID:
description: |-
ID of the account to follow request
This should be a URL parameter not a form field
type: string
notify:
description: Notify when this account posts?
type: boolean
x-go-name: Notify
reblogs:
description: Show reblogs for this account?
type: boolean
x-go-name: Reblogs
type: object
x-go-name: AccountFollowRequest
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
application:
description: Primarily, application is used for allowing apps like Tusky etc to
connect to Mastodon on behalf of a user.
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 represents an api Application, as defined here.
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.
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.
type: string
x-go-name: TextURL
type:
description: |-
The type of the attachment.
unknown = unsupported or unrecognized file type.
image = Static image.
gifv = Looping, soundless animation.
video = Video clip.
audio = Audio track.
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 represents the object returned to a client after a successful
media upload request.
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.
String (Enumerable, oneOf)
link = Link OEmbed
photo = Photo OEmbed
video = Video OEmbed
rich = iframe OEmbed. Not currently accepted, so won't show up in practice.
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
mediaDimensions:
properties:
aspect:
format: float
type: number
x-go-name: Aspect
bitrate:
format: int64
type: integer
x-go-name: Bitrate
duration:
format: float
type: number
x-go-name: Duration
frame_rate:
type: string
x-go-name: FrameRate
height:
format: int64
type: integer
x-go-name: Height
size:
type: string
x-go-name: Size
width:
format: int64
type: integer
x-go-name: Width
title: MediaDimensions describes the physical properties of a piece of media.
It should be returned to the caller as part of MediaMeta.
type: object
x-go-name: MediaDimensions
x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/model
mediaFocus:
properties:
x:
format: float
type: number
x-go-name: X
"y":
format: float
type: number
x-go-name: "Y"
title: MediaFocus describes the focal point of a piece of media. It should be
returned to the caller as part of MediaMeta.
type: object
x-go-name: MediaFocus
x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/model
mediaMeta:
description: MediaMeta describes the returned media
properties:
aspect:
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:
format: float
type: number
x-go-name: Duration
focus:
$ref: '#/definitions/mediaFocus'
fps:
format: uint16
type: integer
x-go-name: FPS
height:
format: int64
type: integer
x-go-name: Height
length:
type: string
x-go-name: Length
original:
$ref: '#/definitions/mediaDimensions'
size:
type: string
x-go-name: Size
small:
$ref: '#/definitions/mediaDimensions'
width:
format: int64
type: integer
x-go-name: Width
type: object
x-go-name: MediaMeta
x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/model
oauthToken:
properties:
access_token:
description: Access token used for authorization.
type: string
x-go-name: AccessToken
created_at:
description: When the OAuth token was generated (UNIX timestamp seconds).
example: 1627644520
format: int64
type: integer
x-go-name: CreatedAt
scope:
description: OAuth scopes granted by this token, space-separated.
example: read write admin
type: string
x-go-name: Scope
token_type:
description: OAuth token type. Will always be 'Bearer'.
example: bearer
type: string
x-go-name: TokenType
title: Token represents an OAuth token used for authenticating with the GoToSocial
API and performing actions.
type: object
x-go-name: Token
x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/model
poll:
properties:
emojis:
description: Custom emoji to be used for rendering poll options.
items:
$ref: '#/definitions/emoji'
type: array
x-go-name: Emojis
expired:
description: Is the poll currently expired?
type: boolean
x-go-name: Expired
expires_at:
description: When the poll ends. (ISO 8601 Datetime), or null if the poll
does not end
type: string
x-go-name: ExpiresAt
id:
description: The ID of the poll in the database.
example: 01FBYKMD1KBMJ0W6JF1YZ3VY5D
type: string
x-go-name: ID
multiple:
description: Does the poll allow multiple-choice answers?
type: boolean
x-go-name: Multiple
options:
description: Possible answers for the poll.
items:
$ref: '#/definitions/pollOptions'
type: array
x-go-name: Options
own_votes:
description: When called with a user token, which options has the authorized
user chosen? Contains an array of index values for options.
items:
format: int64
type: integer
type: array
x-go-name: OwnVotes
voted:
description: When called with a user token, has the authorized user voted?
type: boolean
x-go-name: Voted
voters_count:
description: How many unique accounts have voted on a multiple-choice poll.
Null if multiple is false.
format: int64
type: integer
x-go-name: VotersCount
votes_count:
description: How many votes have been received.
format: int64
type: integer
x-go-name: VotesCount
title: Poll represents a poll attached to a status.
type: object
x-go-name: Poll
x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/model
pollOptions:
properties:
title:
description: The text value of the poll option. String.
type: string
x-go-name: Title
votes_count:
description: The number of received votes for this option. Number, or null
if results are not published yet.
format: int64
type: integer
x-go-name: VotesCount
title: PollOptions represents the current vote counts for different poll options.
type: object
x-go-name: PollOptions
x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/model
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/status'
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 represents a status or post.
type: object
x-go-name: Status
x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/model
statusVisibility:
title: Visibility denotes the visibility of a status to other users.
type: string
x-go-name: Visibility
x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/model
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
host: example.org
info:
contact:
email: admin@gotosocial.org
name: GoToSocial Authors
description: GoToSocial Swagger documentation.
license:
name: AGPL3
url: https://www.gnu.org/licenses/agpl-3.0.en.html
title: GoToSocial
version: 0.1.0-SNAPSHOT
paths:
/api/v1/accounts:
post:
consumes:
- application/json
- application/xml
- application/x-www-form-urlencoded
- multipart/form-data
operationId: accountCreate
parameters:
- in: body
name: Account Create Request
schema:
$ref: '#/definitions/accountCreateRequest'
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:
operationId: accountFollow
parameters:
- description: The id of the account to follow.
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: Follow account with id.
tags:
- accounts
/api/v1/accounts/{id}/followers:
get:
operationId: accountFollowers
parameters:
- description: Account ID.
in: path
name: id
required: true
type: string
produces:
- application/json
responses:
"200":
description: Array of accounts that follow this account.
schema:
items:
$ref: '#/definitions/account'
type: array
"400":
description: bad request
"401":
description: unauthorized
"404":
description: not found
security:
- OAuth2 Bearer:
- read:accounts
summary: See followers of account with given id.
tags:
- accounts
/api/v1/accounts/{id}/following:
get:
operationId: accountFollowing
parameters:
- description: Account ID.
in: path
name: id
required: true
type: string
produces:
- application/json
responses:
"200":
description: Array of accounts that are followed by this account.
schema:
items:
$ref: '#/definitions/account'
type: array
"400":
description: bad request
"401":
description: unauthorized
"404":
description: not found
security:
- OAuth2 Bearer:
- read:accounts
summary: See accounts followed by given account id.
tags:
- accounts
/api/v1/accounts/{id}/statuses:
get:
description: The statuses will be returned in descending chronological order
(newest first), with sequential IDs (bigger = newer).
operationId: accountStatuses
parameters:
- description: Account ID.
in: path
name: id
required: true
type: string
- default: 30
description: Number of statuses to return.
in: query
name: limit
type: integer
- default: false
description: Exclude statuses that are a reply to another status.
in: query
name: exclude_replies
type: boolean
- description: |-
Return only statuses *OLDER* than the given max status ID.
The status with the specified ID will not be included in the response.
in: query
name: max_id
type: string
- default: false
description: Show only pinned statuses. In other words,e xclude statuses that
are not pinned to the given account ID.
in: query
name: pinned_only
type: boolean
- default: false
description: Show only statuses with media attachments.
in: query
name: media_only
type: boolean
produces:
- application/json
responses:
"200":
description: Array of statuses..
schema:
items:
$ref: '#/definitions/status'
type: array
"400":
description: bad request
"401":
description: unauthorized
"404":
description: not found
security:
- OAuth2 Bearer:
- read:accounts
summary: See statuses posted by the requested account.
tags:
- accounts
/api/v1/accounts/{id}/unblock:
post:
operationId: accountUnblock
parameters:
- description: The id of the account to unblock.
in: path
name: id
required: true
type: string
produces:
- application/json
responses:
"200":
description: Your relationship to this account.
schema:
$ref: '#/definitions/accountRelationship'
"400":
description: bad request
"401":
description: unauthorized
"404":
description: not found
security:
- OAuth2 Bearer:
- write:blocks
summary: Unblock account with ID.
tags:
- accounts
/api/v1/accounts/{id}/unfollow:
post:
operationId: accountUnfollow
parameters:
- description: The id of the account to unfollow.
in: path
name: id
required: true
type: string
produces:
- application/json
responses:
"200":
description: Your relationship to this account.
schema:
$ref: '#/definitions/accountRelationship'
"400":
description: bad request
"401":
description: unauthorized
"404":
description: not found
security:
- OAuth2 Bearer:
- write:follows
summary: Unfollow account with id.
tags:
- accounts
/api/v1/accounts/relationships:
get:
operationId: accountRelationships
parameters:
- description: Account IDs.
in: query
items:
type: string
name: id
required: true
type: array
produces:
- application/json
responses:
"200":
description: Array of account relationships.
schema:
items:
$ref: '#/definitions/accountRelationship'
type: array
"400":
description: bad request
"401":
description: unauthorized
"404":
description: not found
security:
- OAuth2 Bearer:
- read:accounts
summary: See your account's relationships with the given account IDs.
tags:
- accounts
/api/v1/accounts/update_credentials:
patch:
consumes:
- multipart/form-data
operationId: accountUpdate
parameters:
- description: Account should be made discoverable and shown in the profile
directory (if enabled).
in: formData
name: discoverable
type: boolean
- description: Account is flagged as a bot.
in: formData
name: bot
type: boolean
- description: The display name to use for the account.
in: formData
name: display_name
type: string
- description: Bio/description of this account.
in: formData
name: note
type: string
- description: Avatar of the user.
in: formData
name: avatar
type: file
- description: Header of the user.
in: formData
name: header
type: file
- description: Require manual approval of follow requests.
in: formData
name: locked
type: boolean
- description: Default post privacy for authored statuses.
in: formData
name: source.privacy
type: string
- description: Mark authored statuses as sensitive by default.
in: formData
name: source.sensitive
type: boolean
- description: Default language to use for authored statuses (ISO 6391).
in: formData
name: source.language
type: string
produces:
- application/json
responses:
"200":
description: The newly updated account.
schema:
$ref: '#/definitions/account'
"400":
description: bad request
"401":
description: unauthorized
security:
- OAuth2 Bearer:
- write:accounts
summary: Update your account.
tags:
- accounts
/api/v1/accounts/verify_credentials:
get:
operationId: accountVerify
produces:
- application/json
responses:
"200":
description: ""
schema:
$ref: '#/definitions/account'
"400":
description: bad request
"401":
description: unauthorized
"404":
description: not found
security:
- OAuth2 Bearer:
- read:accounts
summary: Verify a token by returning account details pertaining to it.
tags:
- accounts
/api/v1/admin/custom_emojis:
post:
consumes:
- multipart/form-data
operationId: emojiCreate
parameters:
- description: |-
The code to use for the emoji, which will be used by instance denizens to select it.
This must be unique on the instance.
example: blobcat_uwu
in: formData
name: shortcode
pattern: \w{2,30}
type: string
- description: A jpeg, png, or gif image of the emoji.
in: formData
name: domains
type: file
produces:
- application/json
responses:
"200":
description: The newly-created emoji.
schema:
$ref: '#/definitions/emoji'
"400":
description: bad request
"403":
description: forbidden
security:
- OAuth2 Bearer:
- admin
summary: Upload and create a new instance emoji.
tags:
- admin
/api/v1/admin/domain_blocks:
get:
operationId: domainBlocksGet
parameters:
- description: |-
If set to true, then each entry in the returned list of domain blocks will only consist of
the fields 'domain' and 'public_comment'. This is perfect for when you want to save and share
a list of all the domains you have blocked on your instance, so that someone else can easily import them,
but you don't need them to see the database IDs of your blocks, or private comments etc.
in: query
name: export
type: boolean
produces:
- application/json
responses:
"200":
description: All domain blocks currently in place.
schema:
items:
$ref: '#/definitions/domainBlock'
type: array
"400":
description: bad request
"403":
description: forbidden
"404":
description: not found
security:
- OAuth2 Bearer:
- admin
summary: View all domain blocks currently in place.
tags:
- admin
patch:
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.
example: example.org
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.
example: harassment, transphobia
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.
example: harassment, transphobia, and some stuff only other admins need to
know about
in: formData
name: private_comment
type: string
produces:
- application/json
responses:
"200":
description: "The newly created domain block, if import != true.\nNote that
if a list has been imported, then an `array` of\nnewly 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
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
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
tokenUrl: https://example.org/oauth/token
type: oauth2
swagger: "2.0"