confcall Recordings API

openapi: 3.2.0
info:
  title: Confcall App Recordings API
  version: post-phase-1
  x-canonical-url: https://docs.confcall.app/openapi/confcall-control-plane.json
  description: 'Operations tagged Recordings across 2 of this provider''s published API definitions: confcall-control-plane.json, confcall-app-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://meet.confcall.app
  description: Production
security:
- ApiKeyAuth: []
- OAuth2ClientCredentials:
  - confcall:rooms
  - confcall:history
tags:
- name: Recordings
paths:
  /api/recordings:
    get:
      operationId: listRecordings
      summary: List recordings the caller may view
      x-auth: jwtOrApiKey
      x-auth-note: 'JWT: union of rooms the user owns/co-hosts/was invited to. sk_ key: every room owned by the key''s account.'
      parameters:
      - name: roomId
        in: query
        required: false
        schema:
          type: string
      responses:
        '200':
          description: Recordings the caller may view
          content:
            application/json:
              schema:
                type: object
                properties:
                  recordings:
                    type: array
                    items:
                      $ref: '#/components/schemas/Recording'
        '403':
          description: roomId given but caller has no access to that room
      tags:
      - Recordings
    servers:
    - url: https://meet.confcall.app
      description: Production
  /api/recordings/{id}:
    get:
      operationId: getRecording
      summary: Recording detail
      x-auth: jwt
      x-auth-note: JWT-only — not sk_-callable. Use listRecordings or streamRecording for API-key integrations.
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Recording detail
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Recording'
        '403':
          description: Caller has no access to this recording
        '404':
          description: Recording not found
      tags:
      - Recordings
    servers:
    - url: https://meet.confcall.app
      description: Production
  /api/recordings/{id}/stream:
    get:
      operationId: streamRecording
      summary: Get a time-limited playback reference for a recording
      x-auth: jwtOrApiKey
      x-auth-note: 'sk_ key: any recording owned by its own account. Returns a pre-signed URL for S3/Azure-backed recordings, or a signed token for the legacy local-file endpoint.'
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Playback reference; replayOutOfBand=true (url null) for BYOS-restricted playback
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StreamReference'
        '403':
          description: Caller/key does not own this recording
        '404':
          description: Recording not found
      tags:
      - Recordings
    servers:
    - url: https://meet.confcall.app
      description: Production
  /api/recordings/{id}/download:
    get:
      operationId: getRecordingDownload
      summary: Get a downloadable reference for a recording
      x-auth: jwt
      x-auth-note: JWT-only — not sk_-callable.
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Download reference; replayOutOfBand=true (url null) for BYOS-restricted downloads
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StreamReference'
        '403':
          description: Caller has no access to this recording
        '404':
          description: Recording not found
      tags:
      - Recordings
    servers:
    - url: https://meet.confcall.app
      description: Production
  /api/recordings/{id}/file:
    get:
      operationId: getRecordingFile
      summary: Stream a legacy/local recording file by signed token
      x-auth: public
      x-auth-note: Authorization is the signed `token` query parameter itself (from streamRecording/getRecordingDownload), not a bearer credential.
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      - name: token
        in: query
        required: false
        schema:
          type: string
      responses:
        '200':
          description: Recording file bytes
        '401':
          description: Missing/invalid/expired token
        '404':
          description: Recording not found
      tags:
      - Recordings
    servers:
    - url: https://meet.confcall.app
      description: Production
components:
  schemas:
    StreamReference:
      type: object
      properties:
        url:
          type:
          - string
          - 'null'
        expiresAt:
          type: string
          format: date-time
        replayOutOfBand:
          type: boolean
        storageProvider:
          type:
          - string
          - 'null'
        storageLocation:
          type:
          - string
          - 'null'
    Recording:
      type: object
      properties:
        id:
          type: string
          format: uuid
        egressId:
          type: string
        roomId:
          type: string
        roomName:
          type: string
        source:
          type: string
        startedAt:
          type: string
          format: date-time
        endedAt:
          type:
          - string
          - 'null'
          format: date-time
        durationSeconds:
          type:
          - number
          - 'null'
          format: double
        sizeBytes:
          type:
          - integer
          - 'null'
          format: int64
        status:
          type: string
        requestedBy:
          type:
          - string
          - 'null'
        storageProvider:
          type:
          - string
          - 'null'
        storageLocation:
          type:
          - string
          - 'null'
        sessionId:
          type:
          - string
          - 'null'
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: A confcall secret (sk_live_/sk_test_) API key. Publishable (pk_) keys are rejected on every route documented here.
    OAuth2ClientCredentials:
      type: oauth2
      description: 'OAuth 2.0 client-credentials grant. Exchange a client id/secret at the token URL for a short-lived bearer JWT and send it as `Authorization: Bearer <token>`. Operations with x-auth jwtOrApiKey accept either this or ApiKeyAuth; x-auth jwt operations need a user-context token.'
      flows:
        clientCredentials:
          tokenUrl: https://auth.confcall.app/oauth/token
          scopes:
            confcall:rooms: Manage rooms and invite/remove the AI agent
            confcall:history: Read meeting artifacts (transcripts, summaries, action items)
x-refined-from:
- confcall-control-plane.json
- confcall-app-openapi.yml