openapi: 3.0.3
info:
  title: Castr API
  description: >-
    Castr is a live video streaming, multistreaming, and video-hosting (VOD)
    platform. This OpenAPI describes Castr's documented, self-serve REST API at
    https://api.castr.com/v2 for managing live streams and their multistream
    platform destinations, sub-second (WebRTC) streams, video hosting folders and
    uploads, live-to-VOD recordings, activity logs/events and stream stats, and
    webhook endpoints. Requests are authenticated with an API token issued from
    the account settings API section and sent in an authorization header.


    Endpoint paths, methods, and resource groupings are taken from Castr's
    published developer reference and its machine index (developers.castr.com,
    including llms.txt). The request/response schemas here are honestly modeled
    from the documentation rather than copied from a Castr-published OpenAPI file;
    verify property-level detail against the live reference.
  version: '1.0'
  contact:
    name: Castr
    url: https://castr.com
  x-modeled: true
servers:
  - url: https://api.castr.com/v2
    description: Castr production API
security:
  - apiToken: []
tags:
  - name: Live Streams
    description: Live streams and their multistream platform destinations.
  - name: Sub-Second Streams
    description: Ultra-low-latency (WebRTC) live streams.
  - name: Video Hosting
    description: Video hosting folders, uploads, and live-to-VOD recordings.
  - name: Analytics
    description: Activity logs, activity events, and stream stats.
  - name: Webhooks
    description: Webhook endpoints for event delivery.
paths:
  /live_streams:
    get:
      operationId: listLiveStreams
      tags: [Live Streams]
      summary: List live streams
      description: Lists the live streams in your account.
      responses:
        '200':
          description: A list of live streams.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/LiveStream'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: createLiveStream
      tags: [Live Streams]
      summary: Create a new live stream
      description: Creates a live stream that ingests an RTMP or SRT source and can multistream to multiple destinations.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LiveStreamCreate'
      responses:
        '201':
          description: The created live stream.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LiveStream'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /live_streams/{stream_id}:
    parameters:
      - $ref: '#/components/parameters/StreamId'
    get:
      operationId: getLiveStream
      tags: [Live Streams]
      summary: Get a live stream
      responses:
        '200':
          description: The requested live stream.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LiveStream'
        '404':
          $ref: '#/components/responses/NotFound'
    patch:
      operationId: updateLiveStream
      tags: [Live Streams]
      summary: Update a live stream
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LiveStreamUpdate'
      responses:
        '200':
          description: The updated live stream.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LiveStream'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      operationId: deleteLiveStream
      tags: [Live Streams]
      summary: Delete a live stream
      responses:
        '204':
          description: The live stream was deleted.
        '404':
          $ref: '#/components/responses/NotFound'
  /live_streams/{stream_id}/stats:
    parameters:
      - $ref: '#/components/parameters/StreamId'
    get:
      operationId: getLiveStreamStats
      tags: [Analytics]
      summary: Get stream stats
      description: Returns online status, duration, bitrate, codec, resolution, and viewer stats for a stream.
      responses:
        '200':
          description: Stream stats.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StreamStats'
        '404':
          $ref: '#/components/responses/NotFound'
  /live_streams/{stream_id}/epg:
    parameters:
      - $ref: '#/components/parameters/StreamId'
    get:
      operationId: getLiveStreamEpg
      tags: [Live Streams]
      summary: Get live EPG
      description: Returns the electronic program guide (schedule) for a live stream.
      responses:
        '200':
          description: The EPG for the stream.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '404':
          $ref: '#/components/responses/NotFound'
  /live_streams/{stream_id}/platforms:
    parameters:
      - $ref: '#/components/parameters/StreamId'
    post:
      operationId: addPlatform
      tags: [Live Streams]
      summary: Add a multistream platform destination
      description: Adds a destination (YouTube, Facebook, custom RTMP, etc.) that the stream is restreamed to.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PlatformCreate'
      responses:
        '201':
          description: The added platform destination.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Platform'
        '404':
          $ref: '#/components/responses/NotFound'
  /live_streams/{stream_id}/platforms/{platform_id}:
    parameters:
      - $ref: '#/components/parameters/StreamId'
      - $ref: '#/components/parameters/PlatformId'
    patch:
      operationId: updatePlatform
      tags: [Live Streams]
      summary: Update a platform destination
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PlatformCreate'
      responses:
        '200':
          description: The updated platform destination.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Platform'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      operationId: deletePlatform
      tags: [Live Streams]
      summary: Delete a platform destination
      responses:
        '204':
          description: The platform destination was deleted.
        '404':
          $ref: '#/components/responses/NotFound'
  /live_streams/{stream_id}/temporary_recordings:
    parameters:
      - $ref: '#/components/parameters/StreamId'
    get:
      operationId: getTemporaryRecordings
      tags: [Video Hosting]
      summary: Get temporary recordings
      description: Lists temporary cloud recordings of a stream (retained for a limited time before conversion to VOD).
      responses:
        '200':
          description: A list of temporary recordings.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Recording'
        '404':
          $ref: '#/components/responses/NotFound'
  /live_streams/{stream_id}/temporary_recordings/{recording_id}:
    parameters:
      - $ref: '#/components/parameters/StreamId'
      - $ref: '#/components/parameters/RecordingId'
    post:
      operationId: convertLiveToVod
      tags: [Video Hosting]
      summary: Convert live recording to VOD
      description: Converts a temporary live-stream recording into a permanent VOD asset (Live-to-VOD).
      responses:
        '201':
          description: The created VOD asset.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Video'
        '404':
          $ref: '#/components/responses/NotFound'
  /live_streams/{stream_id}/recordings:
    parameters:
      - $ref: '#/components/parameters/StreamId'
    get:
      operationId: getLiveToVodRecordings
      tags: [Video Hosting]
      summary: Get live-to-VOD recordings
      description: Lists the permanent VOD recordings produced from a stream.
      responses:
        '200':
          description: A list of VOD recordings.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Video'
        '404':
          $ref: '#/components/responses/NotFound'
  /sub_second_streams:
    get:
      operationId: listSubSecondStreams
      tags: [Sub-Second Streams]
      summary: List sub-second streams
      responses:
        '200':
          description: A list of sub-second streams.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/SubSecondStream'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: createSubSecondStream
      tags: [Sub-Second Streams]
      summary: Create a new sub-second stream
      description: Creates an ultra-low-latency (WebRTC) live stream.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SubSecondStreamCreate'
      responses:
        '201':
          description: The created sub-second stream.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubSecondStream'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /sub_second_streams/{stream_id}:
    parameters:
      - $ref: '#/components/parameters/StreamId'
    get:
      operationId: getSubSecondStream
      tags: [Sub-Second Streams]
      summary: Get a sub-second stream
      responses:
        '200':
          description: The requested sub-second stream.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubSecondStream'
        '404':
          $ref: '#/components/responses/NotFound'
    patch:
      operationId: updateSubSecondStream
      tags: [Sub-Second Streams]
      summary: Update a sub-second stream
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SubSecondStreamCreate'
      responses:
        '200':
          description: The updated sub-second stream.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubSecondStream'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      operationId: deleteSubSecondStream
      tags: [Sub-Second Streams]
      summary: Delete a sub-second stream
      responses:
        '204':
          description: The sub-second stream was deleted.
        '404':
          $ref: '#/components/responses/NotFound'
  /videos:
    get:
      operationId: listFolders
      tags: [Video Hosting]
      summary: List folders
      description: Lists the video hosting folders in your account.
      responses:
        '200':
          description: A list of folders.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Folder'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: createFolder
      tags: [Video Hosting]
      summary: Create a folder
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FolderCreate'
      responses:
        '201':
          description: The created folder.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Folder'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /videos/{folder_id}:
    parameters:
      - $ref: '#/components/parameters/FolderId'
    patch:
      operationId: updateFolder
      tags: [Video Hosting]
      summary: Update a folder
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FolderCreate'
      responses:
        '200':
          description: The updated folder.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Folder'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      operationId: deleteFolder
      tags: [Video Hosting]
      summary: Delete a folder
      responses:
        '204':
          description: The folder was deleted.
        '404':
          $ref: '#/components/responses/NotFound'
  /videos/{folder_id}/contents:
    parameters:
      - $ref: '#/components/parameters/FolderId'
    get:
      operationId: listFolderContents
      tags: [Video Hosting]
      summary: List contents in a folder
      responses:
        '200':
          description: A list of videos in the folder.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Video'
        '404':
          $ref: '#/components/responses/NotFound'
  /videos/{folder_id}/contents/{content_id}:
    parameters:
      - $ref: '#/components/parameters/FolderId'
      - $ref: '#/components/parameters/ContentId'
    delete:
      operationId: deleteFolderContent
      tags: [Video Hosting]
      summary: Delete content in a folder
      responses:
        '204':
          description: The content was deleted.
        '404':
          $ref: '#/components/responses/NotFound'
  /videos/{folder_id}/uploads:
    parameters:
      - $ref: '#/components/parameters/FolderId'
    post:
      operationId: createDirectUpload
      tags: [Video Hosting]
      summary: Create a direct upload URL
      description: Creates a direct upload URL for posting an on-demand video into the folder.
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UploadCreate'
      responses:
        '201':
          description: The created direct upload.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Upload'
        '404':
          $ref: '#/components/responses/NotFound'
  /activity_logs/stream/{stream_id}:
    parameters:
      - $ref: '#/components/parameters/StreamId'
    get:
      operationId: getStreamLogs
      tags: [Analytics]
      summary: Get stream activity logs
      responses:
        '200':
          description: A list of activity log entries for the stream.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/ActivityEntry'
        '404':
          $ref: '#/components/responses/NotFound'
  /activity_events/stream/{stream_id}:
    parameters:
      - $ref: '#/components/parameters/StreamId'
    get:
      operationId: getStreamEvents
      tags: [Analytics]
      summary: Get stream activity events
      responses:
        '200':
          description: A list of activity events for the stream.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/ActivityEntry'
        '404':
          $ref: '#/components/responses/NotFound'
  /webhook_endpoints:
    get:
      operationId: listWebhookEndpoints
      tags: [Webhooks]
      summary: Get webhook endpoints
      responses:
        '200':
          description: A list of webhook endpoints.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/WebhookEndpoint'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: createWebhookEndpoint
      tags: [Webhooks]
      summary: Create a webhook endpoint
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WebhookEndpointCreate'
      responses:
        '201':
          description: The created webhook endpoint.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookEndpoint'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /webhook_endpoints/{webhook_id}:
    parameters:
      - $ref: '#/components/parameters/WebhookId'
    patch:
      operationId: updateWebhookEndpoint
      tags: [Webhooks]
      summary: Update a webhook endpoint
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WebhookEndpointCreate'
      responses:
        '200':
          description: The updated webhook endpoint.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookEndpoint'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      operationId: deleteWebhookEndpoint
      tags: [Webhooks]
      summary: Delete a webhook endpoint
      responses:
        '204':
          description: The webhook endpoint was deleted.
        '404':
          $ref: '#/components/responses/NotFound'
components:
  securitySchemes:
    apiToken:
      type: apiKey
      in: header
      name: authorization
      description: >-
        API token issued from the Castr account settings API section
        (https://castr.com/app/manage/api), sent in the authorization header.
  parameters:
    StreamId:
      name: stream_id
      in: path
      required: true
      description: The unique identifier of the stream.
      schema:
        type: string
    PlatformId:
      name: platform_id
      in: path
      required: true
      description: The unique identifier of the platform destination.
      schema:
        type: string
    RecordingId:
      name: recording_id
      in: path
      required: true
      description: The unique identifier of the temporary recording.
      schema:
        type: string
    FolderId:
      name: folder_id
      in: path
      required: true
      description: The unique identifier of the video folder.
      schema:
        type: string
    ContentId:
      name: content_id
      in: path
      required: true
      description: The unique identifier of the content item.
      schema:
        type: string
    WebhookId:
      name: webhook_id
      in: path
      required: true
      description: The unique identifier of the webhook endpoint.
      schema:
        type: string
  responses:
    Unauthorized:
      description: Missing or invalid API token.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: The requested resource was not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  schemas:
    LiveStream:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        enabled:
          type: boolean
        ingest:
          type: object
          properties:
            rtmp_url:
              type: string
            srt_url:
              type: string
            stream_key:
              type: string
        playback:
          type: object
          properties:
            hls_url:
              type: string
            embed_url:
              type: string
        platforms:
          type: array
          items:
            $ref: '#/components/schemas/Platform'
        created_at:
          type: string
          format: date-time
    LiveStreamCreate:
      type: object
      required: [name]
      properties:
        name:
          type: string
        enabled:
          type: boolean
        record:
          type: boolean
          description: Enable cloud recording of the stream.
    LiveStreamUpdate:
      type: object
      properties:
        name:
          type: string
        enabled:
          type: boolean
        record:
          type: boolean
    Platform:
      type: object
      properties:
        id:
          type: string
        type:
          type: string
          description: Destination type (e.g. youtube, facebook, custom_rtmp).
        name:
          type: string
        rtmp_url:
          type: string
        stream_key:
          type: string
        enabled:
          type: boolean
    PlatformCreate:
      type: object
      required: [type]
      properties:
        type:
          type: string
        name:
          type: string
        rtmp_url:
          type: string
        stream_key:
          type: string
        enabled:
          type: boolean
    StreamStats:
      type: object
      properties:
        online:
          type: boolean
        duration:
          type: integer
          description: Current session duration in seconds.
        bitrate:
          type: integer
        codec:
          type: string
        resolution:
          type: string
        viewers:
          type: integer
    SubSecondStream:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        enabled:
          type: boolean
        ingest:
          type: object
          properties:
            rtmp_url:
              type: string
            webrtc_url:
              type: string
        playback:
          type: object
          properties:
            webrtc_url:
              type: string
            embed_url:
              type: string
    SubSecondStreamCreate:
      type: object
      required: [name]
      properties:
        name:
          type: string
        enabled:
          type: boolean
    Folder:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        item_count:
          type: integer
        created_at:
          type: string
          format: date-time
    FolderCreate:
      type: object
      required: [name]
      properties:
        name:
          type: string
    Video:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        folder_id:
          type: string
        status:
          type: string
          description: Processing status (e.g. uploading, processing, ready).
        duration:
          type: integer
        size:
          type: integer
        playback:
          type: object
          properties:
            hls_url:
              type: string
            embed_url:
              type: string
        created_at:
          type: string
          format: date-time
    Upload:
      type: object
      properties:
        id:
          type: string
        upload_url:
          type: string
          description: Direct URL to PUT/POST the video file to.
        expires_at:
          type: string
          format: date-time
    UploadCreate:
      type: object
      properties:
        name:
          type: string
        size:
          type: integer
    Recording:
      type: object
      properties:
        id:
          type: string
        stream_id:
          type: string
        status:
          type: string
        duration:
          type: integer
        expires_at:
          type: string
          format: date-time
    ActivityEntry:
      type: object
      properties:
        id:
          type: string
        type:
          type: string
        message:
          type: string
        timestamp:
          type: string
          format: date-time
    WebhookEndpoint:
      type: object
      properties:
        id:
          type: string
        url:
          type: string
        events:
          type: array
          items:
            type: string
        enabled:
          type: boolean
        created_at:
          type: string
          format: date-time
    WebhookEndpointCreate:
      type: object
      required: [url]
      properties:
        url:
          type: string
        events:
          type: array
          items:
            type: string
        enabled:
          type: boolean
    Error:
      type: object
      properties:
        error:
          type: string
        message:
          type: string