openapi: 3.0.3
info:
  title: FastPix API
  version: '1.0'
  description: >-
    FastPix is a developer-first video platform providing APIs for video
    on-demand (upload, ingest, encode, playback), live streaming, simulcasting,
    secure playback with signing keys and DRM, in-video AI (transcription,
    summaries, chapters, moderation, named entities), and video data / views
    analytics. All endpoints are served under the versioned base URL and secured
    with HTTP Basic authentication using an Access Token ID (username) and
    Secret Key (password) generated in the FastPix dashboard.
  contact:
    name: FastPix
    url: https://www.fastpix.io
  x-logo:
    url: https://kinlane-images.s3.amazonaws.com/shared/apis-json/apis-json-logo.jpg
servers:
- url: https://api.fastpix.io/v1
  description: FastPix production API
security:
- basicAuth: []
tags:
- name: On-Demand
  description: Upload, import, manage, and encode video-on-demand media.
- name: Live Streaming
  description: Create and manage live streams and their playback.
- name: Simulcast
  description: Restream a live stream to third-party RTMP destinations.
- name: Playback
  description: Manage playback IDs for media and live streams.
- name: Signing Keys
  description: Manage keys used to sign JWTs for secure, tokenized playback.
- name: DRM
  description: Retrieve DRM configurations for protected playback.
- name: In-Video AI
  description: AI-driven media enrichment - summaries, chapters, moderation, named entities, subtitles.
- name: Data
  description: Video views, metrics, dimensions, errors, and timeseries analytics.
paths:
  /on-demand:
    post:
      tags: [On-Demand]
      operationId: createMedia
      summary: Create media from a URL
      description: Creates a new on-demand media asset by importing a publicly accessible video file URL.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateMediaRequest'
      responses:
        '201':
          description: Media created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MediaResponse'
    get:
      tags: [On-Demand]
      operationId: listMedia
      summary: List all media
      parameters:
      - name: limit
        in: query
        schema: { type: integer, default: 20 }
      - name: offset
        in: query
        schema: { type: integer, default: 1 }
      responses:
        '200':
          description: A list of media assets
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MediaListResponse'
  /on-demand/upload:
    post:
      tags: [On-Demand]
      operationId: createUpload
      summary: Upload media from a device
      description: Requests a signed URL for a direct, resumable device upload of a video file.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateUploadRequest'
      responses:
        '201':
          description: Signed upload URL created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UploadResponse'
  /on-demand/uploads:
    get:
      tags: [On-Demand]
      operationId: listUploads
      summary: List unused upload URLs
      responses:
        '200': { description: A list of unused uploads }
  /on-demand/upload/{uploadId}:
    put:
      tags: [On-Demand]
      operationId: cancelUpload
      summary: Cancel an in-progress upload
      parameters:
      - { name: uploadId, in: path, required: true, schema: { type: string } }
      responses:
        '200': { description: Upload cancelled }
  /on-demand/{mediaId}:
    get:
      tags: [On-Demand]
      operationId: getMedia
      summary: Get a media asset by ID
      parameters:
      - { name: mediaId, in: path, required: true, schema: { type: string } }
      responses:
        '200':
          description: The media asset
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MediaResponse'
    patch:
      tags: [On-Demand]
      operationId: updateMedia
      summary: Update a media asset
      description: >-
        Updates media metadata and enrichment flags. Used to enable in-video AI
        features such as summary, chapters, named entities, and moderation.
      parameters:
      - { name: mediaId, in: path, required: true, schema: { type: string } }
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateMediaRequest'
      responses:
        '200': { description: Updated media asset }
    delete:
      tags: [On-Demand]
      operationId: deleteMedia
      summary: Delete a media asset
      parameters:
      - { name: mediaId, in: path, required: true, schema: { type: string } }
      responses:
        '200': { description: Media deleted }
  /on-demand/{mediaId}/media-clips:
    get:
      tags: [On-Demand]
      operationId: listMediaClips
      summary: List clips generated from a media asset
      parameters:
      - { name: mediaId, in: path, required: true, schema: { type: string } }
      responses:
        '200': { description: A list of clips }
  /on-demand/{mediaId}/source:
    patch:
      tags: [On-Demand]
      operationId: updateSourceAccess
      summary: Update source access for a media asset
      parameters:
      - { name: mediaId, in: path, required: true, schema: { type: string } }
      responses:
        '200': { description: Source access updated }
  /on-demand/{mediaId}/update-mp4Support:
    patch:
      tags: [On-Demand]
      operationId: updateMp4Support
      summary: Enable or update MP4 downloads for a media asset
      parameters:
      - { name: mediaId, in: path, required: true, schema: { type: string } }
      responses:
        '200': { description: MP4 support updated }
  /on-demand/{mediaId}/tracks:
    post:
      tags: [On-Demand]
      operationId: addMediaTrack
      summary: Add an audio or subtitle track to a media asset
      parameters:
      - { name: mediaId, in: path, required: true, schema: { type: string } }
      responses:
        '201': { description: Track added }
  /on-demand/{mediaId}/tracks/{trackId}:
    patch:
      tags: [On-Demand]
      operationId: updateMediaTrack
      summary: Update a media track
      parameters:
      - { name: mediaId, in: path, required: true, schema: { type: string } }
      - { name: trackId, in: path, required: true, schema: { type: string } }
      responses:
        '200': { description: Track updated }
    delete:
      tags: [On-Demand]
      operationId: deleteMediaTrack
      summary: Delete a media track
      parameters:
      - { name: mediaId, in: path, required: true, schema: { type: string } }
      - { name: trackId, in: path, required: true, schema: { type: string } }
      responses:
        '200': { description: Track deleted }
  /on-demand/{mediaId}/tracks/{trackId}/generate-subtitle:
    post:
      tags: [In-Video AI]
      operationId: generateSubtitleTrack
      summary: Generate a subtitle track from an audio track
      parameters:
      - { name: mediaId, in: path, required: true, schema: { type: string } }
      - { name: trackId, in: path, required: true, schema: { type: string } }
      responses:
        '201': { description: Subtitle track generation started }
  /live/streams:
    post:
      tags: [Live Streaming]
      operationId: createStream
      summary: Create a new live stream
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateStreamRequest'
      responses:
        '201':
          description: Live stream created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StreamResponse'
    get:
      tags: [Live Streaming]
      operationId: listStreams
      summary: List all live streams
      responses:
        '200': { description: A list of live streams }
  /live/streams/{streamId}:
    get:
      tags: [Live Streaming]
      operationId: getStream
      summary: Get a live stream by ID
      parameters:
      - { name: streamId, in: path, required: true, schema: { type: string } }
      responses:
        '200':
          description: The live stream
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StreamResponse'
    patch:
      tags: [Live Streaming]
      operationId: updateStream
      summary: Update a live stream
      parameters:
      - { name: streamId, in: path, required: true, schema: { type: string } }
      responses:
        '200': { description: Live stream updated }
    delete:
      tags: [Live Streaming]
      operationId: deleteStream
      summary: Delete a live stream
      parameters:
      - { name: streamId, in: path, required: true, schema: { type: string } }
      responses:
        '200': { description: Live stream deleted }
  /live/streams/{streamId}/live-clips:
    get:
      tags: [Live Streaming]
      operationId: listLiveClips
      summary: List clips generated from a live stream
      parameters:
      - { name: streamId, in: path, required: true, schema: { type: string } }
      responses:
        '200': { description: A list of live clips }
  /live/streams/{streamId}/playback-ids:
    post:
      tags: [Playback]
      operationId: createStreamPlaybackId
      summary: Create a playback ID for a live stream
      parameters:
      - { name: streamId, in: path, required: true, schema: { type: string } }
      responses:
        '201': { description: Playback ID created }
  /live/streams/{streamId}/playback-ids/{playbackId}:
    get:
      tags: [Playback]
      operationId: getStreamPlaybackId
      summary: Get a live stream playback ID
      parameters:
      - { name: streamId, in: path, required: true, schema: { type: string } }
      - { name: playbackId, in: path, required: true, schema: { type: string } }
      responses:
        '200': { description: Playback ID details }
    delete:
      tags: [Playback]
      operationId: deleteStreamPlaybackId
      summary: Delete a live stream playback ID
      parameters:
      - { name: streamId, in: path, required: true, schema: { type: string } }
      - { name: playbackId, in: path, required: true, schema: { type: string } }
      responses:
        '200': { description: Playback ID deleted }
  /live/streams/{streamId}/simulcast:
    post:
      tags: [Simulcast]
      operationId: createSimulcast
      summary: Create a simulcast target for a live stream
      parameters:
      - { name: streamId, in: path, required: true, schema: { type: string } }
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateSimulcastRequest'
      responses:
        '201': { description: Simulcast created }
  /live/streams/{streamId}/simulcast/{simulcastId}:
    get:
      tags: [Simulcast]
      operationId: getSimulcast
      summary: Get a simulcast target
      parameters:
      - { name: streamId, in: path, required: true, schema: { type: string } }
      - { name: simulcastId, in: path, required: true, schema: { type: string } }
      responses:
        '200': { description: Simulcast details }
    patch:
      tags: [Simulcast]
      operationId: updateSimulcast
      summary: Enable or disable a simulcast target
      parameters:
      - { name: streamId, in: path, required: true, schema: { type: string } }
      - { name: simulcastId, in: path, required: true, schema: { type: string } }
      responses:
        '200': { description: Simulcast updated }
    delete:
      tags: [Simulcast]
      operationId: deleteSimulcast
      summary: Delete a simulcast target
      parameters:
      - { name: streamId, in: path, required: true, schema: { type: string } }
      - { name: simulcastId, in: path, required: true, schema: { type: string } }
      responses:
        '200': { description: Simulcast deleted }
  /security/signing-keys:
    post:
      tags: [Signing Keys]
      operationId: createSigningKey
      summary: Create a new signing key
      description: Generates an RSA key pair used to sign JWTs for tokenized, secure playback.
      responses:
        '201':
          description: Signing key created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SigningKeyResponse'
    get:
      tags: [Signing Keys]
      operationId: listSigningKeys
      summary: List all signing keys
      responses:
        '200': { description: A list of signing keys }
  /security/signing-keys/{signingKeyId}:
    get:
      tags: [Signing Keys]
      operationId: getSigningKey
      summary: Get a signing key by ID
      parameters:
      - { name: signingKeyId, in: path, required: true, schema: { type: string } }
      responses:
        '200': { description: Signing key details }
    delete:
      tags: [Signing Keys]
      operationId: deleteSigningKey
      summary: Delete a signing key
      parameters:
      - { name: signingKeyId, in: path, required: true, schema: { type: string } }
      responses:
        '200': { description: Signing key deleted }
  /on-demand/drm-configurations:
    get:
      tags: [DRM]
      operationId: listDrmConfigurations
      summary: List DRM configurations
      responses:
        '200': { description: A list of DRM configurations }
  /on-demand/drm-configurations/{drmConfigurationId}:
    get:
      tags: [DRM]
      operationId: getDrmConfiguration
      summary: Get a DRM configuration by ID
      parameters:
      - { name: drmConfigurationId, in: path, required: true, schema: { type: string } }
      responses:
        '200': { description: DRM configuration details }
  /data/dimensions:
    get:
      tags: [Data]
      operationId: listDimensions
      summary: List available viewer/session dimensions
      responses:
        '200': { description: A list of dimensions }
  /data/dimensions/{dimensionId}:
    get:
      tags: [Data]
      operationId: listDimensionValues
      summary: List values for a dimension
      parameters:
      - { name: dimensionId, in: path, required: true, schema: { type: string } }
      responses:
        '200': { description: A list of dimension values }
  /data/views:
    get:
      tags: [Data]
      operationId: listVideoViews
      summary: List video views
      responses:
        '200':
          description: A list of video views
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ViewsListResponse'
  /data/views/{viewId}:
    get:
      tags: [Data]
      operationId: getVideoView
      summary: Get details for a single video view
      parameters:
      - { name: viewId, in: path, required: true, schema: { type: string } }
      responses:
        '200': { description: Video view details }
  /data/errors:
    get:
      tags: [Data]
      operationId: listErrors
      summary: List playback errors
      responses:
        '200': { description: A list of errors }
  /data/metrics/timeseries/{metricId}:
    get:
      tags: [Data]
      operationId: getTimeseriesData
      summary: Get timeseries data for a metric
      parameters:
      - { name: metricId, in: path, required: true, schema: { type: string } }
      responses:
        '200': { description: Timeseries data points }
  /data/metrics/breakdown/{metricId}:
    get:
      tags: [Data]
      operationId: getMetricBreakdown
      summary: Get a metric broken down by a dimension
      parameters:
      - { name: metricId, in: path, required: true, schema: { type: string } }
      responses:
        '200': { description: Breakdown values }
  /data/metrics/overall/{metricId}:
    get:
      tags: [Data]
      operationId: getOverallMetric
      summary: Get overall values for a metric
      parameters:
      - { name: metricId, in: path, required: true, schema: { type: string } }
      responses:
        '200': { description: Overall metric values }
components:
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
      description: >-
        HTTP Basic authentication. Use your FastPix Access Token ID as the
        username and your Secret Key as the password.
  schemas:
    CreateMediaRequest:
      type: object
      required: [inputs]
      properties:
        inputs:
          type: array
          items:
            type: object
            properties:
              type: { type: string, example: video }
              url: { type: string, format: uri, example: 'https://static.fastpix.io/sample.mp4' }
        metadata:
          type: object
          additionalProperties: { type: string }
        accessPolicy: { type: string, enum: [public, private, drm], example: public }
        maxResolution: { type: string, enum: ['480p', '720p', '1080p', '1440p', '2160p'], example: '1080p' }
        mp4Support: { type: string, enum: [none, capped_4k, audioOnly], example: none }
    CreateUploadRequest:
      type: object
      properties:
        corsOrigin: { type: string, example: '*' }
        pushMediaSettings:
          type: object
          properties:
            accessPolicy: { type: string, enum: [public, private, drm] }
            maxResolution: { type: string }
    UploadResponse:
      type: object
      properties:
        success: { type: boolean }
        data:
          type: object
          properties:
            uploadId: { type: string }
            url: { type: string, format: uri }
    MediaResponse:
      type: object
      properties:
        success: { type: boolean }
        data:
          $ref: '#/components/schemas/Media'
    MediaListResponse:
      type: object
      properties:
        success: { type: boolean }
        data:
          type: array
          items:
            $ref: '#/components/schemas/Media'
    Media:
      type: object
      properties:
        id: { type: string }
        status: { type: string, enum: [preparing, ready, errored], example: ready }
        createdAt: { type: string, format: date-time }
        duration: { type: string, example: '00:01:23' }
        maxResolution: { type: string }
        sourceResolution: { type: string }
        aspectRatio: { type: string, example: '16:9' }
        playbackIds:
          type: array
          items:
            $ref: '#/components/schemas/PlaybackId'
        metadata:
          type: object
          additionalProperties: { type: string }
    UpdateMediaRequest:
      type: object
      properties:
        metadata:
          type: object
          additionalProperties: { type: string }
        summary: { type: boolean, description: Enable AI-generated summary. }
        chapters: { type: boolean, description: Enable AI-generated chapters. }
        namedEntities: { type: boolean, description: Enable named-entity extraction. }
        moderation:
          type: object
          properties:
            type: { type: string, example: video }
    PlaybackId:
      type: object
      properties:
        id: { type: string }
        accessPolicy: { type: string, enum: [public, private, drm] }
    CreateStreamRequest:
      type: object
      properties:
        playbackSettings:
          type: object
          properties:
            accessPolicy: { type: string, enum: [public, private] }
        inputMediaSettings:
          type: object
          properties:
            maxResolution: { type: string, example: '1080p' }
            reconnectWindow: { type: integer, example: 60 }
            mediaPolicy: { type: string, enum: [public, private] }
    StreamResponse:
      type: object
      properties:
        success: { type: boolean }
        data:
          type: object
          properties:
            streamId: { type: string }
            streamKey: { type: string }
            srtSecretKey: { type: string }
            status: { type: string, enum: [idle, active, disabled] }
            playbackIds:
              type: array
              items:
                $ref: '#/components/schemas/PlaybackId'
    CreateSimulcastRequest:
      type: object
      required: [url, streamKey]
      properties:
        url: { type: string, example: 'rtmps://live.example.com:443/app' }
        streamKey: { type: string }
        metadata:
          type: object
          additionalProperties: { type: string }
    SigningKeyResponse:
      type: object
      properties:
        success: { type: boolean }
        data:
          type: object
          properties:
            id: { type: string }
            privateKey: { type: string, description: Base64-encoded PEM private key (returned once). }
            createdAt: { type: string, format: date-time }
    ViewsListResponse:
      type: object
      properties:
        success: { type: boolean }
        data:
          type: array
          items:
            type: object
            properties:
              viewId: { type: string }
              viewerId: { type: string }
              playbackId: { type: string }
              watchTime: { type: integer }
              bufferingCount: { type: integer }
              startupTime: { type: integer }