openapi: 3.0.0
info:
  title: Restream API
  description: >-
    The Restream API enables developers to build live streaming integrations and
    manage multistreaming to 30+ platforms including YouTube, Twitch, Facebook,
    LinkedIn, and more. Supports REST endpoints for user profile, channels,
    stream keys, events, and real-time WebSocket updates.
  version: v2
  contact:
    email: developers@restream.io
    url: https://developers.restream.io
  termsOfService: https://restream.io/terms
  license:
    name: Proprietary
servers:
  - url: https://api.restream.io/v2
    description: Restream REST API v2
tags:
  - name: Platforms
    description: Public platform information
  - name: User
    description: User profile and account management
  - name: Channels
    description: Channel management and configuration
  - name: Stream Keys
    description: Stream key and SRT URL management
  - name: Events
    description: Live event management and scheduling
paths:
  /platform/all:
    get:
      operationId: listPlatforms
      summary: List All Platforms
      description: Returns all streaming platforms supported by Restream. This is a public endpoint that does not require authentication.
      tags:
        - Platforms
      responses:
        '200':
          description: List of supported streaming platforms
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Platform'
  /user/profile:
    get:
      operationId: getUserProfile
      summary: Get User Profile
      description: Retrieve the authenticated user's profile information.
      tags:
        - User
      security:
        - OAuth2: [profile.read]
      responses:
        '200':
          description: User profile
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserProfile'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /user/streamKey:
    get:
      operationId: getStreamKey
      summary: Get Stream Key
      description: Retrieve the authenticated user's stream key and SRT URL for live streaming.
      tags:
        - Stream Keys
      security:
        - OAuth2: [stream.read]
      responses:
        '200':
          description: User stream key and SRT URL
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StreamKey'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /user/channel/all:
    get:
      operationId: listChannels
      summary: List All Channels
      description: Retrieve all channels associated with the authenticated user's account.
      tags:
        - Channels
      security:
        - OAuth2: [channels.read]
      responses:
        '200':
          description: List of user channels
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Channel'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /user/channel/{id}:
    get:
      operationId: getChannel
      summary: Get Channel
      description: Retrieve a specific channel by its ID.
      tags:
        - Channels
      security:
        - OAuth2: [channels.read]
      parameters:
        - name: id
          in: path
          required: true
          description: Channel identifier
          schema:
            type: integer
      responses:
        '200':
          description: Channel details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Channel'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    patch:
      operationId: updateChannel
      summary: Update Channel
      description: Update settings for a specific channel.
      tags:
        - Channels
      security:
        - OAuth2: [channels.write]
      parameters:
        - name: id
          in: path
          required: true
          description: Channel identifier
          schema:
            type: integer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ChannelUpdate'
      responses:
        '200':
          description: Updated channel
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Channel'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /user/channel/{id}/meta:
    get:
      operationId: getChannelMeta
      summary: Get Channel Meta
      description: Retrieve metadata for a specific channel.
      tags:
        - Channels
      security:
        - OAuth2: [channels.read]
      parameters:
        - name: id
          in: path
          required: true
          description: Channel identifier
          schema:
            type: integer
      responses:
        '200':
          description: Channel metadata
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChannelMeta'
        '401':
          $ref: '#/components/responses/Unauthorized'
    patch:
      operationId: updateChannelMeta
      summary: Update Channel Meta
      description: Update metadata for a specific channel.
      tags:
        - Channels
      security:
        - OAuth2: [channels.write]
      parameters:
        - name: id
          in: path
          required: true
          description: Channel identifier
          schema:
            type: integer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ChannelMetaUpdate'
      responses:
        '200':
          description: Updated channel metadata
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChannelMeta'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /user/event/upcoming:
    get:
      operationId: listUpcomingEvents
      summary: List Upcoming Events
      description: Retrieve all upcoming live events for the authenticated user.
      tags:
        - Events
      security:
        - OAuth2: [events.read]
      responses:
        '200':
          description: List of upcoming events
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Event'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /user/event/in-progress:
    get:
      operationId: listInProgressEvents
      summary: List In-Progress Events
      description: Retrieve all currently active live events for the authenticated user.
      tags:
        - Events
      security:
        - OAuth2: [events.read]
      responses:
        '200':
          description: List of in-progress events
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Event'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /user/event/history:
    get:
      operationId: listEventHistory
      summary: List Event History
      description: Retrieve historical live events for the authenticated user.
      tags:
        - Events
      security:
        - OAuth2: [events.read]
      parameters:
        - name: limit
          in: query
          required: false
          description: Maximum number of events to return
          schema:
            type: integer
        - name: offset
          in: query
          required: false
          description: Number of events to skip for pagination
          schema:
            type: integer
      responses:
        '200':
          description: List of past events
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Event'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /user/event/{id}:
    get:
      operationId: getEvent
      summary: Get Event
      description: Retrieve details for a specific event by its ID.
      tags:
        - Events
      security:
        - OAuth2: [events.read]
      parameters:
        - name: id
          in: path
          required: true
          description: Event identifier
          schema:
            type: string
      responses:
        '200':
          description: Event details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Event'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /user/event/{id}/streamKey:
    get:
      operationId: getEventStreamKey
      summary: Get Event Stream Key
      description: Retrieve the stream key for a specific event.
      tags:
        - Events
      security:
        - OAuth2: [events.read]
      parameters:
        - name: id
          in: path
          required: true
          description: Event identifier
          schema:
            type: string
      responses:
        '200':
          description: Event stream key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StreamKey'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /oauth/token:
    post:
      operationId: refreshToken
      summary: Refresh OAuth Token
      description: Obtain a new access token using a refresh token via the OAuth2 refresh_token grant.
      tags:
        - User
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              required:
                - grant_type
                - refresh_token
                - client_id
                - client_secret
              properties:
                grant_type:
                  type: string
                  enum: [refresh_token]
                  description: Must be set to "refresh_token"
                refresh_token:
                  type: string
                  description: The refresh token from a prior code exchange
                client_id:
                  type: string
                  description: Your application's client ID
                client_secret:
                  type: string
                  description: Your application's client secret
      responses:
        '200':
          description: New access and refresh tokens
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TokenResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
components:
  securitySchemes:
    OAuth2:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://api.restream.io/oauth/authorize
          tokenUrl: https://api.restream.io/oauth/token
          refreshUrl: https://api.restream.io/oauth/token
          scopes:
            profile.read: Read user profile information
            channels.read: Read channel information
            channels.write: Update channel settings
            stream.read: Read stream key information
            events.read: Read event information
            events.write: Create and update events
            chat.read: Read chat messages
  responses:
    Unauthorized:
      description: Unauthorized - invalid or missing access token
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  schemas:
    Platform:
      type: object
      properties:
        id:
          type: integer
          description: Unique platform identifier
          example: 1
        name:
          type: string
          description: Platform name
          example: Twitch
        url:
          type: string
          description: Platform website URL
          example: https://twitch.tv
        image:
          type: object
          properties:
            png:
              type: string
              description: PNG image URL
            svg:
              type: string
              description: SVG image URL
    UserProfile:
      type: object
      properties:
        id:
          type: integer
          description: User identifier
        email:
          type: string
          description: User email address
        displayName:
          type: string
          description: User display name
        username:
          type: string
          description: Username
        createdAt:
          type: string
          format: date-time
          description: Account creation timestamp
    StreamKey:
      type: object
      properties:
        streamKey:
          type: string
          description: RTMP stream key
          example: re_xxx_xxx
        srtUrl:
          type: string
          nullable: true
          description: SRT streaming URL, null if user does not have SRT access
    Channel:
      type: object
      properties:
        id:
          type: integer
          description: Channel identifier
        streamingPlatformId:
          type: integer
          description: Associated platform ID
        embedUrl:
          type: string
          description: Embedded player URL
        url:
          type: string
          description: Channel URL
        identifier:
          type: string
          description: Channel identifier string
        displayName:
          type: string
          description: Channel display name
        active:
          type: boolean
          description: Whether the channel is active
    ChannelUpdate:
      type: object
      properties:
        active:
          type: boolean
          description: Enable or disable the channel
        displayName:
          type: string
          description: Channel display name
    ChannelMeta:
      type: object
      properties:
        id:
          type: integer
          description: Channel identifier
        title:
          type: string
          description: Stream title for this channel
        description:
          type: string
          description: Stream description
        tags:
          type: array
          items:
            type: string
          description: Stream tags
    ChannelMetaUpdate:
      type: object
      properties:
        title:
          type: string
          description: Stream title
        description:
          type: string
          description: Stream description
        tags:
          type: array
          items:
            type: string
          description: Stream tags
    Event:
      type: object
      properties:
        id:
          type: string
          description: Event identifier
        title:
          type: string
          description: Event title
        description:
          type: string
          description: Event description
        status:
          type: string
          enum: [upcoming, in-progress, completed]
          description: Current event status
        startedAt:
          type: string
          format: date-time
          nullable: true
          description: Event start time
        endedAt:
          type: string
          format: date-time
          nullable: true
          description: Event end time
        channels:
          type: array
          items:
            type: integer
          description: Channel IDs for this event
    TokenResponse:
      type: object
      properties:
        access_token:
          type: string
          description: New access token
        expires_in:
          type: integer
          description: Access token expiry in seconds (3600 = 1 hour)
        refresh_token:
          type: string
          description: New refresh token (valid for 1 year)
        scope:
          type: string
          description: Granted OAuth2 scopes
        token_type:
          type: string
          description: Token type (Bearer)
    Error:
      type: object
      properties:
        statusCode:
          type: integer
          description: HTTP status code
        status:
          type: integer
        code:
          type: integer
          description: Application error code
        message:
          type: string
          description: Human-readable error message
        name:
          type: string
          description: Error type identifier