Overshoot Streams API

openapi: 3.2.0
info:
  title: Inference Service Billing Streams API
  version: 0.4.0
  description: Pricing, prepaid balance, and checkout.
servers:
- url: https://api.overshoot.ai/v1beta
  description: Base URL declared by the provider in apis.yml (roadmap#122).
tags:
- name: Streams
  description: Create, inspect, keep alive, and delete live video streams.
paths:
  /streams:
    post:
      tags:
      - Streams
      operationId: createStream
      summary: Create stream
      description: 'Creates a live stream and returns a publish token. The current request body is

        empty. The retained frame history is fixed at 600 seconds.


        The publish token is scoped to this stream and grants media publish permissions.

        Renew it through [`/keepalive`](#tag/Streams/operation/keepaliveStream) before it

        expires.

        '
      parameters:
      - $ref: '#/components/parameters/RegionHeader'
      responses:
        '201':
          description: Stream created.
          headers:
            X-Overshoot-Region:
              $ref: '#/components/headers/RegionResponseHeader'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateStreamResponse'
        '401':
          description: Missing or invalid API key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: API key has no associated user.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: Wrong region.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RegionError'
        '503':
          description: Stream creation temporarily unavailable.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /streams/{stream_id}:
    parameters:
    - $ref: '#/components/parameters/StreamId'
    - $ref: '#/components/parameters/RegionHeader'
    get:
      tags:
      - Streams
      operationId: getStream
      summary: Get stream
      description: 'Returns current stream status and frame telemetry.


        `stream_time_ms` is zero until the first frame arrives. After that, it is measured

        from the first captured frame. When a stream ends, live counters and timestamps

        are snapshotted — `GET /streams/{id}` on an ended stream returns those final

        values; fields may be `null` if the stream ended before the value existed.

        '
      responses:
        '200':
          description: Stream state.
          headers:
            X-Overshoot-Region:
              $ref: '#/components/headers/RegionResponseHeader'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StreamStatusResponse'
        '401':
          description: Missing or invalid API key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Stream unknown, expired, deleted, or owned by a different user.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: Wrong region.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RegionError'
    delete:
      tags:
      - Streams
      operationId: deleteStream
      summary: Delete stream
      description: Request stream deletion.
      responses:
        '200':
          description: Delete acknowledged.
          headers:
            X-Overshoot-Region:
              $ref: '#/components/headers/RegionResponseHeader'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeleteStreamResponse'
        '401':
          description: Missing or invalid API key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Stream unknown, expired, deleted, or owned by a different user.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: Wrong region.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RegionError'
  /streams/{stream_id}/keepalive:
    parameters:
    - $ref: '#/components/parameters/StreamId'
    - $ref: '#/components/parameters/RegionHeader'
    post:
      tags:
      - Streams
      operationId: keepaliveStream
      summary: Renew stream lease
      description: 'Renews the stream lease and returns a fresh publish token. Clients should renew

        before the 5-minute lease expires, for example every 4 minutes, and pass the

        returned token to the LiveKit SDK with `room.updateToken(...)`.

        '
      responses:
        '200':
          description: Lease renewed.
          headers:
            X-Overshoot-Region:
              $ref: '#/components/headers/RegionResponseHeader'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/KeepaliveResponse'
        '401':
          description: Missing or invalid API key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Stream unknown, expired, deleted, or owned by a different user.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: Wrong region.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RegionError'
components:
  schemas:
    Error:
      type: object
      description: Standard error body used by stream-lifecycle and billing endpoints.
      properties:
        detail:
          type: string
      required:
      - detail
    KeepaliveResponse:
      type: object
      properties:
        id:
          type: string
          format: uuid
        expires_at_ms:
          type: integer
        ttl_seconds:
          type: integer
          example: 300
        stream_time_ms:
          type: number
          description: Current stream-clock position in ms.
        publish:
          $ref: '#/components/schemas/PublishInfo'
      required:
      - id
      - expires_at_ms
      - ttl_seconds
      - publish
    RegionError:
      type: object
      description: Returned on `409` when the request reaches the wrong region.
      properties:
        detail:
          type: object
          properties:
            error:
              type: string
              example: region_error
            expected_region:
              type: string
              example: us-west1
            requested_region:
              type: string
              nullable: true
              example: us-central1
    CreateStreamResponse:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: Unique stream identifier. Use this in every subsequent stream URL.
        state:
          type: string
          enum:
          - active
          description: Always `active` for a freshly created stream.
        publish:
          $ref: '#/components/schemas/PublishInfo'
        expires_at_ms:
          type: integer
          description: Wall-clock Unix ms when the lease will expire if not renewed via `/keepalive`.
        ttl_seconds:
          type: integer
          example: 300
          description: Lease TTL in seconds. Currently `300` for all streams.
      required:
      - id
      - state
      - publish
      - expires_at_ms
      - ttl_seconds
    PublishInfo:
      type: object
      description: WebRTC publish target. Connect with the LiveKit client SDK.
      properties:
        type:
          type: string
          enum:
          - livekit
          default: livekit
        url:
          type: string
          description: LiveKit room URL (`wss://...`).
        token:
          type: string
          description: Short-lived publish JWT for the LiveKit client.
      required:
      - type
      - url
      - token
    StreamStatusResponse:
      type: object
      properties:
        id:
          type: string
          format: uuid
        state:
          type: string
          enum:
          - active
          - ended
          description: 'Lifecycle state. `active` while the stream accepts publishers and inference.

            `ended` once it has expired or been deleted — this transition is terminal.

            '
        stream_time_ms:
          type: number
          nullable: true
          description: Stream-clock position in ms. Zero until the first frame arrives, then monotonically increasing from that first frame.
        first_frame_at_ms:
          type: integer
          nullable: true
          description: Wall-clock Unix ms of the first frame ever ingested.
        last_frame_at_ms:
          type: integer
          nullable: true
          description: Wall-clock Unix ms of the most recent frame.
        last_frame_index:
          type: integer
          nullable: true
          description: Lifetime index of the most recent frame. `frame_index=-1` resolves against this at request time.
        first_available_frame_at_ms:
          type: integer
          nullable: true
          description: Wall-clock Unix ms of the oldest retained frame.
        first_available_frame_index:
          type: integer
          nullable: true
          description: Lifetime index of the oldest frame still retained.
        created_at_ms:
          type: integer
          nullable: true
          description: Wall-clock Unix ms of stream creation.
        recent_fps:
          type: number
          nullable: true
          description: Rolling FPS over the current frame-metrics bucket for active streams.
        retained_frame_count:
          type: integer
          nullable: true
        evicted_frame_count:
          type: integer
          nullable: true
        expires_at_ms:
          type: integer
          nullable: true
          description: Wall-clock Unix ms when the lease will expire. `null` on ended streams.
        ttl_seconds:
          type: integer
          nullable: true
        ended_at_ms:
          type: integer
          nullable: true
          description: Wall-clock Unix ms when the stream entered the `ended` state.
        end_reason:
          type: string
          nullable: true
          enum:
          - expired
          - deleted
          description: 'Why the stream ended. `expired` = system-driven termination, `deleted` =

            explicit `DELETE`. `null` while `state == active`.

            '
        audio:
          type: boolean
          default: false
          description: Reserved for future audio support. Always `false` today.
      required:
      - id
      - state
    DeleteStreamResponse:
      type: object
      properties:
        id:
          type: string
          format: uuid
        deleted:
          type: boolean
          example: true
      required:
      - id
      - deleted
  parameters:
    RegionHeader:
      name: X-Overshoot-Region
      in: header
      required: false
      schema:
        type: string
        enum:
        - us-west1
        - us-central1
      description: 'Optional hint to route the request to the region that owns the stream. If the

        request reaches the wrong region the API returns `409` with a `region_error` body.

        '
    StreamId:
      name: stream_id
      in: path
      required: true
      schema:
        type: string
        format: uuid
      description: UUID returned by `POST /streams`.
  headers:
    RegionResponseHeader:
      description: The region that served this request.
      schema:
        type: string
        enum:
        - us-west1
        - us-central1
  securitySchemes:
    API_Key:
      type: http
      description: Bearer <api_key>
      scheme: bearer