owncast/openapi.yaml

openapi: 3.0.1
info:
  title: Owncast
  description: Owncast is a self-hosted live video and web chat server for use with existing popular broadcasting software. <br/><br/>Take note that only APIs listed specifically for external use, 3rd parties or for integration purposes are encouraged for external use. Internal APIs may change at any time and are used by the server and frontend itself.
  version: '0.1.0'
  contact:
    name: Gabe Kangas
    email: gabek@real-ity.com
    url: http://owncast.online
  x-logo:
    url: >-
      data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAIAAAACACAYAAADDPmHLAAAEvmlUWHRYTUw6Y29tLmFkb2JlLnhtcAAAAAAAPD94cGFja2V0IGJlZ2luPSLvu78iIGlkPSJXNU0wTXBDZWhpSHpyZVN6TlRjemtjOWQiPz4KPHg6eG1wbWV0YSB4bWxuczp4PSJhZG9iZTpuczptZXRhLyIgeDp4bXB0az0iWE1QIENvcmUgNS41LjAiPgogPHJkZjpSREYgeG1sbnM6cmRmPSJodHRwOi8vd3d3LnczLm9yZy8xOTk5LzAyLzIyLXJkZi1zeW50YXgtbnMjIj4KICA8cmRmOkRlc2NyaXB0aW9uIHJkZjphYm91dD0iIgogICAgeG1sbnM6ZXhpZj0iaHR0cDovL25zLmFkb2JlLmNvbS9leGlmLzEuMC8iCiAgICB4bWxuczp0aWZmPSJodHRwOi8vbnMuYWRvYmUuY29tL3RpZmYvMS4wLyIKICAgIHhtbG5zOnBob3Rvc2hvcD0iaHR0cDovL25zLmFkb2JlLmNvbS9waG90b3Nob3AvMS4wLyIKICAgIHhtbG5zOnhtcD0iaHR0cDovL25zLmFkb2JlLmNvbS94YXAvMS4wLyIKICAgIHhtbG5zOnhtcE1NPSJodHRwOi8vbnMuYWRvYmUuY29tL3hhcC8xLjAvbW0vIgogICAgeG1sbnM6c3RFdnQ9Imh0dHA6Ly9ucy5hZG9iZS5jb20veGFwLzEuMC9zVHlwZS9SZXNvdXJjZUV2ZW50IyIKICAgZXhpZjpQaXhlbFhEaW1lbnNpb249IjEyOCIKICAgZXhpZjpQaXhlbFlEaW1lbnNpb249IjEyOCIKICAgZXhpZjpDb2xvclNwYWNlPSIxIgogICB0aWZmOkltYWdlV2lkdGg9IjEyOCIKICAgdGlmZjpJbWFnZUxlbmd0aD0iMTI4IgogICB0aWZmOlJlc29sdXRpb25Vbml0PSIyIgogICB0aWZmOlhSZXNvbHV0aW9uPSI5Ni4wIgogICB0aWZmOllSZXNvbHV0aW9uPSI5Ni4wIgogICBwaG90b3Nob3A6Q29sb3JNb2RlPSIzIgogICBwaG90b3Nob3A6SUNDUHJvZmlsZT0ic1JHQiBJRUM2MTk2Ni0yLjEiCiAgIHhtcDpNb2RpZnlEYXRlPSIyMDIwLTA2LTE4VDAwOjQ2OjEyLTA3OjAwIgogICB4bXA6TWV0YWRhdGFEYXRlPSIyMDIwLTA2LTE4VDAwOjQ2OjEyLTA3OjAwIj4KICAgPHhtcE1NOkhpc3Rvcnk+CiAgICA8cmRmOlNlcT4KICAgICA8cmRmOmxpCiAgICAgIHN0RXZ0OmFjdGlvbj0icHJvZHVjZWQiCiAgICAgIHN0RXZ0OnNvZnR3YXJlQWdlbnQ9IkFmZmluaXR5IERlc2lnbmVyIChNYXIgMzEgMjAyMCkiCiAgICAgIHN0RXZ0OndoZW49IjIwMjAtMDYtMThUMDA6NDY6MTItMDc6MDAiLz4KICAgIDwvcmRmOlNlcT4KICAgPC94bXBNTTpIaXN0b3J5PgogIDwvcmRmOkRlc2NyaXB0aW9uPgogPC9yZGY6UkRGPgo8L3g6eG1wbWV0YT4KPD94cGFja2V0IGVuZD0iciI/Pn6jclUAAAGCaUNDUHNSR0IgSUVDNjE5NjYtMi4xAAAokXWRzytEURTHPzODESPCwsLipWE15EdNbJSZNNSkaYwy2Mw880PNj9d7I8lW2SpKbPxa8BewVdZKESlZWVgTG/ScZ6Zmkjm3c8/nfu89p3vPBXsko2aNmn7I5gp6OOBTZqNzivOZOlpx0oESUw1tLBQKUtU+7rBZ8abXqlX93L/WuJgwVLDVC4+qml4QnhAOrhQ0i7eF29V0bFH4VNijywWFby09XuQXi1NF/rJYj4T9YG8RVlIVHK9gNa1nheXluLOZZbV0H+slrkRuZlpil3gnBmEC+FCYZBw/XgYYkdlLL4P0yYoq+f2/+VPkJVeVWWMVnSVSpCngEXVZqickJkVPyMiwavX/b1+N5NBgsbrLB7VPpvnWDc4t+N40zc9D0/w+AscjXOTK+fkDGH4XfbOsufeheR3OLstafAfON6DjQYvpsV/JIW5PJuH1BJqi0HYNDfPFnpX2Ob6HyJp81RXs7kGPnG9e+AEyv2fOZnRq6wAAAAlwSFlzAAAOxAAADsQBlSsOGwAAHBpJREFUeJztfXl8VEW69vO852QhYYcAIRsGRETZ3BURRXGcn5/bOKPOOPPduRevv9EZh3tdRp1x+bjM6FXGXcdt3HGDO7ij1w0XRnHBBTAoypJASEjYlyzdp+r9/ugEmqQ7fbrTnaQDz+9XhD6n6q23u556q+qtDdiP/diPfRfsbAU6Gx/fpz36ZeJiUM8EMAzEAADZADIBGADbAdRCdbW1mFdXL88eMZ07O1PnZGKfJcA395sCOJgmgisB9vKbThXbVfF3Nfr4oZc4S1OpY0dgnyPAkpuV2sc7WRx5kURuO0RZazDLqN444VK3MWkKdjD2KQJ8ebe6jmsegMNfAshKgkhVq8uMxRmH/dYtT4K8Dsc+Q4DF93m9BXyIDs5PunBFuXp69oTL3K+SLjvF2CcI8Pm9XhbJJ0mcl8JsKuxOjD/iD86WFOaRdLidrUBHQIFZUJynmtJsitEDLwKYnNJckoxubwE+uSt4CYX3ApAOyM5aq78/ZnrGfR2QV1LQrQnw/h1eYabgGxK9OzDbOmtQeNx/umnRFHTbJuDD24MZQl1glb2RWtPfEjmATgPw1w7NNUF0hFnsFFiLi6xyuFWgwwN4w/uzgh1pdRJGt7QA784yBaC5z2qnNXG9VDgBwPudlL9vdEsCKM1lBmQHm/69dVA7FfsJ0PF4878bR1rldHZi4QOAgqcDuK5ztYiNbtcHUPLfVTXbqqKTw9hXbmzo2dm/Ryx0Kwsw50Z1rQYv7mw9miDM5kgAX3S2Im2hWxGgR3bwcgPt6GFfVKjaodhPgI6DVf1FZ+sQDlUO6GwdYqHbEGDOH+0gq8ExXaX2A4CiQz2QCaHbEAAZjXdZZRfr1GqXd7V3CwI886eGbHVxqulsRVpCaTtbhVjoFgQIKAZkqfbpSuYfAAit62wdYqFbEMDJ0EuMwulsPVpB0eVXD6c9Ae6+fHumAX6TqOfPGsAYQA1grUIt0HLhCAlQQkGEEAdwHPiYTNcNiWnVcUh7AuTkOMUWOqAt868aKmhrgWCjorEOCDQogoFQwScEAhlZQFY2kdkDyOxBiADihAgDANagKkHpHYa0J4ASw02kwlegfqdi145QQTcToBXaMW4wAaAhoMB2gNCQhXCAzCwgpxdMrpO1JnHpHYO0J4BRPaX5/8FGoKFO0VAfquGt1gCmelCmADwg4AE7d7Lsz89mBFKcY7uR9gQIGJwaaFDs2KoIdvT2jDYJZRd1lBrtQVoT4PLzt/WrWqdjdtd0n+ZcFQECj0J1IYB6BU6h8NcAeiRLN1V8lCxZqURaE0AcHGKgjMO0e7CYoca5f9ZzuZvCns+74hfbb3Cov4TwLwBy2qubiv2uvTI6AmlNABWMtv4Lvw5WfvPXp3s+Fenlbc/03gjgzssv3L5IHLyDdpBAQ/+sSjR9R6KL+c7jgzp6iKXCT/BUb/zr7MiFH47bn+69yBhztqWqX9kRwne3ze7b5X0AQJpbAAMe6Mv8q75sa/vc7luu4D1C14EsSkgxq7MSStcJSGsLYEVHKENzbtGCJRqt8vp73vA/MXP3U/2Clrg3luwoIaiC11L5vZOJtCXA+ecZscQBhoq2goU+cM+TfZbEK7+xUR6OJTtK2GVpN6fiO6cCaUuAXjnbhlvCtaFaHj2oPpKI/Iee7b3FEttjym8ZgAfufax/l3cANSNt+wB0dKSNMQOkiiWeeN8kmoel7kJ8q3oaxGTdkmh+nYG0JQDIEbGGgAr5/aOP5CW8KCOOIWYzvnnw8ZytiebXGUhbAnjUIrZRQATqAPN1e/Iw0Ky45g+Us9uTX2cgYQLMuP760szMzCtF5DQ
servers: []
tags:
  - name: Admin
    description: Admin operations requiring authentication.
  - name: Chat
    description: Endpoints related to the chat interface.
  - name: Integrations
    description: APIs built to allow 3rd parties to interact with an Owncast server.
  - name: Moderation
    description: Chat-related actions that can take place by a moderator.

components:
  schemas:
    ClientArray:
      type: array
      items:
        $ref: '#/components/schemas/Client'

    UserArray:
      type: array
      items:
        $ref: '#/components/schemas/User'

    LogEntryArray:
      type: array
      items:
        $ref: '#/components/schemas/LogEntry'

    FollowerArray:
      type: array
      items:
        $ref: '#/components/schemas/Follower'

    StreamKeyArray:
      type: array
      items:
        $ref: '#/components/schemas/StreamKey'

    ChatMessageArray:
      type: array
      items:
        $ref: '#/components/schemas/ChatMessage'

    Client:
      type: object
      description: A single representation of a client.
      example:
        connectedAt: '2020-10-06T23:20:44.588649-07:00'
        messageCount: 0
        userAgent: >-
          Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_5) AppleWebKit/537.36
          (KHTML, like Gecko) Chrome/84.0.4147.89 Safari/537.36
        ipAddress: '::1'
        clientID: 2ba20dd34f911c198df3218ddc64c740
        geo:
          countryCode: US
          regionName: California
          timeZone: America/Los_Angeles
      properties:
        connectedAt:
          type: string
          format: date-time
        messageCount:
          description: Number of chat messages sent by user
          type: integer
        userAgent:
          description: The web client used to connect to this server
          type: string
          example: 'Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/91.0.4472.124 Safari/537.36'
        ipAddress:
          description: The public IP address of this client
          type: string
        clientID:
          description: The value used to identify this client
          type: string
        geo:
          type: object
          description: Optional geographic data for the client
          properties:
            countryCode:
              type: string
            regionName:
              type: string
            timeZone:
              type: string
        user:
          $ref: '#/components/schemas/User'
      x-last-modified: 1602052347511

    BasicResponse:
      type: object
      properties:
        success:
          type: boolean
        message:
          type: string

    InstanceDetails:
      type: object
      description: User-facing details about this server.
      properties:
        name:
          type: string
          description: Displayed as the header in the instance details.
        summary:
          type: string
          description: This is brief summary of whom you are or what the stream is.
        logo:
          type: string
          description: Local file name of your logo image. We recommend a square image (150 x 150px) with ample padding around the important contents of the image, as it will be rendered as a circle.
        tags:
          type: array
          description: Categories of the content this instance focuses on.
          items:
            type: string
        socialHandles:
          type: array
          description: Links to social network urls.
          items:
            type: object
            properties:
              platform:
                type: string
                example: github
              url:
                type: string
                example: http://github.com/owncast/owncast
        extraPageContent:
          type: string
          description: Additional HTML content to render in the body of the web interface.
          example: '<p>This page is <strong>super</strong> cool!'
        version:
          type: string
          example: Owncast v0.0.3-macOS (ef3796a033b32a312ebf5b334851cbf9959e7ecb)

    YP:
      type: object
      description: Configuration of the instance's registration to the Owncast Directory (YP API)
      properties:
        enabled:
          type: boolean
          description: If YP support is on or off.  Must be enabled to show in the directory.
          default: false
        instanceUrl:
          type: string
          description: The public URL of this owncast server, used for registration and linking with the directory.  Must be publicly available.

    S3:
      type: object
      description: Configuration of external storage using S3-compatible providers.
      properties:
        enabled:
          type: boolean
        endpoint:
          type: string
        servingEndpoint:
          type: string
        accessKey:
          type: string
        secret:
          type: string
        bucket:
          type: string
        region:
          type: string
        acl:
          type: string
        forcePathStyle:
          type: boolean
      required:
        - enabled
    StreamQuality:
      type: object
      properties:
        videoPassthrough:
          type: boolean
          description: If enabled video transcoding is disabled and the video is passed along in its original format.
        audioPassthrough:
          type: boolean
          description: If enabled audio transcoding is disabled and the audio is passed along in its original format.
        videoBitrate:
          type: integer
          description: The video quality, in kbps.
        audioBitrate:
          type: integer
          description: The audio quality, in kbps.
        scaledWidth:
          type: integer
          description: The resized video width.
        scaledHeight:
          type: integer
          description: The resized video height.
        framerate:
          type: integer
          description: The target frames per second of the video.
        cpuUsageLevel:
          type: integer
          description: 'The amount of hardware utilization selected for this HLS variant.'

    TimestampedValue:
      type: object
      properties:
        time:
          type: string
          format: date-time
        value:
          type: integer

    ConfigValue:
      description: A wrapper object used to set values in many config endpoints.
      type: object
      properties:
        value:
          oneOf:
            - type: string
            - type: integer
            - type: object
            - type: boolean

    BooleanValue:
      description: A wrapper object used to set boolean values in many config endpoints.
      type: object
      properties:
        value:
          type: boolean
      example:
        value: true

    LogEntry:
      type: object
      properties:
        time:
          type: string
          format: date-time
          description: 'Timestamp for this log entry'
        level:
          type: string
          description: 'The level of this log entry'
        message:
          type: string
          description: 'The log entry contents'

    Webhook:
      type: object
      properties:
        id:
          type: string
          description: The ID of this webhook.
        url:
          type: string
          description: The URL that events will be sent to.
        events:
          type: array
          items:
            type: string
            description: The events that will be sent to this webhook.
        timestamp:
          type: string
          format: date-time
          description: When this webhook was created.
        lastUsed:
          type: string
          format: date-time
          description: When this webhook was last used.

    User:
      type: object
      properties:
        id:
          type: string
          description: User ID
          example: yklw5Imng
        displayName:
          type: string
          description: The user-facing disaplay name for this user.
          example: awesome-pizza
        displayColor:
          type: integer
          description: Color name number for client rendering.  theme-user-colors-n
          example: 3
        createdAt:
          type: string
          format: date-time
          description: When this account was originally registered/created.
        previousNames:
          type: string
          description: Comma separated list of names previously used by this user.
          example: 'awesome-pizza,user42'
        scopes:
          type: array
          items:
            description: A specific attribute assigned to this user
            type: string
            example: 'MODERATOR'

    Follower:
      type: object
      required:
        - link
        - username
        - timestamp
      properties:
        link:
          type: string
          description: URL linking to this follower
          example: https://mastodon.cloud/users/gabektest
        name:
          type: string
          description: Optional display name for this follower
          example: John Smith
        image:
          type: string
          description: Optional image for this follower
          example: http://mastodon.cloud/users/gabektest/avatar.png
        timestamp:
          type: string
          format: date-time
          description: Timestamp of when the follow occurred
        disabledAt:
          type: string
          format: date-time
          description: Timestamp when the follow was removed

    FederatedAction:
      type: object
      properties:
        iri:
          type: string
          description: The unique identifier for this action.
          example: https://fediverse.server/jfk-3827
        actorIRI:
          type: string
          description: The identifier for the actor that performed this action.
          example: https://mastodon.cloud/users/gabektest
        type:
          type: string
          enum:
            [
              FEDIVERSE_ENGAGEMENT_FOLLOW,
              FEDIVERSE_ENGAGEMENT_LIKE,
              FEDIVERSE_ENGAGEMENT_REPOST,
            ]

    StreamKey:
      type: object
      properties:
        id:
          type: string
          description: The key used for authing a stream.
          example: yklw5Imng
        comment:
          type: string
          description: The user-facing description or explanation of this single key
          example: Used by Tim.

    ChatMessage:
      type: array
      items:
        type: object
        properties:
          user:
            $ref: '#/components/schemas/User'
            body:
              type: string
              description: Escaped HTML of the chat message content.
            id:
              type: string
              description: Unique ID of the chat message.
            visible:
              type: boolean
              description: 'Should chat message be visibly rendered.'
            timestamp:
              type: string
              format: date-time

  securitySchemes:
    AdminBasicAuth:
      type: http
      scheme: basic
      description: The username for admin basic auth is `admin`. Defaults to abc123.
    AccessToken:
      type: http
      scheme: bearer
      description: 3rd party integration auth where a service user must provide an access token.
    UserToken:
      type: apiKey
      name: accessToken
      in: query
      description: A standard user must provide a valid access token.
    ModeratorUserToken:
      type: apiKey
      name: accessToken
      in: query
      description: A moderator user must provide a valid access token.

  responses:
    UsersResponse:
      description: A collection of users.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/UserArray'

    FollowersResponse:
      description: A collection of users.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/FollowerArray'

    ClientsResponse:
      description: Successful response of an array of clients
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ClientArray'
          example:
            - connectedAt: '2020-10-06T23:20:44.588649-07:00'
              messageCount: 3
              userAgent: >-
                Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_5) AppleWebKit/537.36
                (KHTML, like Gecko) Chrome/84.0.4147.89 Safari/537.36
              ipAddress: '172.217.164.110'
              geo:
                countryCode: US
                regionName: California
                timeZone: America/Los_Angeles
              user:
                id: yklw5Imng
                displayName: awesome-pizza
                displayColor: 42
                createdAt: '2021-07-08T20:21:25.303402404-07:00'
                previousNames: 'awesome-pizza,coolPerson23'

    LogsResponse:
      description: Response of server log entries
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/LogEntryArray'
          examples:
            success:
              summary: Logs returned
              value:
                [
                  {
                    'message': 'Owncast v0.0.0-localdev (unknown)',
                    'level': 'info',
                    'time': '2020-10-29T18:35:34.422386-07:00',
                  },
                  {
                    'message': 'Web server running on port: 8080',
                    'level': 'info',
                    'time': '2020-10-29T18:35:35.011731-07:00',
                  },
                  {
                    'message': 'RTMP server is listening for incoming stream on port: 1935',
                    'level': 'info',
                    'time': '2020-10-29T18:35:35.011823-07:00',
                  },
                ]

    BasicResponse:
      description: Operation Success/Failure Response
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/BasicResponse'
          examples:
            success:
              summary: Operation succeeded.
              value:
                {
                  'success': true,
                  'message': 'context specific success message',
                }
            failure:
              summary: Operation failed.
              value:
                {
                  'success': false,
                  'message': 'context specific failure message',
                }

paths:
  /api/config:
    get:
      summary: Information
      description: The client configuration. Information useful for the user interface.
      tags: ['Server']
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InstanceDetails'

  /api/ping:
    get:
      summary: Mark the current viewer as active.
      description: For tracking viewer count, periodically hit the ping endpoint.
      tags: ['Server']
      responses:
        '200':
          description: 'Successful ping'

  /api/status:
    get:
      summary: Current Status
      description: This endpoint is used to discover when a server is broadcasting, the number of active viewers as well as other useful information for updating the user interface.
      tags: ['Server']
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  lastConnectTime:
                    type: string
                    nullable: true
                    format: date-time
                  overallMaxViewerCount:
                    type: integer
                  sessionMaxViewerCount:
                    type: integer
                  online:
                    type: boolean
                  viewerCount:
                    type: integer
                  lastDisconnectTime:
                    type: string
                    nullable: true
                    format: date-time
              examples:
                online:
                  value:
                    lastConnectTime: '2020-10-03T21:36:22-05:00'
                    lastDisconnectTime: null
                    online: true
                    overallMaxViewerCount: 420
                    sessionMaxViewerCount: 12
                    viewerCount: 7

  /api/customjavascript:
    get:
      summary: Custom Javascript to execute.
      description: Returns custom Javascript that was set in the Owncast admin to be run in the Owncast frontend.
      tags: ['Server']
      responses:
        '200':
          description: ''
          content:
            application/javascript:
              schema:
                type: string
              example: console.log("Hello World");

  /api/chat/register:
    post:
      summary: Register a chat user
      description: Register a user that returns an access token for accessing chat.
      tags: ['Chat']
      security:
        - UserToken: []
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                displayName:
                  type: string
                  description: Optionally provide a display name you want to assign to this user when registering.
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    description: The new user's id.
                  accessToken:
                    type: string
                    description: The access token used for accessing chat.
                  displayName:
                    type: string
                    description: The user-facing name displayed for this user.

  /api/chat:
    get:
      summary: Chat Messages Backlog
      description: Used to get chat messages prior to connecting to the websocket.
      tags: ['Chat']
      security:
        - UserToken: []
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChatMessageArray'

  /api/yp:
    get:
      summary: Yellow Pages Information
      description: Information to be used in the Yellow Pages service, a global directory of Owncast servers.
      tags: ['Server']
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  name:
                    type: string
                  description:
                    type: string
                  logo:
                    type: string
                  nsfw:
                    type: boolean
                  tags:
                    type: array
                    items:
                      type: string
                  online:
                    type: boolean
                  viewerCount:
                    type: integer
                  overallMaxViewerCount:
                    type: integer
                  sessionMaxViewerCount:
                    type: integer
                  lastConnectTime:
                    type: string
                    nullable: true
                    format: date-time

  /img/emoji/:
    get:
      parameters:
        - name: name
          in: path
          description: Emoji image name
          required: true
          schema:
            type: string
          example: test.svg
      summary: Get Emoji Image
      description: Get an emoji image.
      tags: ['Chat']
      responses:
        '200':
          description: 'Returns a single image'

  /api/emoji:
    get:
      summary: Get Custom Emoji
      description: Get a list of custom emoji that are supported in chat.
      tags: ['Chat']
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    name:
                      type: string
                      description: The name of the Emoji
                    emoji:
                      type: string
                      description: The relative path to the Emoji image file
              examples:
                default:
                  value:
                    items:
                      - name: nicolas_cage_party
                        emoji: /img/emoji/nicolas_cage_party.gif
                      - name: parrot
                        emoji: /img/emoji/parrot.gif

  /api/followers:
    get:
      summary: Get the public followers of this instance
      responses:
        '200':
          description: Followers
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Follower'

  /api/remotefollow:
    post:
      summary: Return the information needed to redirect a user to a fediverse server to perform a remote follow action.
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                account:
                  description: The fediverse username@server.tld account that wants to perform the remote follow action.
                  type: string
                  example: johnsmith@fediverse.biz
      responses:
        '200':
          description: Remote follow redirect details
          content:
            application/json:
              schema:
                type: object
                properties:
                  redirectUrl:
                    description: The URL the frontend should redirect to
                    type: string
                    example: https://fediverse.biz/authorize_interaction?uri=https://my.owncast.server/federation/user/streamer

  /api/chat/messagevisibility:
    post:
      summary: Update the visibility of chat messages.
      description: Pass an array of IDs you want to change the chat visibility of.
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                visible:
                  type: boolean
                  description: Are these messages visible.
                idArray:
                  type: array
                  items:
                    type: string
                    description: IDs of the chat messages you wish to change the visibility of.
      tags: ['Moderation']
      security:
        - ModeratorUserToken: []
      responses:
        '200':
          $ref: '#/components/responses/BasicResponse'

  /api/chat/users/setenabled:
    post:
      summary: Disable (block) or re-enable a chat user.
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                userId:
                  type: string
                  description: User ID of the chat user you're changing.
                enabled:
                  type: boolean
                  description: State of this user. False to block/disable.
      tags: ['Moderation']
      security:
        - ModeratorUserToken: []
      responses:
        '200':
          $ref: '#/components/responses/BasicResponse'

  /api/admin/status:
    get:
      summary: 'Server status and broadcaster'
      tags: ['Admin']
      security:
        - AdminBasicAuth: []
      responses:
        '200':
          description: Server status and broadcaster details
          content:
            application/json:
              schema:
                type: object
                properties:
                  broadcaster:
                    type: object
                    properties:
                      remoteAddr:
                        type: string
                      time:
                        type: string
                        format: date-time
                      streamDetails:
                        type: object
                        properties:
                          width:
                            type: integer
                          height:
                            type: integer
                          frameRate:
                            type: integer
                          videoBitrate:
                            type: integer
                          videoCodec:
                            type: string
                          audioBitrate:
                            type: integer
                          audioCodec:
                            type: string
                          encoder:
                            type: string
                  online:
                    type: boolean
                    description: Is a stream currently active
                  viewerCount:
                    type: integer
                    description: The current number of viewers
                  sessionPeakViewerCount:
                    type: integer
                    description: The peak number of viewers this streaming session
                  overallPeakViewerCount:
                    type: integer
                    description: The all-time peak number of viewers
                  versionNumber:
                    type: string
                    description: The current version of the owncast software
              examples:
                connected:
                  summary: 'Broadcaster Connected'
                  value:
                    broadcaster:
                      remoteAddr: 172.217.164.110
                      time: '2020-10-06T23:20:44.588649-07:00'
                      streamDetails:
                        width: 640
                        height: 480
                        frameRate: 24
                        videoBitrate: 1500
                        videoCodec: 'mp4a'
                        audioBitrate: 256
                        audioCodec: 'aac'
                        encoder: 'obs-output module (libobs version 25.0.8)'
                    online: true
                    viewerCount: 3
                    overallPeakViewerCount: 4
                    sessionPeakViewerCount: 4
                    versionNumber: '0.0.3'

  /api/admin/disconnect:
    post:
      summary: Disconnect Broadcaster
      description: Disconnect the active inbound stream, if one exists, and terminate the broadcast.
      tags: ['Admin']
      security:
        - AdminBasicAuth: []
      responses:
        '200':
          $ref: '#/components/responses/BasicResponse'

  /api/admin/yp/reset:
    post:
      summary: Reset your YP registration key.
      description: Used when there is a problem with your registration to the Owncast Directory via the YP APIs.  This will reset your local registration key.
      tags: ['Admin']
      security:
        - AdminBasicAuth: []
      responses:
        '200':
          $ref: '#/components/responses/BasicResponse'

  /api/admin/chat/clients:
    get:
      summary: Return a list of currently connected clients
      description: Return a list of currently connected clients with optional geo details.
      tags: ['Admin']
      security:
        - AdminBasicAuth: []
      responses:
        '200':
          $ref: '#/components/responses/ClientsResponse'

  /api/admin/users/disabled:
    get:
      summary: Return a list of currently connected clients
      description: Return a list of currently connected clients with optional geo details.
      tags: ['Admin']
      security:
        - AdminBasicAuth: []
      responses:
        '200':
          $ref: '#/components/responses/UsersResponse'

  /api/admin/logs:
    get:
      summary: Return recent log entries
      description: Returns server logs.
      tags: ['Admin']
      security:
        - AdminBasicAuth: []
      responses:
        '200':
          $ref: '#/components/responses/LogsResponse'

  /api/admin/logs/warnings:
    get:
      summary: Return recent warning and error logs.
      description: Return recent warning and error logs.
      tags: ['Admin']
      security:
        - AdminBasicAuth: []
      responses:
        '200':
          $ref: '#/components/responses/LogsResponse'

  /api/admin/serverconfig:
    get:
      summary: Server Configuration
      description: Get the current configuration of the Owncast server.
      tags: ['Admin']
      security:
        - AdminBasicAuth: []
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  instanceDetails:
                    $ref: '#/components/schemas/InstanceDetails'
                  ffmpegPath:
                    type: string
                    description: The path to the copy of ffmpeg that this server is using.
                  webServerPort:
                    type: integer
                    description: The port the public web server is listening on.
                  rtmpServerPort:
                    type: integer
                    description: The port the inbound RTMP broadcast should be sent to.
                  s3:
                    $ref: '#/components/schemas/S3'
                  videoSettings:
                    type: object
                    description: How the different variants of video streams are configured.
                    properties:
                      videoQualityVariants:
                        type: array
                        items:
                          $ref: '#/components/schemas/StreamQuality'
                      latencyLevel:
                        type: integer
                        description: The level of latency selected for streaming.  Lower latency can create more buffering.
                  yp:
                    $ref: '#/components/schemas/YP'

  /api/admin/chat/messages:
    get:
      summary: Chat messages, unfiltered.
      description: Get a list of all chat messages with no filters applied.
      tags: ['Admin']
      security:
        - AdminBasicAuth: []
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    user:
                      $ref: '#/components/schemas/User'
                    body:
                      type: string
                      description: Escaped HTML of the chat message content.
                    id:
                      type: string
                      description: Unique ID of the chat message.
                    visible:
                      type: boolean
                      description: 'Should chat message be visibly rendered.'
                    timestamp:
                      type: string
                      format: date-time

  /api/admin/chat/messagevisibility:
    post:
      summary: Update the visibility of chat messages.
      description: Pass an array of IDs you want to change the chat visibility of.
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                visible:
                  type: boolean
                  description: Are these messages visible.
                idArray:
                  type: array
                  items:
                    type: string
                    description: IDs of the chat messages you wish to change the visibility of.
      tags: ['Admin']
      security:
        - AdminBasicAuth: []
      responses:
        '200':
          $ref: '#/components/responses/BasicResponse'

  /api/admin/chat/users/setenabled:
    post:
      summary: Enable or disable a single user.
      description: Enable or disable a single user. Disabling will also hide all the user's chat messages.
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                userId:
                  type: string
                  description: User ID to act upon.
                  example: 'yklw5Imng'
                enabled:
                  type: boolean
                  description: Set the enabled state of this user.
      tags: ['Admin']
      security:
        - AdminBasicAuth: []
      responses:
        '200':
          $ref: '#/components/responses/BasicResponse'

  /api/admin/config/adminpass:
    post:
      summary: Set the admin password.
      tags: ['Admin']
      security:
        - AdminBasicAuth: []
      responses:
        '200':
          $ref: '#/components/responses/BasicResponse'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ConfigValue'

  /api/admin/config/streamkeys:
    post:
      summary: Set the stream keys.
      tags: ['Admin']
      security:
        - AdminBasicAuth: []
      responses:
        '200':
          $ref: '#/components/responses/BasicResponse'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/StreamKeyArray'

  /api/admin/config/pagecontent:
    post:
      summary: Set the custom page content.
      description: Set the custom page content using markdown.
      tags: ['Admin']
      security:
        - AdminBasicAuth: []
      responses:
        '200':
          $ref: '#/components/responses/BasicResponse'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ConfigValue'
            example: '# Welcome to my cool server!<br><br>I _hope_ you enjoy it.'

  /api/admin/config/streamtitle:
    post:
      summary: Set the stream title.
      description: Set the title of the currently streaming content.
      tags: ['Admin']
      security:
        - AdminBasicAuth: []
      responses:
        '200':
          $ref: '#/components/responses/BasicResponse'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ConfigValue'
            example:
              value: Streaming my favorite game, Desert Bus.

  /api/admin/config/name:
    post:
      summary: Set the server name.
      description: Set the name associated with your server.  Often is your name, username or identity.
      tags: ['Admin']
      security:
        - AdminBasicAuth: []
      responses:
        '200':
          $ref: '#/components/responses/BasicResponse'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ConfigValue'

  /api/admin/config/serversummary:
    post:
      summary: Set the server summary.
      description: Set the summary of your server's streaming content.
      tags: ['Admin']
      security:
        - AdminBasicAuth: []
      responses:
        '200':
          $ref: '#/components/responses/BasicResponse'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ConfigValue'
            example:
              value: The best in Desert Bus Streaming

  /api/admin/config/offlinemessage:
    post:
      summary: Set the offline message.
      description: Set the message that is displayed when a stream is not live.
      tags: ['Admin']
      security:
        - AdminBasicAuth: []
      responses:
        '200':
          $ref: '#/components/responses/BasicResponse'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ConfigValue'
            example:
              value: Come back on Friday at 2pm, I'll be streaming then.

  /api/admin/config/logo:
    post:
      summary: Set the server logo.
      description: Set the logo for your server.  Path is relative to webroot.
      tags: ['Admin']
      security:
        - AdminBasicAuth: []
      responses:
        '200':
          $ref: '#/components/responses/BasicResponse'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ConfigValue'
            example:
              value: '/img/mylogo.png'

  /api/admin/config/tags:
    post:
      summary: Set the server tags.
      description: Set the tags displayed for your server and the categories you can show up in on the directory.
      tags: ['Admin']
      security:
        - AdminBasicAuth: []
      responses:
        '200':
          $ref: '#/components/responses/BasicResponse'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ConfigValue'
            example:
              value:
                - games
                - music
                - streaming

  /api/admin/config/ffmpegpath:
    post:
      summary: Set the ffmpeg binary path
      description: Set the path for a specific copy of ffmpeg on your system.
      tags: ['Admin']
      security:
        - AdminBasicAuth: []
      responses:
        '200':
          $ref: '#/components/responses/BasicResponse'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ConfigValue'
            example:
              value: '/home/owncast/ffmpeg'

  /api/admin/config/webserverport:
    post:
      summary: Set the owncast web port.
      description: Set the port the owncast web server should listen on.
      tags: ['Admin']
      security:
        - AdminBasicAuth: []
      responses:
        '200':
          $ref: '#/components/responses/BasicResponse'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ConfigValue'
            example:
              value: 8080

  /api/admin/config/rtmpserverport:
    post:
      summary: Set the inbound rtmp server port.
      description: Set the port where owncast service will listen for inbound broadcasts.
      tags: ['Admin']
      security:
        - AdminBasicAuth: []
      responses:
        '200':
          $ref: '#/components/responses/BasicResponse'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ConfigValue'
            example:
              value: 1935

  /api/admin/config/nsfw:
    post:
      summary: Mark if your stream is not safe for work
      description: Mark if your stream can be consitered not safe for work.  Used in different contexts, including the directory for filtering purposes.
      tags: ['Admin']
      security:
        - AdminBasicAuth: []
      responses:
        '200':
          $ref: '#/components/responses/BasicResponse'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ConfigValue'
            example:
              value: false

  /api/admin/config/directoryenabled:
    post:
      summary: Set if this server supports the Owncast directory.
      description: If set to true the server will attempt to register itself with the [Owncast Directory](https://directory.owncast.online).  Off by default.
      tags: ['Admin']
      security:
        - AdminBasicAuth: []
      responses:
        '200':
          $ref: '#/components/responses/BasicResponse'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ConfigValue'
            example:
              value: true

  /api/admin/config/serverurl:
    post:
      summary: Set the public url of this owncast server.
      description: Set the public url of this owncast server.  Used for the directory and optional integrations.
      tags: ['Admin']
      security:
        - AdminBasicAuth: []
      responses:
        '200':
          $ref: '#/components/responses/BasicResponse'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ConfigValue'
            example:
              value: https://live.mycoolserver.biz

  /api/admin/config/video/streamlatencylevel:
    post:
      summary: Set the latency level for the stream.
      description: Sets the latency level that determines how much video is buffered between the server and viewer.  Less latency can end up with more buffering.
      tags: ['Admin']
      security:
        - AdminBasicAuth: []
      responses:
        '200':
          $ref: '#/components/responses/BasicResponse'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                value:
                  description: The latency level
                  type: integer
              example:
                value: 4

  /api/admin/config/video/streamoutputvariants:
    post:
      summary: Set the configuration of your stream output.
      description: Sets the detailed configuration for all of the stream variants you support.
      tags: ['Admin']
      security:
        - AdminBasicAuth: []
      responses:
        '200':
          $ref: '#/components/responses/BasicResponse'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ConfigValue'
            example:
              value:
                - framerate: 30
                  videoPassthrough: false
                  videoBitrate: 1800
                  cpuUsageLevel: 2
                  audioPassthrough: true
                - framerate: 24
                  videoPassthrough: false
                  videoBitrate: 1000
                  cpuUsageLevel: 3
                  audioPassthrough: true

  /api/admin/config/video/codec:
    post:
      summary: Set the video codec.
      description: Sets the specific video codec that will be used for video encoding. Some codecs will support hardware acceleration. Not all codecs will be supported for all systems.
      tags: ['Admin']
      security:
        - AdminBasicAuth: []
      responses:
        '200':
          $ref: '#/components/responses/BasicResponse'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                value:
                  description: The video codec to change to.
                  type: string
              example:
                value: libx264

  /api/admin/config/s3:
    post:
      summary: Set your storage configuration.
      description: Sets your S3 storage provider configuration details to enable external storage.
      tags: ['Admin']
      security:
        - AdminBasicAuth: []
      responses:
        '200':
          $ref: '#/components/responses/BasicResponse'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ConfigValue'
            example:
              value:
                enabled: true
                endpoint: https://s3.us-west-000.backblazeb2.com
                accessKey: e1ac500y7000500047156bd060
                secret: 'H8FH8eSxM2K/S42CUg5K000Tt4WY2fI'
                bucket: 'video'
                region: us-west-000

  /api/admin/config/socialhandles:
    post:
      summary: Set your social handles.
      description: Sets the external links to social networks and profiles.
      tags: ['Admin']
      security:
        - AdminBasicAuth: []
      responses:
        '200':
          $ref: '#/components/responses/BasicResponse'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ConfigValue'
            example:
              value:
                - platform: github
                  url: https://github.com/owncast/owncast
                - platform: mastodon
                  url: https://mastodon.social/@gabek

  /api/admin/config/customstyles:
    post:
      summary: Custom CSS styles to be used in the web front endpoints.
      description: Save a string containing CSS to be inserted in to the web frontend page.
      tags: ['Admin']
      responses:
        '200':
          $ref: '#/components/responses/BasicResponse'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ConfigValue'
            example:
              value: 'body { color: orange; background: black; }'

  /api/admin/config/customjavascript:
    post:
      summary: Custom Javascript to be inserted into the frontend
      description: Save a string containing Javascript to be inserted in to the web frontend page.
      tags: ['Admin']
      responses:
        '200':
          $ref: '#/components/responses/BasicResponse'
      requestBody:
        content:
          application/javascript:
            schema:
              $ref: '#/components/schemas/ConfigValue'
            example:
              value: console.log('Hello world.');

  /api/admin/config/appearance:
    post:
      summary: Save a map of variables and values to be used in the frontend.
      description: These values will override the default values in the frontend.
      tags: ['Admin']
      responses:
        '200':
          $ref: '#/components/responses/BasicResponse'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                value:
                  type: object
            example:
              value:
                theme-color-components-primary-button-background: '#ff0000'
                theme-color-components-chat-background: '#000000'

  /api/admin/viewersOverTime:
    get:
      summary: Viewers Over Time
      description: Get the tracked viewer count over the collected period.
      tags: ['Admin']
      security:
        - AdminBasicAuth: []
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/TimestampedValue'
              examples:
                default:
                  value:
                    - time: '2020-10-03T21:41:00.381996-05:00'
                      value: 50
                    - time: '2020-10-03T21:42:00.381996-05:00'
                      value: 52

  /api/admin/hardwarestats:
    get:
      summary: Hardware Stats
      description: 'Get the CPU, Memory and Disk utilization levels over the collected period.'
      tags: ['Admin']
      security:
        - AdminBasicAuth: []
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  cpu:
                    type: array
                    items:
                      $ref: '#/components/schemas/TimestampedValue'
                  memory:
                    type: array
                    items:
                      $ref: '#/components/schemas/TimestampedValue'
                  disk:
                    type: array
                    items:
                      $ref: '#/components/schemas/TimestampedValue'
              examples:
                default:
                  value:
                    cpu:
                      - time: '2020-10-03T21:41:00.381996-05:00'
                        value: 23
                      - time: '2020-10-03T21:42:00.381996-05:00'
                        value: 27
                      - time: '2020-10-03T21:43:00.381996-05:00'
                        value: 22
                    memory:
                      - time: '2020-10-03T21:41:00.381996-05:00'
                        value: 65
                      - time: '2020-10-03T21:42:00.381996-05:00'
                        value: 66
                      - time: '2020-10-03T21:43:00.381996-05:00'
                        value: 72
                    disk:
                      - time: '2020-10-03T21:41:00.381996-05:00'
                        value: 11
                      - time: '2020-10-03T21:42:00.381996-05:00'
                        value: 11
                      - time: '2020-10-03T21:43:00.381996-05:00'
                        value: 11

  /api/admin/config/hideviewercount:
    post:
      summary: Enable or disable showing the viewer count.
      tags: ['Admin']
      security:
        - AdminBasicAuth: []
      responses:
        '200':
          $ref: '#/components/responses/BasicResponse'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BooleanValue'

  /api/admin/config/federation/enable:
    post:
      summary: Enable or disable federated social features.
      tags: ['Admin']
      security:
        - AdminBasicAuth: []
      responses:
        '200':
          $ref: '#/components/responses/BasicResponse'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BooleanValue'

  /api/admin/config/federation/private:
    post:
      summary: Enable or disable private federation mode.
      tags: ['Admin']
      security:
        - AdminBasicAuth: []
      responses:
        '200':
          $ref: '#/components/responses/BasicResponse'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BooleanValue'

  /api/admin/config/federation/showengagement:
    post:
      summary: Enable or disable Federation activity showing in chat.
      tags: ['Admin']
      security:
        - AdminBasicAuth: []
      responses:
        '200':
          $ref: '#/components/responses/BasicResponse'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BooleanValue'

  /api/admin/config/federation/username:
    post:
      summary: Set the username you are seen as on the fediverse.
      tags: ['Admin']
      security:
        - AdminBasicAuth: []
      responses:
        '200':
          $ref: '#/components/responses/BasicResponse'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ConfigValue'

  /api/admin/config/federation/livemessage:
    post:
      summary: Set the message sent to the fediverse when this instance goes live.
      tags: ['Admin']
      security:
        - AdminBasicAuth: []
      responses:
        '200':
          $ref: '#/components/responses/BasicResponse'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ConfigValue'

  /api/admin/config/federation/blockdomains:
    post:
      summary: Save a collection of domains that should be ignored on the fediverse.
      tags: ['Admin']
      security:
        - AdminBasicAuth: []
      responses:
        '200':
          $ref: '#/components/responses/BasicResponse'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ConfigValue'
            example:
              value:
                - guns.eagles.biz
                - freedom.us

  /api/admin/federation/send:
    post:
      summary: Manually send a message to the fediverse from this instance.
      tags: ['Admin']
      security:
        - AdminBasicAuth: []
      responses:
        '200':
          $ref: '#/components/responses/BasicResponse'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ConfigValue'
            example:
              value: I'm still streaming, you should come visit.

  /api/admin/federation/actions:
    get:
      summary: Get a list of accepted actions that took place on the Fediverse.
      tags: ['Admin']
      security:
        - AdminBasicAuth: []
      responses:
        '200':
          description: Actions previously handled.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/FederatedAction'

  /api/admin/emoji/upload:
    post:
      summary: Upload a single emoji image.
      tags: ['Admin']
      security:
        - AdminBasicAuth: []
      responses:
        '200':
          $ref: '#/components/responses/BasicResponse'

  /api/admin/emoji/delete:
    post:
      summary: Delete a single emoji image.
      tags: ['Admin']
      security:
        - AdminBasicAuth: []
      responses:
        '200':
          $ref: '#/components/responses/BasicResponse'
      requestBody:
        content:
          application/json:
            schema:
              type: object
            example:
              name: test.svg

  /api/integrations/streamtitle:
    post:
      summary: Set the stream title.
      description: Set the title of the currently streaming content.
      tags: ['Integrations']
      security:
        - AccessToken: []
      responses:
        '200':
          $ref: '#/components/responses/BasicResponse'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ConfigValue'
            example:
              value: Streaming my favorite game, Desert Bus.

  /api/integrations/chat/send:
    post:
      summary: Send a chat message.
      description: Send a chat message on behalf of a 3rd party integration, bot or service.
      tags: ['Integrations']
      security:
        - AccessToken: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                body:
                  type: string
                  description: The message text that will be sent as the user.
      responses:
        '200':
          description: Message was sent.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  message:
                    type: string
                    example: sent

  /api/integrations/chat/system:
    post:
      summary: Send a system chat message.
      description: Send a chat message on behalf of the system/server.
      tags: ['Integrations']
      security:
        - AccessToken: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                body:
                  type: string
                  description: The message text that will be sent as the system user.
      responses:
        '200':
          description: Message was sent.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  message:
                    type: string
                    example: sent

  /api/integrations/chat/action:
    post:
      summary: Send a chat action.
      description: Send an action that took place to the chat.
      tags: ['Integrations']
      security:
        - AccessToken: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - 'body'
              properties:
                body:
                  type: string
                  description: The message text that will be sent as the system user.
                  example: 'rolled a 15 on the dice'
                author:
                  type: string
                  description: An optional user name that performed the action.
                  example: 'JohnSmith'
      responses:
        '200':
          description: Message was sent.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  message:
                    type: string
                    example: sent

  /api/integrations/chat/system/client/{clientId}:
    post:
      summary: Send system chat message to a client, identified by its ClientId
      description: Send a chat message on behalf of the system/server to a single client.
      tags: ['Integrations']
      security:
        - AccessToken: []
      parameters:
        - name: clientId
          in: path
          description: Client ID (a unique numeric Id, identifying the client connection)
          required: true
          schema:
            type: integer
            format: int64
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - 'body'
              properties:
                body:
                  type: string
                  description: The message text that will be sent to the client.
                  example: 'What a beautiful day. I love it'
      responses:
        '200':
          description: Message was sent.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  messages:
                    type: string
                    example: sent
        '500':
          description: Message was not sent to the client
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: message explaining what went wrong sending the message to the client

  /api/admin/accesstokens/create:
    post:
      summary: Create an access token.
      description: Create a single access token that has access to the access scopes provided.
      tags: ['Integrations']
      security:
        - AdminBasicAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  description: The human-readable name to give this access token.
                scopes:
                  type: array
                  items:
                    type: string

      responses:
        '200':
          description: Token was created.
          content:
            application/json:
              schema:
                type: object
                properties:
                  name:
                    type: string
                    example: your new token
                  token:
                    type: string
                    example: 'zG2xO-mHTFnelCp5xaIkYEFWcPhoOswOSRmFC1BkI='

  /api/admin/accesstokens/delete:
    post:
      summary: Delete an access token.
      description: Delete a single access token.
      tags: ['Integrations']
      security:
        - AdminBasicAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                token:
                  type: string
                  description: The token to delete

      responses:
        '200':
          description: Token was deleted.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  message:
                    type: string
                    example: deleted token

  /api/admin/accesstokens:
    get:
      summary: Return all access tokens.
      description: Return all of the available access tokens.
      tags: ['Integrations']
      security:
        - AdminBasicAuth: []
      responses:
        '200':
          description: Tokens are returned
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string

  /api/admin/webhooks:
    get:
      summary: Return all webhooks.
      description: Return all of the configured webhooks for external events.
      tags: ['Admin']
      security:
        - AdminBasicAuth: []
      responses:
        '200':
          description: Webhooks are returned
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Webhook'

  /api/admin/config/externalactions:
    post:
      summary: Set external action URLs.
      description: Set a collection of external action URLs that are displayed in the UI.
      tags: ['Admin', 'Integrations']
      security:
        - AdminBasicAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                type: object
                properties:
                  url:
                    type: string
                    description: URL of the external action content.
                  title:
                    type: string
                    description: The title to put on the external action button.
                  description:
                    type: string
                    description: Optional additional description to display in the UI.
                  icon:
                    type: string
                    description: The URL to an image to place on the external action button.
                  color:
                    type: string
                    description: Optional color to use for drawing the action button.
                  openExternally:
                    type: boolean
                    description: If set this action will open in a new browser tab instead of an internal modal.
      responses:
        '200':
          description: Actions have been updated.

  /api/admin/webhooks/delete:
    post:
      summary: Delete a single webhook.
      description: Delete a single webhook by its ID.
      tags: ['Admin']
      security:
        - AdminBasicAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                id:
                  type: string
                  description: The webhook id to delete
      responses:
        '200':
          description: Webhook is deleted

  /api/admin/webhooks/create:
    post:
      summary: Create a webhook.
      description: Create a single webhook that acts on the requested events.
      tags: ['Admin']
      security:
        - AdminBasicAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                url:
                  type: string
                  description: The url to post the events to.
                events:
                  description: The events to be notified about.
                  type: array
                  items:
                    type: string

      responses:
        '200':
          description: Token was created.
          content:
            application/json:
              schema:
                type: object
                properties:
                  name:
                    type: string
                    example: your new token
                  token:
                    type: string
                    example: 'zG2xO-mHTFnelCp5xaIkYEFWcPhoOswOSRmFC1BkI='

  /api/integrations/clients:
    get:
      summary: Return a list of currently connected clients
      description: Return a list of currently connected clients with optional geo details.
      tags: ['Integrations']
      security:
        - AccessToken: []
      responses:
        '200':
          $ref: '#/components/responses/ClientsResponse'

  /api/integrations/chat:
    get:
      summary: Historical Chat Messages
      description: Used to get the backlog of chat messages.
      tags: ['Integrations']
      security:
        - AccessToken: []
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    user:
                      $ref: '#/components/schemas/User'
                    body:
                      type: string
                      description: Escaped HTML of the chat message content.
                    id:
                      type: string
                      description: Unique ID of the chat message.
                    visible:
                      type: boolean
                      description: 'Should chat message be visibly rendered.'
                    timestamp:
                      type: string
                      format: date-time

  /api/integrations/chat/messagevisibility:
    post:
      summary: Update the visibility of chat messages.
      description: Pass an array of IDs you want to change the chat visibility of.
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                visible:
                  type: boolean
                  description: Are these messages visible.
                idArray:
                  type: array
                  items:
                    type: string
                    description: IDs of the chat messages you wish to change the visibility of.
      tags: ['Integrations']
      security:
        - AccessToken: []
      responses:
        '200':
          $ref: '#/components/responses/BasicResponse'

  /api/admin/chat/users/setmoderator:
    post:
      summary: Set moderator privileges on a chat users.
      description: Give a chat user ID and be able to grant or remove moderator privileges to this user.
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                userId:
                  type: string
                  description: User ID of the chat user you want to change moderation status of.
                  example: xJ84_48Ghj
                isModerator:
                  type: boolean
                  description: The moderator status of this user.
                  example: true
      tags: ['Admin', 'Moderation']
      security:
        - AdminBasicAuth: []
      responses:
        '200':
          $ref: '#/components/responses/BasicResponse'

  /api/admin/chat/users/moderators:
    get:
      tags: ['Admin', 'Moderation']
      security:
        - AdminBasicAuth: []
      summary: Get a list of chat moderator users.
      responses:
        '200':
          description: List of moderators
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/User'

  /api/moderation/chat/user/:
    get:
      tags: ['Moderation']
      parameters:
        - name: name
          in: path
          description: User ID
          required: true
          schema:
            type: string
          example: USER-ID
      responses:
        '200':
          description: User
          content:
            application/json:
              schema:
                type: object
                properties:
                  user:
                    $ref: '#/components/schemas/User'
                  connectClients:
                    type: array
                    items:
                      $ref: '#/components/schemas/Client'
                  messages:
                    $ref: '#/components/schemas/ChatMessageArray'

  /api/admin/followers:
    get:
      tags: ['Admin']
      security:
        - AdminBasicAuth: []
      summary: Get the followers of this instance
      responses:
        '200':
          description: Followers
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Follower'

  /api/admin/followers/pending:
    get:
      tags: ['Admin']
      security:
        - AdminBasicAuth: []
      summary: Get a list of follow requests that are pending.
      responses:
        '200':
          description: Followers
          $ref: '#/components/schemas/FollowerArray'

  /api/admin/followers/blocked:
    get:
      tags: ['Admin']
      security:
        - AdminBasicAuth: []
      summary: Get a list of follow requests that have been blocked/rejected.
      responses:
        '200':
          description: Follower requests that have been rejected or blocked.
          $ref: '#/components/schemas/FollowerArray'

  /api/admin/followers/approve:
    post:
      tags: ['Admin']
      security:
        - AdminBasicAuth: []
      summary: Approve a pending follow request.
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                actorIRI:
                  type: string
                  description: The requestor's remote IRI used to identify the user.
      responses:
        '200':
          description: The request has been successfully approved.
          $ref: '#/components/responses/BasicResponse'

  /api/admin/config/chat/suggestedusernames:
    post:
      tags: ['Admin']
      security:
        - AdminBasicAuth: []
      summary: A list of names to select from randomly for new chat users.
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                value:
                  type: array
                  items:
                    type: string
      responses:
        '200':
          description: The list of default names have been updated.
          $ref: '#/components/responses/BasicResponse'

  /api/admin/prometheus:
    get:
      tags: ['Admin']
      security:
        - AdminBasicAuth: []
      summary: Return Prometheus-compatible scraper metrics.
      responses:
        '200':
          description: Prometheus-compatible scraper values.