OpenAPI / Swagger Mastodon API Specification

mastodon.yml

swagger: '2.0'
info:
  title: Mastodon API
  description: API for GNU Social-compatible microblogging server 
  version: '1.1.1'
  contact:
    name: Mastodon API Team
    url: https://github.com/tootsuite/mastodon
  license:
    name: AGPL
    url: https://github.com/tootsuite/mastodon/blob/master/LICENSE
    
# the domain of the service
host: mastodon.cx
# array of all schemes that your API supports
schemes:
  - https
# will be prefixed to all paths
basePath: /api/v1
produces:
  - application/json

paths:

# ---------------------------------------------------------------------------------------------------------

  /accounts/{id}:
    get:
      operationId: getAccount
      summary: Fetching an account
      description: Returns an Account with the given id.
      
      parameters:
        - name: id
          type: integer
          in: path
          required: true
          
      responses:
        200:
          description: OK
          schema:
            $ref: '#/definitions/Account'
        default:
          description: unexpected error
          schema:
            $ref: '#/definitions/Error'
            
  /account/{id}/followers:
    get:
      operationId: getAccountFollowers
      summary: Getting an account's followers
      description: Returns an array of Account
      
      parameters:
        - name: id
          type: integer
          in: path
          required: true
          
      responses:
        200:
          description: OK
          schema:
            type: array
            items: 
              $ref: '#/definitions/Account'
        default:
          description: unexpected error
          schema:
            $ref: '#/definitions/Error'
            
  /account/{id}/following:
    get:
      operationId: getAccountFollowing
      summary: Getting who account is following
      description: Returns an array of Account
      
      parameters:
        - name: id
          type: integer
          in: path
          required: true
          
      responses:
        200:
          description: OK
          schema:
            type: array
            items: 
              $ref: '#/definitions/Account'
        default:
          description: unexpected error
          schema:
            $ref: '#/definitions/Error'
            
  /account/{id}/statuses:
    get:
      operationId: getStatus
      summary: Getting who account is following
      description: Returns an array of Status
      
      parameters:
        - name: id
          type: integer
          in: path
          required: true
        - name: only_media
          type: string
          in: query
          description: 'Only return statuses that have media attachments'
          required: false
        - name: exclude_replies
          type: string
          in: query
          description: 'Skip statuses that reply to other statuses'
          required: false
          
      responses:
        200:
          description: OK
          schema:
            type: array
            items: 
              $ref: '#/definitions/Account'
        default:
          description: unexpected error
          schema:
            $ref: '#/definitions/Error'       
            
  /accounts/verify_credentials:
    get:
      operationId: getCurrentAccount
      summary: Getting the current user
      description: Returns the authenticated user's account.
      
      responses:
        200:
          description: OK
          schema:
            $ref: '#/definitions/Account'
        default:
          description: unexpected error
          schema:
            $ref: '#/definitions/Error'
            
  /accounts/update_credentials:
    patch:
      operationId: updateUserDetails
      summary: Updating the current user
      description: Updates the current user attributes using the given payload
      
      parameters:
        - name: display_name
          type: string
          in: query
          description: The name to display in the user's profile
          required: false
        - name: note
          type: string
          in: query
          description: A new biography for the user
          required: false
        - name: avatar
          type: string
          in: query
          description: A base64 encoded image to display as the user's avatar (e.g. `data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAUoAAADrCAYAAAA...`)
          required: false
        - name: header
          type: string
          in: query
          description: A base64 encoded image to display as the user's header image (e.g. `data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAUoAAADrCAYAAAA...`)
          required: false
          
      responses:
        200:
          description: OK
          schema:
            $ref: '#/definitions/Account'
        default:
          description: unexpected error
          schema:
            $ref: '#/definitions/Error'

# ---------------------------------------------------------------------------------------------------------

definitions:
  Error:
    description: Represents error message
    required:
      - error
    properties:
      error: 
        type: string
        description: A textual description of the error
        
  Account:
    description: Represents user account information.
    required:
      - id
    properties:
      id:
        type: integer
        description: The ID of the account
      username:
        type: string
        description: The username of the account
      acct:
        type: string
        description: Equals `username` for local users, includes `@domain` for remote ones
      display_name:
        type: string
        description: The account's display name
      note:
        type: string
        description: Biography of user
      url:
        type: string
        description: URL of the user's profile page (can be remote)
      avatar:
        type: string
        description: URL to the avatar image
      header:
        type: string
        description: URL to the header image
      locked:
        type: boolean
        description: Boolean for when the account cannot be followed without waiting for approval first
      created_at:
        type: integer
        description: The time the account was created
      followers_count:
        type: integer
        description: The number of followers for the account
        default: 0
      following_count:
        type: integer
        description: The number of accounts the given account is following
        default: 0
      statuses_count:
        type: integer
        description: The number of statuses the account has made
        default: 0
        
  Application:
    description: Represents external services connections.
    properties:
      name:
        type: string
        description: Name of the app
      website:
        type: string
        description: Homepage URL of the app
        
  Attachment:
    description: Represents atachment information for status.
    properties:
      id: 
        type: integer
        description: ID of the attachment
      type:
        type: string
        description: Attachment type
        enum:
          - image
          - video
          - gifv
      url:
        type: string
        description: URL of the locally hosted version of the image
      remote_url:
        type: string
        description: For remote images, the remote URL of the original image
      preview_url:
        type: string
        description: URL of the preview image
      text_url:
        type: string
        description: Shorter URL for the image, for insertion into text (only present on local images)