openapi.yaml

openapi: 3.0.3
info:
  title: Convertrilo Encode API
  version: "1.0.0"
  description: |
    JWT-protected API for creating and managing encode jobs. Supports browser-upload, direct URL ingest, or S3 source.
    Public endpoints are limited and rate-limited.

    Swagger auth:
    1. Create an API key in Dashboard -> Developer.
    2. Click Authorize in these docs.
    3. Paste the raw API key into ApiKeyAuth.
    4. Protected endpoints can then be executed from Swagger.

    API integrations should keep Convertrilo API keys and customer storage credentials on the server.
    Google Drive folder automation uses encrypted customer-owned service-account credentials.
    Dashboard Google Drive access is separate and uses Google Picker with the drive.file scope.
    
    Official TypeScript SDK: https://www.npmjs.com/package/@convertrilo/sdk
    SDK source and examples: https://github.com/serkandrgn/convertrilo-js
    Interactive docs: https://api.convertrilo.com/docs
externalDocs:
  description: Convertrilo TypeScript SDK
  url: https://github.com/serkandrgn/convertrilo-js
servers:
  - url: /
    description: Same origin as these docs
  - url: https://api.convertrilo.com
    description: Production
components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
  parameters:
    IdempotencyKey:
      in: header
      name: Idempotency-Key
      required: false
      schema:
        type: string
        maxLength: 255
      description: Optional key for safely retrying job creation requests. Reusing the same key with the same request body replays the original response; reusing it with a different body returns 409.
  schemas:
    AuthLoginRequest:
      type: object
      required: [email, password]
      properties:
        email: { type: string, format: email }
        password: { type: string, minLength: 8 }
    AuthLoginResponse:
      type: object
      properties:
        accessToken: { type: string }
        refreshToken: { type: string }
    TokenBalanceResponse:
      type: object
      properties:
        available: { type: number }
        reserved: { type: number }
        trialGrantRemaining: { type: number }
        trialExpiresAt: { type: string, format: date-time, nullable: true }
    TokenReserveRequest:
      type: object
      required: [jobId, amount]
      properties:
        jobId: { type: string, format: uuid }
        amount: { type: integer, minimum: 1 }
    TokenDeductRequest:
      type: object
      required: [jobId, amount]
      properties:
        jobId: { type: string, format: uuid }
        amount: { type: integer, minimum: 1 }
    CompatibilityWarning:
      type: object
      required: [code, message]
      properties:
        code: { type: string }
        message: { type: string }
        severity:
          type: string
          enum: [info, warning, error]
    MediaColorProbe:
      type: object
      properties:
        kind:
          type: string
          enum: [sdr, hdr10, hlg, unknown, conflicting]
        primaries: { type: string, nullable: true }
        transfer: { type: string, nullable: true }
        matrix: { type: string, nullable: true }
        range: { type: string, nullable: true }
        notes:
          type: array
          items: { type: string }
    MediaProbe:
      type: object
      properties:
        durationSec: { type: number }
        codec: { type: string, nullable: true }
        width: { type: integer, nullable: true }
        height: { type: integer, nullable: true }
        fps: { type: number, nullable: true }
        audioStreams: { type: integer }
        audioCodec: { type: string, nullable: true }
        container: { type: string, nullable: true }
        color:
          $ref: "#/components/schemas/MediaColorProbe"
    JobCreateRequest:
      type: object
      required: [codec, resolution, fps]
      properties:
        externalId:
          type: string
          maxLength: 255
          description: Your stable job identifier for reconciliation in status responses and webhooks.
        metadata:
          type: object
          additionalProperties: true
          description: Integration-owned JSON object returned in status responses and webhooks.
        codec:
          type: string
          enum: [h264, h265, av1]
        resolution:
          type: string
          enum: [480p, 720p, 1080p, 1440p, 2160p, 4320p]
        fps:
          type: integer
          minimum: 1
          maximum: 240
        container:
          type: string
          enum: [mp4, mkv, webm, mov]
          default: mp4
        preset:
          type: string
          enum: [fast, standard, slow]
          default: fast
        bitrateTier:
          type: string
          enum: [low, medium, high]
          default: medium
        passes:
          type: integer
          enum: [1, 2]
          default: 1
          description: Requested encoding passes. When optimize is vmaf, the API uses and bills one effective final pass.
        policy:
          type: string
          enum: [fastest, gpu_first, gpu_only]
          default: gpu_first
        quality:
          type: string
          enum: [good, better, best]
        audioPolicy:
          type: string
          enum: [auto, copy, transcode-aac, strip]
          default: transcode-aac
        frameRatePolicy:
          type: string
          enum: [preserve, cap, force]
          default: force
        scalePolicy:
          type: string
          enum: [no-upscale, allow-upscale, downscale-only]
          default: no-upscale
        sourceUrl:
          type: string
          format: uri
          description: Optional direct HTTP(S) ingest. When provided, upload URL is not returned.
        originalFilename:
          type: string
          description: Optional source filename used to generate human-readable output download names.
        sourceS3:
          type: object
          properties:
            bucket: { type: string }
            key: { type: string }
            endpoint: { type: string }
            region: { type: string }
            accessKeyId: { type: string }
            secretAccessKey: { type: string }
            forcePathStyle: { type: boolean }
        confirm: { type: boolean, default: false }
        optimize: { type: string, enum: [none, vmaf] }
        vmafTarget: { type: number, minimum: 50, maximum: 99 }
    JobCreateResponse:
      type: object
      required: [jobId, upload, output]
      properties:
        jobId: { type: string }
        externalId: { type: string, nullable: true }
        metadata:
          type: object
          additionalProperties: true
          nullable: true
        sourceFilename: { type: string, nullable: true }
        outputFilename: { type: string, nullable: true }
        status:
          type: string
          description: Present when the job is auto-confirmed and queued.
        upload:
          nullable: true
          type: object
          properties:
            url: { type: string }
            key: { type: string }
        output:
          type: object
          properties:
            key: { type: string }
            publicUrl: { type: string }
        estimate:
          type: object
          properties:
            neu: { type: number }
            totalNeu: { type: number }
            reserved: { type: number }
            requestedPasses: { type: integer, enum: [1, 2] }
            effectivePasses:
              type: integer
              enum: [1, 2]
              description: Pass count actually used for pricing and encoding. VMAF requests use 1.
        warnings:
          type: array
          items:
            $ref: "#/components/schemas/CompatibilityWarning"
    JobFilesDeleteResponse:
      type: object
      required: [ok, jobId, objectsDeleted, jobRetained]
      properties:
        ok: { type: boolean }
        jobId: { type: string }
        objectsDeleted:
          type: integer
          minimum: 0
        jobRetained:
          type: boolean
          enum: [true]
          description: The job and billing history remain available after managed files are deleted.
    JobCancelResponse:
      type: object
      required: [ok]
      properties:
        ok: { type: boolean }
        released:
          type: number
          description: Actual reserved NEU returned to the account.
        note:
          type: string
          description: Present when cancellation is a terminal-state no-op.
    ProbeDurationResponse:
      type: object
      properties:
        durationSec: { type: number }
        durationMinutes: { type: number }
    ApproveUnifiedRequest:
      type: object
      properties:
        codec: { type: string, enum: [h264, h265, av1] }
        resolution: { type: string }
        fps: { type: integer }
        preset: { type: string, enum: [fast, standard, slow] }
        bitrateTier: { type: string, enum: [low, medium, high] }
        passes:
          type: integer
          enum: [1, 2]
          description: Requested passes. Ignored for execution and billing when optimize is vmaf.
        policy: { type: string, enum: [gpu_only, gpu_first, fastest] }
        container: { type: string, enum: [mp4, mkv, webm, mov] }
        quality: { type: string, enum: [good, better, best] }
        optimize: { type: string, enum: [none, vmaf] }
        vmafTarget: { type: number, minimum: 50, maximum: 99 }
        audioPolicy: { type: string, enum: [auto, copy, transcode-aac, strip] }
        frameRatePolicy: { type: string, enum: [preserve, cap, force] }
        scalePolicy:
          { type: string, enum: [no-upscale, allow-upscale, downscale-only] }
    ApproveUnifiedResponse:
      type: object
      properties:
        ok: { type: boolean }
        estimate:
          type: object
          properties:
            perMinuteNeu: { type: number }
            durationSec: { type: number }
            totalNeu: { type: number }
            reserved: { type: number }
            requestedPasses: { type: integer, enum: [1, 2] }
            effectivePasses:
              type: integer
              enum: [1, 2]
              description: Pass count used for pricing and execution.
        warnings:
          type: array
          items:
            $ref: "#/components/schemas/CompatibilityWarning"
    ConfirmRequest:
      type: object
      properties:
        container: { type: string, enum: [mp4, mkv, webm, mov] }
        quality: { type: string, enum: [good, better, best] }
        optimize: { type: string, enum: [none, vmaf] }
        vmafTarget: { type: number, minimum: 1, maximum: 100 }
        audioPolicy: { type: string, enum: [auto, copy, transcode-aac, strip] }
        frameRatePolicy: { type: string, enum: [preserve, cap, force] }
        scalePolicy:
          { type: string, enum: [no-upscale, allow-upscale, downscale-only] }
    ConfirmResponse:
      type: object
      properties:
        ok: { type: boolean }
    StatusResponse:
      type: object
      properties:
        id: { type: string }
        externalId: { type: string, nullable: true }
        metadata:
          type: object
          additionalProperties: true
          nullable: true
        sourceFilename: { type: string, nullable: true }
        outputFilename: { type: string, nullable: true }
        status: { type: string }
        ingest: { type: string, nullable: true }
        container: { type: string, enum: [mp4, mkv, webm, mov], nullable: true }
        quality: { type: string, enum: [good, better, best], nullable: true }
        output:
          nullable: true
          type: object
          properties:
            key: { type: string }
            publicUrl: { type: string }
        downloadUrl: { type: string, nullable: true }
        encoder: { type: string, nullable: true }
        pct: { type: number, nullable: true }
        createdAt: { type: string, format: date-time }
        startedAt: { type: string, format: date-time, nullable: true }
        finishedAt: { type: string, format: date-time, nullable: true }
        failureMessage: { type: string, nullable: true }
        requestedExecution:
          type: object
          additionalProperties: true
          nullable: true
        effectiveExecution:
          type: object
          additionalProperties: true
          nullable: true
        sourceProbe:
          $ref: "#/components/schemas/MediaProbe"
          nullable: true
        outputProbe:
          $ref: "#/components/schemas/MediaProbe"
          nullable: true
        warnings:
          type: array
          items:
            $ref: "#/components/schemas/CompatibilityWarning"
        billingSummary:
          type: object
          additionalProperties: true
          nullable: true
        executionReport:
          type: object
          additionalProperties: true
          nullable: true
    ErrorResponse:
      type: object
      required: [code, message]
      properties:
        code:
          type: string
          description: Stable machine-readable error code. Branch on this instead of parsing `message`.
          enum:
            - invalid_api_key
            - api_key_expired
            - user_not_found
            - account_banned
            - missing_required_scope
            - invalid_request
            - invalid_body
            - invalid_url
            - url_ingest_disabled
            - url_host_blocked
            - signed_url_required
            - host_not_resolvable
            - private_ip_blocked
            - missing_content_length
            - file_too_large
            - unsupported_content_type
            - probe_failed
            - insufficient_tokens
            - idempotency_conflict
            - idempotency_in_progress
            - rate_limit_exceeded
            - not_found
            - forbidden
            - deprecated_dropbox
            - google_drive_not_connected
            - dropbox_not_connected
            - no_video_files_found
            - webhook_limit_exceeded
            - webhook_not_found
            - no_updates_provided
            - output_not_available
            - job_active
            - job_files_delete_failed
        message: { type: string }
        issues:
          description: Validation details for `invalid_body`.
        requiredScope: { type: string }
        required: { type: number }
        available: { type: number }

    # Bulk Jobs
    BulkCreateRequest:
      type: object
      required: [jobs]
      properties:
        jobs:
          type: array
          items:
            $ref: "#/components/schemas/JobCreateRequest"
        settings:
          type: object
          required: []
          properties:
            failFast: { type: boolean, default: false }
            dryRun: { type: boolean, default: false }
            confirm: { type: boolean, default: false }
            container: { type: string, enum: [mp4, mkv, webm, mov] }
            quality: { type: string, enum: [good, better, best] }
            optimize: { type: string, enum: [none, vmaf] }
            vmafTarget: { type: number, minimum: 50, maximum: 99 }
            audioPolicy:
              { type: string, enum: [auto, copy, transcode-aac, strip] }
            frameRatePolicy: { type: string, enum: [preserve, cap, force] }
            scalePolicy:
              {
                type: string,
                enum: [no-upscale, allow-upscale, downscale-only],
              }
    BulkCreateResponse:
      type: object
      properties:
        totalJobs: { type: integer }
        totalEstimatedNeu: { type: number }
        reserved: { type: number }
        jobs:
          type: array
          items:
            type: object
            properties:
              index: { type: integer }
              jobId: { type: string, format: uuid }
              externalId: { type: string, nullable: true }
              metadata:
                type: object
                additionalProperties: true
                nullable: true
              status: { type: string }
              error: { type: string }
              estimate:
                type: object
                properties:
                  neu: { type: number }
              warnings:
                type: array
                items:
                  $ref: "#/components/schemas/CompatibilityWarning"
        warnings:
          type: array
          items:
            $ref: "#/components/schemas/CompatibilityWarning"
    BulkStatusResponse:
      type: object
      properties:
        jobs:
          type: array
          items:
            $ref: "#/components/schemas/StatusResponse"
        missing:
          type: array
          items: { type: string }
    BulkConfirmRequest:
      type: object
      required: [jobIds]
      properties:
        jobIds:
          type: array
          items: { type: string, format: uuid }
        settings:
          type: object
          properties:
            container: { type: string, enum: [mp4, mkv, webm, mov] }
            quality: { type: string, enum: [good, better, best] }
            audioPolicy:
              { type: string, enum: [auto, copy, transcode-aac, strip] }
            frameRatePolicy: { type: string, enum: [preserve, cap, force] }
            scalePolicy:
              {
                type: string,
                enum: [no-upscale, allow-upscale, downscale-only],
              }

    # Encode Presets
    EncodePresetSettings:
      type: object
      required:
        - codec
        - resolution
        - fps
        - preset
        - bitrateTier
        - passes
        - policy
        - container
        - quality
        - optimize
        - vmafTarget
        - audioPolicy
        - frameRatePolicy
        - scalePolicy
      properties:
        codec: { type: string, enum: [h264, h265, av1] }
        resolution:
          { type: string, enum: [480p, 720p, 1080p, 1440p, 2160p, 4320p] }
        fps: { type: integer, minimum: 1, maximum: 240 }
        preset: { type: string, enum: [fast, standard, slow] }
        bitrateTier: { type: string, enum: [low, medium, high] }
        passes: { type: integer, enum: [1, 2] }
        policy: { type: string, enum: [gpu_only, gpu_first, fastest] }
        container: { type: string, enum: [mp4, mkv, webm, mov] }
        quality: { type: string, enum: [good, better, best] }
        optimize: { type: string, enum: [none, vmaf] }
        vmafTarget: { type: integer, minimum: 50, maximum: 99 }
        audioPolicy: { type: string, enum: [auto, copy, transcode-aac, strip] }
        frameRatePolicy: { type: string, enum: [preserve, cap, force] }
        scalePolicy:
          { type: string, enum: [no-upscale, allow-upscale, downscale-only] }
    EncodePresetCreateRequest:
      type: object
      required: [name, settings]
      properties:
        name: { type: string, minLength: 1, maxLength: 255 }
        settings:
          $ref: "#/components/schemas/EncodePresetSettings"
    EncodePresetUpdateRequest:
      type: object
      properties:
        name: { type: string, minLength: 1, maxLength: 255 }
        settings:
          $ref: "#/components/schemas/EncodePresetSettings"
    EncodePresetResponse:
      type: object
      properties:
        id: { type: string, format: uuid }
        name: { type: string }
        settings:
          $ref: "#/components/schemas/EncodePresetSettings"
        createdAt: { type: string, format: date-time }
        updatedAt: { type: string, format: date-time }
    EncodePresetListResponse:
      type: object
      properties:
        presets:
          type: array
          items:
            $ref: "#/components/schemas/EncodePresetResponse"

    # Output Destinations
    OutputDestinationConfig:
      oneOf:
        - type: object
          required: [type]
          properties:
            type: { type: string, enum: [cdn] }
            outputExpiry: { type: integer, minimum: 3600, maximum: 604800 }
        - type: object
          required: [type, credentialId]
          properties:
            type: { type: string, enum: [s3] }
            credentialId: { type: string, format: uuid }
            keyPrefix: { type: string, maxLength: 1024 }
        - type: object
          required: [type, folderId]
          properties:
            type: { type: string, enum: [google-drive] }
            credentialId: { type: string, format: uuid }
            folderId: { type: string, minLength: 1 }
            folderName: { type: string, maxLength: 255 }
            fileNameTemplate: { type: string, maxLength: 255 }
      discriminator:
        propertyName: type
    OutputDestinationCreateRequest:
      type: object
      required: [name, config]
      properties:
        name: { type: string, minLength: 1, maxLength: 255 }
        config:
          $ref: "#/components/schemas/OutputDestinationConfig"
    OutputDestinationUpdateRequest:
      type: object
      properties:
        name: { type: string, minLength: 1, maxLength: 255 }
        config:
          $ref: "#/components/schemas/OutputDestinationConfig"
    OutputDestinationResponse:
      type: object
      properties:
        id: { type: string, format: uuid }
        name: { type: string }
        destinationType:
          type: string
          enum: [cdn, s3, google-drive]
        config:
          $ref: "#/components/schemas/OutputDestinationConfig"
        createdAt: { type: string, format: date-time }
        updatedAt: { type: string, format: date-time }
    OutputDestinationListResponse:
      type: object
      properties:
        destinations:
          type: array
          items:
            $ref: "#/components/schemas/OutputDestinationResponse"

    # API Keys
    ApiKeyCreateRequest:
      type: object
      required: [name]
      properties:
        name: { type: string }
        scopes:
          type: array
          description: |
            Requested API key scopes. Use the minimum scopes needed:
            `jobs:create`, `jobs:read`, `jobs:cancel`, `tokens:read`,
            `webhooks:manage`, and `credentials:manage` for saved storage credential management.
          items:
            type: string
            enum:
              - jobs:create
              - jobs:read
              - jobs:cancel
              - tokens:read
              - tokens:write
              - webhooks:manage
              - credentials:manage
        expiresInDays: { type: integer, minimum: 1, maximum: 365 }
    ApiKeyResponse:
      type: object
      properties:
        id: { type: string, format: uuid }
        name: { type: string }
        key: { type: string, description: "Raw key, only returned on creation" }
        prefix: { type: string }
        scopes:
          type: array
          items:
            type: string
            enum:
              - jobs:create
              - jobs:read
              - jobs:cancel
              - tokens:read
              - tokens:write
              - webhooks:manage
              - credentials:manage
        expiresAt: { type: string, format: date-time, nullable: true }
        createdAt: { type: string, format: date-time }
    ApiKeyListResponse:
      type: object
      properties:
        keys:
          type: array
          items:
            $ref: "#/components/schemas/ApiKeyResponse"

    # Webhooks
    WebhookCreateRequest:
      type: object
      required: [url, events]
      properties:
        url: { type: string, format: uri }
        events:
          type: array
          items:
            type: string
            enum:
              [
                job.created,
                job.queued,
                job.running,
                job.completed,
                job.failed,
                job.canceled,
              ]
    WebhookUpdateRequest:
      type: object
      properties:
        url: { type: string, format: uri }
        events:
          type: array
          items:
            type: string
            enum:
              [
                job.created,
                job.queued,
                job.running,
                job.completed,
                job.failed,
                job.canceled,
              ]
        isActive: { type: boolean }
    WebhookResponse:
      type: object
      properties:
        id: { type: string, format: uuid }
        url: { type: string }
        events:
          type: array
          items: { type: string }
        secret:
          {
            type: string,
            description: "HMAC secret, only returned on creation",
          }
        isActive: { type: boolean }
        failureCount: { type: integer }
        lastTriggeredAt: { type: string, format: date-time, nullable: true }
        lastFailedAt: { type: string, format: date-time, nullable: true }
        createdAt: { type: string, format: date-time }
    WebhookListResponse:
      type: object
      properties:
        webhooks:
          type: array
          items:
            $ref: "#/components/schemas/WebhookResponse"
    WebhookDeliveryResponse:
      type: object
      properties:
        id: { type: string, format: uuid }
        webhookId: { type: string, format: uuid }
        event: { type: string }
        jobId: { type: string, format: uuid, nullable: true }
        status: { type: string, enum: [success, failed] }
        statusCode: { type: integer, nullable: true }
        durationMs: { type: integer, nullable: true }
        responseBody:
          type: string
          nullable: true
          description: Response body captured from the receiver, truncated to 2048 characters.
        error:
          type: string
          nullable: true
          description: Network, timeout, or delivery error, truncated to 2048 characters.
        attempt: { type: integer }
        nextRetryAt: { type: string, format: date-time, nullable: true }
        retriedAt: { type: string, format: date-time, nullable: true }
        createdAt: { type: string, format: date-time }
    WebhookDeliveryListResponse:
      type: object
      properties:
        deliveries:
          type: array
          items:
            $ref: "#/components/schemas/WebhookDeliveryResponse"

    # On-Demand Encoding
    S3Output:
      type: object
      required: [bucket, key]
      properties:
        bucket: { type: string }
        key: { type: string }
        endpoint: { type: string, format: uri }
        region: { type: string }
        accessKeyId: { type: string }
        secretAccessKey: { type: string, format: password }
        forcePathStyle: { type: boolean }
    S3FolderSource:
      type: object
      description: Customer-owned S3-compatible folder source. Credentials should allow listing the prefix and reading objects.
      required: [bucket]
      properties:
        bucket: { type: string }
        prefix:
          type: string
          default: ""
          description: Prefix to crawl. Only files with video extensions are queued.
        endpoint:
          type: string
          format: uri
          description: Optional S3-compatible endpoint, for example Cloudflare R2, MinIO, or object storage providers.
        region: { type: string }
        accessKeyId:
          type: string
          description: Optional source access key. Omit only when your backend/runtime provides credentials another way.
        secretAccessKey: { type: string, format: password }
        forcePathStyle: { type: boolean, default: true }
    S3FolderOutput:
      type: object
      description: Customer-owned S3-compatible output destination. Credentials should allow writing encoded objects.
      required: [bucket]
      properties:
        bucket: { type: string }
        prefix:
          type: string
          default: outputs/
          description: Output key prefix. The source file name is appended to this prefix.
        endpoint:
          type: string
          format: uri
          description: Optional S3-compatible endpoint, for example Cloudflare R2, MinIO, or object storage providers.
        region: { type: string }
        accessKeyId:
          type: string
          description: Optional output access key. Omit only when your backend/runtime provides credentials another way.
        secretAccessKey: { type: string, format: password }
        forcePathStyle: { type: boolean, default: true }
    GoogleDriveFolderSource:
      type: object
      description: Google Drive folder source for headless API integrations. The saved service account must have Reader access to the folder.
      required: [folderId, credentialId]
      properties:
        folderId: { type: string }
        credentialId: { type: string, format: uuid }
    GoogleDriveSelectedFile:
      type: object
      required: [fileId, fileName]
      properties:
        fileId: { type: string }
        fileName: { type: string }
        mimeType: { type: string }
    GoogleDriveOutput:
      type: object
      description: Google Drive output destination. SDK callers provide a saved service-account credential ID; dashboard callers use their connected drive.file grant.
      required: [folderId]
      properties:
        folderId: { type: string }
        fileName: { type: string }
        credentialId: { type: string, format: uuid }
    GoogleDriveCredentialCreate:
      type: object
      required: [name, serviceAccount]
      properties:
        name: { type: string }
        serviceAccount:
          oneOf:
            - type: string
              description: Raw Google service-account JSON.
            - type: object
              additionalProperties: true
    GoogleDriveCredential:
      type: object
      properties:
        id: { type: string, format: uuid }
        name: { type: string }
        clientEmail: { type: string }
        projectId: { type: string, nullable: true }
        createdAt: { type: string, format: date-time }
    OnDemandEncodeRequest:
      type: object
      required: [sourceUrl]
      properties:
        sourceUrl: { type: string, format: uri }
        externalId:
          type: string
          maxLength: 255
          description: Your stable job identifier for reconciliation in status responses and webhooks.
        metadata:
          type: object
          additionalProperties: true
          description: Integration-owned JSON object returned in status responses and webhooks.
        codec: { type: string, enum: [h264, h265, av1], default: h264 }
        resolution:
          {
            type: string,
            enum: [480p, 720p, 1080p, 1440p, 2160p],
            default: 1080p,
          }
        fps: { type: integer, minimum: 1, maximum: 120, default: 30 }
        preset: { type: string, enum: [fast, standard, slow], default: fast }
        bitrateTier:
          { type: string, enum: [low, medium, high], default: medium }
        container: { type: string, enum: [mp4, mkv, webm, mov], default: mp4 }
        jobMode:
          type: string
          enum: [encode, hls]
          default: encode
          description: Use `hls` to create an HLS VOD package instead of a single output file. HLS output is H.264/AAC SDR; supported non-H.264/non-AAC source codecs are transcoded into the package.
        packageType:
          type: string
          enum: [hls]
          description: Alternative explicit package selector for HLS jobs.
        hls:
          type: object
          properties:
            segmentDuration:
              type: integer
              minimum: 2
              maximum: 10
              default: 6
            audioTrackIndex:
              type: integer
              minimum: 0
              maximum: 7
            gopSeconds:
              type: integer
              minimum: 1
              maximum: 10
            poster:
              type: boolean
            posterAtSec:
              type: number
              minimum: 0
            thumbnails:
              type: object
              properties:
                enabled: { type: boolean }
                intervalSec:
                  type: integer
                  minimum: 2
                  maximum: 60
                width:
                  type: integer
                  minimum: 96
                  maximum: 320
            subtitleWebvttUrl:
              type: string
              format: uri
            subtitleLanguage:
              type: string
              minLength: 2
              maxLength: 16
            subtitleName:
              type: string
              minLength: 1
              maxLength: 80
            privatePlayback:
              type: boolean
            renditions:
              type: array
              minItems: 2
              maxItems: 3
              items:
                type: object
                required: [height]
                properties:
                  height: { type: integer, enum: [360, 480, 540, 720, 1080] }
                  videoBitrate:
                    type: string
                    pattern: "^\\d+k$"
                  audioBitrate:
                    type: string
                    pattern: "^\\d+k$"
        quality: { type: string, enum: [good, better, best], default: better }
        audioPolicy:
          {
            type: string,
            enum: [auto, copy, transcode-aac, strip],
            default: transcode-aac,
          }
        frameRatePolicy:
          { type: string, enum: [preserve, cap, force], default: force }
        scalePolicy:
          {
            type: string,
            enum: [no-upscale, allow-upscale, downscale-only],
            default: no-upscale,
          }
        priority: { type: string, enum: [normal, high], default: normal }
        outputExpiry:
          { type: integer, minimum: 3600, maximum: 604800, default: 86400 }
        webhook:
          type: string
          format: uri
          description: Optional one-off terminal callback URL for this job. Best-effort and unsigned. Use managed webhooks for signed HMAC delivery.
        outputS3:
          $ref: "#/components/schemas/S3Output"
        outputGoogleDrive:
          $ref: "#/components/schemas/GoogleDriveOutput"
        outputDropbox:
          deprecated: true
          description: Deprecated. Requests using Dropbox output return 410 Gone.
          type: object
          properties:
            path: { type: string }
            accessToken: { type: string }
    OnDemandEncodeResponse:
      type: object
      required: [jobId, status, statusUrl]
      properties:
        jobId: { type: string, format: uuid }
        externalId: { type: string, nullable: true }
        metadata:
          type: object
          additionalProperties: true
          nullable: true
        sourceFilename: { type: string, nullable: true }
        outputFilename: { type: string, nullable: true }
        status: { type: string }
        estimatedDuration: { type: integer }
        pricing:
          type: object
          properties:
            basePerMinute: { type: number }
            onDemandPerMinute: { type: number }
            multiplier: { type: number }
            totalNeu: { type: number }
            reserved: { type: number }
            requestedPasses: { type: integer, enum: [1, 2] }
            effectivePasses:
              type: integer
              enum: [1, 2]
              description: Pass count used for pricing and execution. VMAF requests use 1.
        statusUrl: { type: string }
        packageType: { type: string, nullable: true }
        playbackUrl: { type: string, nullable: true }
        webhook: { type: string, nullable: true }
    OnDemandStatusResponse:
      type: object
      properties:
        jobId: { type: string, format: uuid }
        externalId: { type: string, nullable: true }
        metadata:
          type: object
          additionalProperties: true
          nullable: true
        sourceFilename: { type: string, nullable: true }
        outputFilename: { type: string, nullable: true }
        status: { type: string }
        progress: { type: number, nullable: true }
        encoder: { type: string, nullable: true }
        downloadUrl: { type: string, nullable: true }
        playbackUrl: { type: string, nullable: true }
        hlsPackage:
          type: object
          additionalProperties: true
          nullable: true
        expiresIn: { type: integer, nullable: true }
        destination:
          oneOf:
            - type: object
              properties:
                type: { type: string, enum: [cdn] }
            - type: object
              properties:
                type: { type: string, enum: [s3] }
                bucket: { type: string }
                key: { type: string }
            - type: object
              properties:
                type: { type: string, enum: [google-drive] }
                folderId: { type: string }
                fileName: { type: string, nullable: true }
          nullable: true
        createdAt: { type: string, format: date-time }
        startedAt: { type: string, format: date-time, nullable: true }
        finishedAt: { type: string, format: date-time, nullable: true }
        failureMessage: { type: string, nullable: true }
        requestedExecution:
          type: object
          additionalProperties: true
          nullable: true
        effectiveExecution:
          type: object
          additionalProperties: true
          nullable: true
        sourceProbe:
          $ref: "#/components/schemas/MediaProbe"
          nullable: true
        outputProbe:
          $ref: "#/components/schemas/MediaProbe"
          nullable: true
        warnings:
          type: array
          items:
            type: object
            additionalProperties: true
        billingSummary:
          type: object
          additionalProperties: true
          nullable: true
        executionReport:
          type: object
          additionalProperties: true
          nullable: true
    OnDemandFolderIngestRequest:
      type: object
      properties:
        externalIdPrefix:
          type: string
          maxLength: 200
          description: Optional prefix used to generate one externalId per queued file as `${externalIdPrefix}:${fileName}`.
        metadata:
          type: object
          additionalProperties: true
          description: Integration-owned JSON object attached to every queued job and returned in webhooks/status responses.
        codec: { type: string, enum: [h264, h265, av1], default: h264 }
        resolution:
          {
            type: string,
            enum: [480p, 720p, 1080p, 1440p, 2160p, 4320p],
            default: 1080p,
          }
        fps: { type: integer, minimum: 1, maximum: 120, default: 30 }
        preset: { type: string, enum: [fast, standard, slow], default: fast }
        bitrateTier:
          { type: string, enum: [low, medium, high], default: medium }
        passes:
          type: integer
          minimum: 1
          maximum: 2
          default: 1
          description: Requested passes. VMAF optimization always uses and bills one effective final pass.
        optimize: { type: string, enum: [none, vmaf], default: none }
        vmafTarget: { type: integer, minimum: 50, maximum: 99 }
        container: { type: string, enum: [mp4, mkv, webm, mov], default: mp4 }
        quality: { type: string, enum: [good, better, best], default: better }
        audioPolicy:
          {
            type: string,
            enum: [auto, copy, transcode-aac, strip],
            default: transcode-aac,
          }
        frameRatePolicy:
          { type: string, enum: [preserve, cap, force], default: force }
        scalePolicy:
          {
            type: string,
            enum: [no-upscale, allow-upscale, downscale-only],
            default: no-upscale,
          }
        priority: { type: string, enum: [normal, high], default: normal }
        maxFiles:
          type: integer
          minimum: 1
          maximum: 1000
          description: Optional cap on the number of discovered video files to queue from the folder.
        sourceS3:
          $ref: "#/components/schemas/S3FolderSource"
        sourceGoogleDrive:
          $ref: "#/components/schemas/GoogleDriveFolderSource"
        sourceGoogleDriveFiles:
          type: array
          minItems: 1
          maxItems: 1000
          items:
            $ref: "#/components/schemas/GoogleDriveSelectedFile"
        sourceDropbox:
          deprecated: true
          description: Deprecated. Requests using Dropbox ingest return 410 Gone.
          type: object
          properties:
            path: { type: string }
            accessToken: { type: string }
        outputDestination:
          type: string
          enum: [cdn, s3, google-drive]
          default: cdn
        outputS3:
          $ref: "#/components/schemas/S3FolderOutput"
        outputGoogleDrive:
          $ref: "#/components/schemas/GoogleDriveOutput"
        outputDropbox:
          deprecated: true
          description: Deprecated. Requests using Dropbox output return 410 Gone.
          type: object
          properties:
            path: { type: string }
    OnDemandFolderIngestResponse:
      type: object
      properties:
        message: { type: string }
        jobs:
          type: array
          items:
            type: object
            properties:
              jobId: { type: string, format: uuid }
              externalId: { type: string, nullable: true }
              fileName: { type: string }

    # Streaming
    StreamInitResponse:
      type: object
      properties:
        ok: { type: boolean }
        uploadId: { type: string }
        inputKey: { type: string }
    StreamFinalizeRequest:
      type: object
      properties:
        parts:
          type: array
          items:
            type: object
            properties:
              PartNumber: { type: integer }
              ETag: { type: string }
security:
  - BearerAuth: []
paths:
  /auth/login:
    post:
      summary: Login and receive JWTs
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/AuthLoginRequest"
      responses:
        "200":
          description: Tokens issued
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AuthLoginResponse"
  /tokens/balance:
    get:
      security: [{ BearerAuth: [] }, { ApiKeyAuth: [] }]
      summary: Get token balance
      responses:
        "200":
          description: Balance
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TokenBalanceResponse"
  /tokens/reserve:
    post:
      security: [{ BearerAuth: [] }, { ApiKeyAuth: [] }]
      summary: Reserve tokens for a job
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/TokenReserveRequest"
      responses:
        "200": { description: Reserved or insufficient }
  /tokens/release:
    post:
      security: [{ BearerAuth: [] }, { ApiKeyAuth: [] }]
      summary: Release reserved tokens for a job
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/TokenReserveRequest"
      responses:
        "200": { description: Released }
  /tokens/deduct:
    post:
      security: [{ BearerAuth: [] }, { ApiKeyAuth: [] }]
      summary: Deduct tokens after a job
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/TokenDeductRequest"
      responses:
        "200": { description: Deducted }
  /encode-presets:
    get:
      security: [{ BearerAuth: [] }, { ApiKeyAuth: [] }]
      summary: List saved encode presets
      responses:
        "200":
          description: Saved encode presets
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/EncodePresetListResponse"
    post:
      security: [{ BearerAuth: [] }, { ApiKeyAuth: [] }]
      summary: Save an encode preset
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/EncodePresetCreateRequest"
      responses:
        "201":
          description: Preset saved
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/EncodePresetResponse"
  /encode-presets/{id}:
    patch:
      security: [{ BearerAuth: [] }, { ApiKeyAuth: [] }]
      summary: Update a saved encode preset
      parameters:
        - in: path
          name: id
          required: true
          schema: { type: string, format: uuid }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/EncodePresetUpdateRequest"
      responses:
        "200":
          description: Preset updated
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/EncodePresetResponse"
    delete:
      security: [{ BearerAuth: [] }, { ApiKeyAuth: [] }]
      summary: Delete a saved encode preset
      parameters:
        - in: path
          name: id
          required: true
          schema: { type: string, format: uuid }
      responses:
        "200": { description: Preset deleted }
  /output-destinations:
    get:
      security: [{ BearerAuth: [] }, { ApiKeyAuth: [] }]
      summary: List saved output destinations
      responses:
        "200":
          description: Saved output destinations
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/OutputDestinationListResponse"
    post:
      security: [{ BearerAuth: [] }, { ApiKeyAuth: [] }]
      summary: Save an output destination
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/OutputDestinationCreateRequest"
      responses:
        "201":
          description: Destination saved
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/OutputDestinationResponse"
  /output-destinations/{id}:
    patch:
      security: [{ BearerAuth: [] }, { ApiKeyAuth: [] }]
      summary: Update a saved output destination
      parameters:
        - in: path
          name: id
          required: true
          schema: { type: string, format: uuid }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/OutputDestinationUpdateRequest"
      responses:
        "200":
          description: Destination updated
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/OutputDestinationResponse"
    delete:
      security: [{ BearerAuth: [] }, { ApiKeyAuth: [] }]
      summary: Delete a saved output destination
      parameters:
        - in: path
          name: id
          required: true
          schema: { type: string, format: uuid }
      responses:
        "200": { description: Destination deleted }
  /jobs:
    post:
      security: [{ BearerAuth: [] }, { ApiKeyAuth: [] }]
      summary: Create a new encode job
      description: Create a job for upload ingest (returns a presigned PUT) or direct URL/S3 ingest. Send `Idempotency-Key` when retrying from your backend to avoid duplicate jobs.
      parameters:
        - $ref: "#/components/parameters/IdempotencyKey"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/JobCreateRequest"
      responses:
        "200":
          description: Created
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/JobCreateResponse"
        "429":
          description: Rate limit exceeded
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
  /jobs/{id}:
    delete:
      security: [{ BearerAuth: [] }, { ApiKeyAuth: [] }]
      summary: Delete managed files for a terminal job
      description: Permanently deletes managed upload and output objects while retaining the job record and billing history. Active jobs must be canceled first.
      parameters:
        - in: path
          name: id
          required: true
          schema: { type: string }
      responses:
        "200":
          description: Managed files deleted and job record retained
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/JobFilesDeleteResponse"
        "409":
          description: Active job must be canceled before deleting files
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
  /jobs/{id}/probe-duration:
    get:
      security: [{ BearerAuth: [] }, { ApiKeyAuth: [] }]
      summary: Probe input duration
      parameters:
        - in: path
          name: id
          required: true
          schema: { type: string }
      responses:
        "200":
          description: Duration probed
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ProbeDurationResponse"
  /jobs/{id}/approve-unified:
    post:
      security: [{ BearerAuth: [] }, { ApiKeyAuth: [] }]
      summary: Approve, probe, reserve, and return estimate (does not enqueue)
      parameters:
        - in: path
          name: id
          required: true
          schema: { type: string }
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ApproveUnifiedRequest"
      responses:
        "200":
          description: Approved
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApproveUnifiedResponse"
  /jobs/{id}/confirm:
    post:
      security: [{ BearerAuth: [] }, { ApiKeyAuth: [] }]
      summary: Confirm job and enqueue (reserves if not already reserved)
      parameters:
        - in: path
          name: id
          required: true
          schema: { type: string }
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ConfirmRequest"
      responses:
        "200":
          description: Confirmed
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ConfirmResponse"
  /jobs/{id}/status:
    get:
      security: [{ BearerAuth: [] }, { ApiKeyAuth: [] }]
      summary: Get status for an authenticated job
      parameters:
        - in: path
          name: id
          required: true
          schema: { type: string }
      responses:
        "200":
          description: Status
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/StatusResponse"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "403":
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "404":
          description: Not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "429":
          description: Rate limit exceeded
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
  /jobs/{id}/cancel:
    post:
      security: [{ BearerAuth: [] }, { ApiKeyAuth: [] }]
      summary: Cancel a job (created/queued)
      parameters:
        - in: path
          name: id
          required: true
          schema: { type: string }
      responses:
        "200":
          description: Canceled or terminal-state no-op
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/JobCancelResponse"

  /api-keys:
    get:
      security: [{ BearerAuth: [] }]
      summary: List API keys
      responses:
        "200":
          description: List of keys
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiKeyListResponse"
    post:
      security: [{ BearerAuth: [] }]
      summary: Create an API key
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ApiKeyCreateRequest"
      responses:
        "200":
          description: Created
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiKeyResponse"
  /api-keys/{id}:
    delete:
      security: [{ BearerAuth: [] }]
      summary: Revoke an API key
      parameters:
        - in: path
          name: id
          required: true
          schema: { type: string, format: uuid }
      responses:
        "204": { description: Revoked }

  /webhooks:
    get:
      security: [{ BearerAuth: [] }, { ApiKeyAuth: [] }]
      summary: List webhooks
      description: List managed webhook subscriptions for the authenticated user. API keys need the `webhooks:manage` scope. Managed webhook deliveries include HMAC-SHA256 signatures.
      responses:
        "200":
          description: List of webhooks
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WebhookListResponse"
    post:
      security: [{ BearerAuth: [] }, { ApiKeyAuth: [] }]
      summary: Create a webhook
      description: |
        Create a managed webhook subscription. The response includes `secret` exactly once.
        Store it securely and use it to verify `X-Webhook-Signature`.
        API keys need the `webhooks:manage` scope.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/WebhookCreateRequest"
            examples:
              jobCompletionWebhook:
                summary: Completion and failure notifications
                value:
                  url: https://your-app.com/webhooks/convertrilo
                  events: [job.completed, job.failed, job.canceled]
      responses:
        "200":
          description: Created
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WebhookResponse"
  /webhooks/{id}:
    patch:
      security: [{ BearerAuth: [] }, { ApiKeyAuth: [] }]
      summary: Update a webhook
      description: API keys need the `webhooks:manage` scope.
      parameters:
        - in: path
          name: id
          required: true
          schema: { type: string, format: uuid }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/WebhookUpdateRequest"
            examples:
              reEnableWebhook:
                summary: Re-enable a disabled webhook
                value:
                  isActive: true
              changeEvents:
                summary: Receive only terminal job events
                value:
                  events: [job.completed, job.failed, job.canceled]
      responses:
        "200":
          description: Updated
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WebhookResponse"
    delete:
      security: [{ BearerAuth: [] }, { ApiKeyAuth: [] }]
      summary: Delete a webhook
      description: API keys need the `webhooks:manage` scope.
      parameters:
        - in: path
          name: id
          required: true
          schema: { type: string, format: uuid }
      responses:
        "204": { description: Deleted }
    post:
      security: [{ BearerAuth: [] }, { ApiKeyAuth: [] }]
      summary: Test a webhook
      description: Sends a `webhook.test` event to the configured URL using the same HMAC signature header as managed deliveries. API keys need the `webhooks:manage` scope.
      parameters:
        - in: path
          name: id
          required: true
          schema: { type: string, format: uuid }
      responses:
        "200": { description: Test event sent }
  /webhooks/{id}/deliveries:
    get:
      security: [{ BearerAuth: [] }, { ApiKeyAuth: [] }]
      summary: List webhook delivery attempts
      description: Returns the 50 most recent managed or test delivery attempts for this webhook. API keys need the `webhooks:manage` scope.
      parameters:
        - in: path
          name: id
          required: true
          schema: { type: string, format: uuid }
      responses:
        "200":
          description: Recent delivery attempts
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WebhookDeliveryListResponse"
        "404":
          description: Webhook not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

  /jobs/bulk:
    post:
      security: [{ BearerAuth: [] }, { ApiKeyAuth: [] }]
      summary: Bulk create jobs
      description: Send `Idempotency-Key` when retrying from your backend to avoid duplicate bulk batches, duplicate token reservations, or duplicate queue entries.
      parameters:
        - $ref: "#/components/parameters/IdempotencyKey"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/BulkCreateRequest"
      responses:
        "200":
          description: Created
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BulkCreateResponse"
        "429":
          description: Rate limit exceeded
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
  /jobs/bulk/status:
    get:
      security: [{ BearerAuth: [] }, { ApiKeyAuth: [] }]
      summary: Bulk status check
      parameters:
        - in: query
          name: ids
          required: true
          schema: { type: string, description: "Comma-separated job IDs" }
      responses:
        "200":
          description: Statuses
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BulkStatusResponse"
  /jobs/bulk/confirm:
    post:
      security: [{ BearerAuth: [] }, { ApiKeyAuth: [] }]
      summary: Bulk confirm/enqueue jobs
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/BulkConfirmRequest"
      responses:
        "200":
          description: Confirmed
          content:
            application/json:
              schema:
                type: object
                properties:
                  queued: { type: integer }
                  jobs:
                    type: array
                    items: { type: object }

  /jobs/{id}/stream/init:
    post:
      security: [{ BearerAuth: [] }, { ApiKeyAuth: [] }]
      summary: Initialize streaming ingest
      parameters:
        - in: path
          name: id
          required: true
          schema: { type: string, format: uuid }
      responses:
        "200":
          description: Session created
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/StreamInitResponse"
  /jobs/{id}/stream/chunk/{index}:
    put:
      security: [{ BearerAuth: [] }, { ApiKeyAuth: [] }]
      summary: Upload a streaming chunk
      parameters:
        - in: path
          name: id
          required: true
          schema: { type: string, format: uuid }
        - in: path
          name: index
          required: true
          schema: { type: integer, minimum: 1, maximum: 10000 }
      requestBody:
        required: true
        content:
          application/octet-stream:
            schema: { type: string, format: binary }
      responses:
        "200": { description: Chunk received }
  /jobs/{id}/stream/finalize:
    post:
      security: [{ BearerAuth: [] }, { ApiKeyAuth: [] }]
      summary: Finalize streaming and complete upload
      parameters:
        - in: path
          name: id
          required: true
          schema: { type: string, format: uuid }
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/StreamFinalizeRequest"
      responses:
        "200": { description: Finalized }
  /jobs/{id}/stream/abort:
    post:
      security: [{ BearerAuth: [] }, { ApiKeyAuth: [] }]
      summary: Abort streaming
      parameters:
        - in: path
          name: id
          required: true
          schema: { type: string, format: uuid }
      responses:
        "200": { description: Aborted }

  # Public (no auth) limited endpoints
  /public/jobs:
    post:
      summary: Create a public job
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [codec, resolution, fps]
              properties:
                codec: { type: string, enum: [h264, h265, av1] }
                resolution: { type: string, enum: [480p, 720p] }
                fps: { type: integer, minimum: 1, maximum: 60 }
                container: { type: string, enum: [mp4, mkv, mov, webm] }
                sourceUrl:
                  {
                    type: string,
                    format: uri,
                    description: Optional direct URL ingest,
                  }
      responses:
        "200":
          description: Created
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/JobCreateResponse"
  /public/jobs/{id}/probe-duration:
    get:
      summary: Probe duration for public job
      parameters:
        - in: path
          name: id
          required: true
          schema: { type: string }
      responses:
        "200":
          description: Duration
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ProbeDurationResponse"
  /public/jobs/{id}/confirm:
    post:
      summary: Confirm and enqueue a public job
      parameters:
        - in: path
          name: id
          required: true
          schema: { type: string }
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ConfirmRequest"
      responses:
        "200":
          description: Confirmed
  /public/jobs/{id}/status:
    get:
      summary: Get status for a public job (tokenized)
      parameters:
        - in: path
          name: id
          required: true
          schema: { type: string }
        - in: query
          name: token
          required: true
          schema: { type: string }
      responses:
        "200":
          description: Status
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/StatusResponse"

  # On-Demand Encoding API
  /ondemand/credentials/google-drive:
    get:
      security: [{ BearerAuth: [] }, { ApiKeyAuth: [] }]
      summary: List saved Google Drive service-account credentials
      responses:
        "200":
          description: Credential metadata
          content:
            application/json:
              schema:
                type: object
                properties:
                  credentials:
                    type: array
                    items:
                      $ref: "#/components/schemas/GoogleDriveCredential"
    post:
      security: [{ BearerAuth: [] }, { ApiKeyAuth: [] }]
      summary: Save an encrypted Google Drive service-account credential
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/GoogleDriveCredentialCreate"
      responses:
        "201":
          description: Credential saved
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GoogleDriveCredential"
  /ondemand/credentials/google-drive/{id}:
    delete:
      security: [{ BearerAuth: [] }, { ApiKeyAuth: [] }]
      summary: Delete a Google Drive service-account credential
      parameters:
        - in: path
          name: id
          required: true
          schema: { type: string, format: uuid }
      responses:
        "200":
          description: Credential deleted
  /ondemand/encode:
    post:
      security: [{ BearerAuth: [] }, { ApiKeyAuth: [] }]
      summary: Submit video for immediate on-demand encoding
      description: |
        Simplified API for immediate video encoding. Automatically probes, reserves tokens, 
        and starts encoding. Premium pricing (1.5x-2x) for on-demand convenience.
        Send `Idempotency-Key` when retrying from your backend to avoid duplicate jobs.
      parameters:
        - $ref: "#/components/parameters/IdempotencyKey"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/OnDemandEncodeRequest"
            examples:
              urlToCdn:
                summary: URL source to CDN output
                value:
                  sourceUrl: https://example.com/video.mp4
                  externalId: customer-video-123
                  metadata:
                    customerId: cus_123
                    workflow: daily-compression
                  codec: h264
                  resolution: 1080p
                  quality: better
              urlToS3:
                summary: URL source to S3 output
                value:
                  sourceUrl: https://example.com/video.mp4
                  codec: h264
                  resolution: 1080p
                  outputS3:
                    bucket: customer-output-bucket
                    key: encoded/video-1080p.mp4
                    region: us-east-1
                    accessKeyId: AKIA...
                    secretAccessKey: replace-with-secret
              urlToGoogleDrive:
                summary: URL source to Google Drive output with a saved service account
                value:
                  sourceUrl: https://example.com/video.mp4
                  codec: h264
                  resolution: 1080p
                  outputGoogleDrive:
                    folderId: GOOGLE_DRIVE_FOLDER_ID
                    fileName: video-1080p.mp4
                    credentialId: 11111111-1111-4111-8111-111111111111
      responses:
        "200":
          description: Job created and queued
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/OnDemandEncodeResponse"
        "400":
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "402":
          description: Insufficient tokens
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "403":
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "410":
          description: Deprecated Dropbox destination requested
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "429":
          description: Rate limit exceeded
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
  /ondemand/ingest/folder:
    post:
      security: [{ BearerAuth: [] }, { ApiKeyAuth: [] }]
      summary: Ingest videos from an S3 or Google Drive folder
      description: |
        Crawls an S3 prefix or Google Drive folder, queues one encode job per video file,
        and optionally delivers outputs to CDN, S3, or Google Drive.

        For API integrations, use bring-your-own credentials:
        - S3-compatible storage: pass `sourceS3` and/or `outputS3` credentials from your backend.
        - Google Drive: save a customer-owned service account, share the folders with its client email,
          and pass its `credentialId` in `sourceGoogleDrive` and/or `outputGoogleDrive`.
        Send `Idempotency-Key` when retrying from your backend to avoid duplicate folder batches.
      parameters:
        - $ref: "#/components/parameters/IdempotencyKey"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/OnDemandFolderIngestRequest"
            examples:
              s3FolderToS3:
                summary: S3 folder source to S3 output
                value:
                  externalIdPrefix: batch-2026-06-09
                  metadata:
                    customerId: cus_123
                    workflow: folder-compression
                  sourceS3:
                    bucket: customer-source-bucket
                    prefix: incoming/
                    region: us-east-1
                    accessKeyId: AKIA...
                    secretAccessKey: replace-with-secret
                  outputDestination: s3
                  outputS3:
                    bucket: customer-output-bucket
                    prefix: encoded/
                    region: us-east-1
                    accessKeyId: AKIA...
                    secretAccessKey: replace-with-secret
                  codec: h264
                  resolution: 1080p
              googleDriveFolderToGoogleDrive:
                summary: Google Drive folder source to Google Drive output
                value:
                  sourceGoogleDrive:
                    folderId: SOURCE_FOLDER_ID
                    credentialId: 11111111-1111-4111-8111-111111111111
                  outputDestination: google-drive
                  outputGoogleDrive:
                    folderId: OUTPUT_FOLDER_ID
                    credentialId: 11111111-1111-4111-8111-111111111111
                  codec: h264
                  resolution: 1080p
      responses:
        "200":
          description: Folder jobs queued
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/OnDemandFolderIngestResponse"
        "400":
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "401":
          description: Missing dashboard Google Drive connection
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "404":
          description: No video files found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "410":
          description: Deprecated Dropbox source or destination requested
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "429":
          description: Rate limit exceeded
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
  /ondemand/status/{jobId}:
    get:
      security: [{ BearerAuth: [] }, { ApiKeyAuth: [] }]
      summary: Get on-demand job status and download URL
      parameters:
        - in: path
          name: jobId
          required: true
          schema: { type: string, format: uuid }
      responses:
        "200":
          description: Job status
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/OnDemandStatusResponse"
        "404":
          description: Not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "429":
          description: Rate limit exceeded
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
  /ondemand/{jobId}:
    delete:
      security: [{ BearerAuth: [] }, { ApiKeyAuth: [] }]
      summary: Cancel on-demand encoding job
      parameters:
        - in: path
          name: jobId
          required: true
          schema: { type: string, format: uuid }
      responses:
        "200":
          description: Job canceled
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok: { type: boolean }
                  released: { type: number }