Overshoot Streams API

openapi: 3.2.0
info:
  title: Overshoot Streams API
  version: 1.0.0-beta
  description: 'Real-time video understanding API. Create a live video stream, push frames over

    WebRTC (LiveKit), then ask a vision-language model questions about what''s happening

    using an OpenAI-compatible chat completions endpoint.


    Billing endpoints are mounted on the same host under `/billing`.'
servers:
- url: https://api.overshoot.ai/v1beta
security:
- bearerAuth: []
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` 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:
  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`.
  schemas:
    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
    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
    Error:
      type: object
      description: Standard error body used by stream-lifecycle and billing endpoints.
      properties:
        detail:
          type: string
      required:
      - detail
    DeleteStreamResponse:
      type: object
      properties:
        id:
          type: string
          format: uuid
        deleted:
          type: boolean
          example: true
      required:
      - id
      - deleted
    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
          - 'null'
          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
          - 'null'
          description: Wall-clock Unix ms of the first frame ever ingested.
        last_frame_at_ms:
          type:
          - integer
          - 'null'
          description: Wall-clock Unix ms of the most recent frame.
        last_frame_index:
          type:
          - integer
          - 'null'
          description: Lifetime index of the most recent frame. `frame_index=-1` resolves against this at request time.
        first_available_frame_at_ms:
          type:
          - integer
          - 'null'
          description: Wall-clock Unix ms of the oldest retained frame.
        first_available_frame_index:
          type:
          - integer
          - 'null'
          description: Lifetime index of the oldest frame still retained.
        created_at_ms:
          type:
          - integer
          - 'null'
          description: Wall-clock Unix ms of stream creation.
        recent_fps:
          type:
          - number
          - 'null'
          description: Rolling FPS over the current frame-metrics bucket for active streams.
        retained_frame_count:
          type:
          - integer
          - 'null'
        evicted_frame_count:
          type:
          - integer
          - 'null'
        expires_at_ms:
          type:
          - integer
          - 'null'
          description: Wall-clock Unix ms when the lease will expire. `null` on ended streams.
        ttl_seconds:
          type:
          - integer
          - 'null'
        ended_at_ms:
          type:
          - integer
          - 'null'
          description: Wall-clock Unix ms when the stream entered the `ended` state.
        end_reason:
          type:
          - string
          - 'null'
          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
    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
    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
              - 'null'
              example: us-central1
  headers:
    RegionResponseHeader:
      description: The region that served this request.
      schema:
        type: string
        enum:
        - us-west1
        - us-central1
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API key (e.g. `ovs_...`)
      description: "Every public HTTP request requires `Authorization: Bearer <api_key>`, except\n`GET /models` and the public `/billing/pricing` endpoints.\n\n- `401` means the key is missing, unknown, or revoked.\n- `403` means the key is valid but cannot access the requested resource.\n- The publish token returned by `POST /streams` is only for publishing media to\n  LiveKit. It does not replace the API key for HTTP calls.\n"