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.  The following APIs represent the state in the development branch.
  version: '0.0.10-dev'
  contact:
    name: Gabe Kangas
    email: gabek@real-ity.com
    url: http://owncast.online
  x-logo:
    url: >-
      data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAIAAAACACAYAAADDPmHLAAAEvmlUWHRYTUw6Y29tLmFkb2JlLnhtcAAAAAAAPD94cGFja2V0IGJlZ2luPSLvu78iIGlkPSJXNU0wTXBDZWhpSHpyZVN6TlRjemtjOWQiPz4KPHg6eG1wbWV0YSB4bWxuczp4PSJhZG9iZTpuczptZXRhLyIgeDp4bXB0az0iWE1QIENvcmUgNS41LjAiPgogPHJkZjpSREYgeG1sbnM6cmRmPSJodHRwOi8vd3d3LnczLm9yZy8xOTk5LzAyLzIyLXJkZi1zeW50YXgtbnMjIj4KICA8cmRmOkRlc2NyaXB0aW9uIHJkZjphYm91dD0iIgogICAgeG1sbnM6ZXhpZj0iaHR0cDovL25zLmFkb2JlLmNvbS9leGlmLzEuMC8iCiAgICB4bWxuczp0aWZmPSJodHRwOi8vbnMuYWRvYmUuY29tL3RpZmYvMS4wLyIKICAgIHhtbG5zOnBob3Rvc2hvcD0iaHR0cDovL25zLmFkb2JlLmNvbS9waG90b3Nob3AvMS4wLyIKICAgIHhtbG5zOnhtcD0iaHR0cDovL25zLmFkb2JlLmNvbS94YXAvMS4wLyIKICAgIHhtbG5zOnhtcE1NPSJodHRwOi8vbnMuYWRvYmUuY29tL3hhcC8xLjAvbW0vIgogICAgeG1sbnM6c3RFdnQ9Imh0dHA6Ly9ucy5hZG9iZS5jb20veGFwLzEuMC9zVHlwZS9SZXNvdXJjZUV2ZW50IyIKICAgZXhpZjpQaXhlbFhEaW1lbnNpb249IjEyOCIKICAgZXhpZjpQaXhlbFlEaW1lbnNpb249IjEyOCIKICAgZXhpZjpDb2xvclNwYWNlPSIxIgogICB0aWZmOkltYWdlV2lkdGg9IjEyOCIKICAgdGlmZjpJbWFnZUxlbmd0aD0iMTI4IgogICB0aWZmOlJlc29sdXRpb25Vbml0PSIyIgogICB0aWZmOlhSZXNvbHV0aW9uPSI5Ni4wIgogICB0aWZmOllSZXNvbHV0aW9uPSI5Ni4wIgogICBwaG90b3Nob3A6Q29sb3JNb2RlPSIzIgogICBwaG90b3Nob3A6SUNDUHJvZmlsZT0ic1JHQiBJRUM2MTk2Ni0yLjEiCiAgIHhtcDpNb2RpZnlEYXRlPSIyMDIw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
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.

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"

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

    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: Hue value for displaying in the UI.
          example: 42
        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"
        
  securitySchemes:
    AdminBasicAuth:
      type: http
      scheme: basic
      description: The username for admin basic auth is `admin` and the password is the stream key.
    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: 3rd party integration auth where a service user must provide an access token.

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

    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/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:
                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/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

  /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/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/updatemessagevisibility:
    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/key:
    post:
      summary: Set the stream key.
      description: Set the stream key.  Also used as 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/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/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 configration. 
        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/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/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/updatemessagevisibility:
    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"