gotosocial/docs/api/swagger.yaml
Tobi Smethurst 58dddd86e0
Swagger (#124)
* start experimenting with swagger documentation

* further adventures in swagger

* do a few more api paths

* account paths documented

* go fmt

* fix up some models

* bit o lintin'
2021-07-31 17:49:59 +02:00

1476 lines
46 KiB
YAML

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
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"