openapi: 3.1.0
info:
  title: Importly API
  version: 1.0.0
  summary: Download media, get transcripts, and read metadata from a URL.
  description: |
    Importly turns a public media URL (YouTube, TikTok, podcasts and more) into a downloadable file,
    a transcript, or metadata.

    Every job is asynchronous. A `POST` returns a `jobId` right away. Then either poll the matching
    `/status` endpoint until `status` is `completed` or `failed`, or pass a `webhookUrl` and Importly
    posts the result to you when the job succeeds.

    Every response uses one envelope: `{ "success": true, "data": … }` on success and
    `{ "success": false, "error": "…" }` on failure. Responses carry `X-RateLimit-Limit`,
    `X-RateLimit-Remaining`, `X-RateLimit-Reset` (Unix time in ms) and `X-RateLimit-Window` headers.

    Billing is pay-as-you-go from a credit balance. New accounts get $3.00 in free credits, no card required.
  contact:
    name: Importly support
    email: support@importly.io
    url: https://www.importly.io/docs
servers:
  - url: https://api.importly.io
    description: Production
security:
  - bearerAuth: []
tags:
  - name: Media
    description: Download video or audio from a URL.
  - name: Transcripts
    description: Turn a media URL into text with timestamped segments.
  - name: Metadata
    description: Read a URL's title, duration, thumbnail, formats and more without downloading the media.
  - name: Account
    description: Your credit balance.
  - name: Account settings
    description: Stored S3 credentials and speech-to-text provider keys. These calls carry secrets, so the docs playground is off for them.
  - name: Webhooks
    description: Requests Importly sends to your `webhookUrl` when a job completes.

paths:
  /import:
    post:
      tags: [Media]
      operationId: importMedia
      summary: Import media
      description: |
        Downloads the video and/or audio at a URL and gives you a signed download link (valid for 7 days).
        It can also copy the file to your own S3-compatible bucket and transcribe it in the same job.

        Costs $0.01 per MB downloaded, rounded up to the next MB, with a $0.03 minimum per import.
        You're charged only after the import succeeds, based on `downloadedBytes`.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ImportRequest'
            examples:
              default:
                summary: 720p video with medium audio
                value:
                  url: https://www.youtube.com/watch?v=jNQXAC9IVRw
                  webhookUrl: https://your-app.com/webhooks/importly
              audioOnly:
                summary: Audio only, high quality
                value:
                  url: https://www.youtube.com/watch?v=jNQXAC9IVRw
                  includeVideo: false
                  audioQuality: high
              withTranscript:
                summary: Download and transcribe from captions
                value:
                  url: https://www.youtube.com/watch?v=jNQXAC9IVRw
                  includeTranscript: true
              withProvider:
                summary: Download and transcribe with your AssemblyAI key
                value:
                  url: https://www.youtube.com/watch?v=jNQXAC9IVRw
                  includeTranscript: true
                  transcriptProvider: assemblyai
                  transcriptApiKey: YOUR_ASSEMBLYAI_KEY
                  transcriptOptions:
                    speaker_labels: true
              toYourBucket:
                summary: Also copy the file to your S3 bucket
                value:
                  url: https://www.youtube.com/watch?v=jNQXAC9IVRw
                  store: true
                  storagePath: videos/2026
      responses:
        '200':
          description: The import job was queued.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QueuedJobResponse'
              example:
                success: true
                data:
                  jobId: a824760e-ece1-4415-8838-ce2a7785ea6b
                  status: queued
                  message: Media import has been queued. You will receive a webhook when it's complete.
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalError'

  /import/status:
    get:
      tags: [Media]
      operationId: getImportStatus
      summary: Get import status
      description: |
        Returns the state of an import job. Poll it every few seconds until `status` is `completed`
        (the `result` holds the download link) or `failed` (the `message` says why). Free.
      parameters:
        - $ref: '#/components/parameters/JobId'
      responses:
        '200':
          description: The job's current state. A failed job still returns 200, with `status` set to `failed`.
          content:
            application/json:
              schema:
                type: object
                required: [success, data]
                properties:
                  success:
                    type: boolean
                    const: true
                  data:
                    $ref: '#/components/schemas/ImportStatus'
              examples:
                completed:
                  summary: Completed (audio-only import)
                  value:
                    success: true
                    data:
                      jobId: a824760e-ece1-4415-8838-ce2a7785ea6b
                      status: completed
                      result:
                        mediaUrl: https://fly.storage.tigris.dev/cdn-storage/imports/a824760e-ece1-4415-8838-ce2a7785ea6b/Me%20at%20the%20zoo.mp3?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Expires=604800&X-Amz-Signature=…
                        title: Me at the zoo
                        duration: 19
                        thumbnailUrl: https://i.ytimg.com/vi/jNQXAC9IVRw/hqdefault.jpg
                        filename: Me at the zoo.mp3
                        fileSizeBytes: 120621
                        downloadedBytes: 252182
                        costInDollars: 0.03
                      startedAt: '2026-11-16T14:36:05.491+00:00'
                      completedAt: '2026-11-16T14:37:36.956+00:00'
                running:
                  summary: Still running
                  value:
                    success: true
                    data:
                      jobId: a824760e-ece1-4415-8838-ce2a7785ea6b
                      status: running
                      startedAt: '2026-11-16T14:36:05.491+00:00'
                      completedAt: null
                failed:
                  summary: Failed
                  value:
                    success: true
                    data:
                      jobId: a824760e-ece1-4415-8838-ce2a7785ea6b
                      status: failed
                      message: Source video is unavailable.
                      code: VIDEO_UNAVAILABLE
                      documentationUrl: https://www.importly.io/docs/errors/media-unavailable
                      startedAt: '2026-11-16T14:36:05.491+00:00'
                      completedAt: '2026-11-16T14:36:20.102+00:00'
        '400':
          $ref: '#/components/responses/MissingJobId'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/JobNotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalError'

  /transcribe:
    post:
      tags: [Transcripts]
      operationId: transcribeMedia
      summary: Transcribe media
      description: |
        Turns a media URL into a transcript: plain text plus timestamped segments.

        - **Existing captions** (default): when the video has captions, including auto-generated ones. $0.01 per video.
        - **Built-in speech-to-text** (`provider: "importly"`): no account needed. $0.02 per media minute (min $0.03), plus the audio download at $0.01 per MB.
        - **Your own provider key** (`assemblyai`, `deepgram`, `openai`): $0.01 per media minute (min $0.03), plus the audio download at $0.01 per MB, plus your provider's own fees.

        Setting `provider` or `providerOptions` skips captions and always runs speech-to-text.
        If a video has no captions and you set no provider, the job fails with `TRANSCRIPTION_PROVIDER_REQUIRED`
        and a `quote` for built-in speech-to-text. Failed transcriptions are refunded automatically.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TranscribeRequest'
            examples:
              captions:
                summary: From existing captions
                value:
                  url: https://www.youtube.com/watch?v=jNQXAC9IVRw
                  webhookUrl: https://your-app.com/api/importly-webhook
              builtIn:
                summary: Built-in speech-to-text with a cost cap
                value:
                  url: https://example.com/conference-talk.mp4
                  provider: importly
                  maxCostDollars: 0.5
              ownKey:
                summary: Your Deepgram key
                value:
                  url: https://example.com/podcast-episode.mp3
                  provider: deepgram
                  apiKey: YOUR_DEEPGRAM_KEY
                  language: en
      responses:
        '200':
          description: The transcription job was queued.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QueuedJobResponse'
              example:
                success: true
                data:
                  jobId: 95be812f-4a2c-410a-9fcb-3ca5b445cc44
                  status: queued
                  message: Transcription has been queued for processing.
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalError'

  /transcribe/status:
    get:
      tags: [Transcripts]
      operationId: getTranscriptionStatus
      summary: Get transcription status
      description: |
        Returns the state of a transcription job. Poll it until `status` is `completed` (the `result` holds the
        transcript) or `failed` (`message`, usually a `code`, and for `TRANSCRIPTION_PROVIDER_REQUIRED` a `quote`). Free.
      parameters:
        - $ref: '#/components/parameters/JobId'
      responses:
        '200':
          description: The job's current state. A failed job still returns 200, with `status` set to `failed`.
          content:
            application/json:
              schema:
                type: object
                required: [success, data]
                properties:
                  success:
                    type: boolean
                    const: true
                  data:
                    $ref: '#/components/schemas/TranscriptionStatus'
              examples:
                completed:
                  summary: Completed from captions
                  value:
                    success: true
                    data:
                      jobId: 95be812f-4a2c-410a-9fcb-3ca5b445cc44
                      status: completed
                      result:
                        text: "All right, so here we are, in front of the elephants\nthe cool thing about these guys is that they have really...\nreally really long trunks\nand that's cool\n(baaaaaaaaaaahhh!!)\nand that's pretty much all there is to say"
                        source: platform_captions
                        language: en
                        duration: 19
                        data:
                          segments:
                            - { start: 1.2, end: 3.36, text: 'All right, so here we are, in front of the elephants' }
                            - { start: 5.318, end: 7.974, text: 'the cool thing about these guys is that they have really...' }
                            - { start: 7.974, end: 12.616, text: 'really really long trunks' }
                            - { start: 12.616, end: 14.367, text: "and that's cool" }
                            - { start: 14.421, end: 15.733, text: '(baaaaaaaaaaahhh!!)' }
                            - { start: 16.881, end: 18.881, text: "and that's pretty much all there is to say" }
                        costInDollars: 0.01
                running:
                  summary: Still running
                  value:
                    success: true
                    data:
                      jobId: 95be812f-4a2c-410a-9fcb-3ca5b445cc44
                      status: running
                providerRequired:
                  summary: Failed, no captions and no provider
                  value:
                    success: true
                    data:
                      jobId: 95be812f-4a2c-410a-9fcb-3ca5b445cc44
                      status: failed
                      message: 'This video has no captions. Add "provider": "importly" to transcribe it with AI speech-to-text — this 12-min video would cost $0.24 from your credits ($0.02/min). Or bring your own key (deepgram, openai, assemblyai) at $0.01/min.'
                      code: TRANSCRIPTION_PROVIDER_REQUIRED
                      documentationUrl: https://www.importly.io/docs/errors/transcription-provider-required
                      quote:
                        provider: importly
                        estimatedMinutes: 12
                        estimatedCostDollars: 0.24
        '400':
          $ref: '#/components/responses/MissingJobId'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/JobNotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalError'

  /metadata:
    post:
      tags: [Metadata]
      operationId: getMetadata
      summary: Get metadata
      description: |
        Returns everything the source knows about a URL (title, description, uploader, stats, thumbnails,
        and every available format) without downloading the media. If you only need the title, duration and
        thumbnail, use basic metadata instead; it's faster.

        Costs $0.01 per request. Metadata and basic metadata share one rate-limit budget.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MetadataRequest'
            example:
              url: https://www.youtube.com/watch?v=jNQXAC9IVRw
              webhookUrl: https://your-app.com/webhooks/importly
      responses:
        '200':
          description: The metadata job was queued.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QueuedJobResponse'
              example:
                success: true
                data:
                  jobId: e0b5df98-0867-490a-b321-cd10fdd80130
                  status: queued
                  message: Metadata request queued. You will receive a webhook when it's complete.
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalError'
    get:
      tags: [Metadata]
      operationId: getMetadataByQuery
      summary: Get metadata (GET form)
      description: |
        Starts the same job as `POST /metadata`, with the URL in the query string. It can't take a
        `webhookUrl`, so poll `GET /metadata/status` for the result. Costs $0.01 per request.
      parameters:
        - $ref: '#/components/parameters/MediaUrl'
      responses:
        '200':
          description: The metadata job was queued.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QueuedJobResponse'
              example:
                success: true
                data:
                  jobId: e0b5df98-0867-490a-b321-cd10fdd80130
                  status: queued
                  message: 'Metadata request queued. '
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalError'

  /metadata/status:
    get:
      tags: [Metadata]
      operationId: getMetadataStatus
      summary: Get metadata status
      description: |
        Returns the state of a metadata job. Poll it until `status` is `completed` or `failed`. The `result` is the
        source's raw metadata in snake_case; which fields exist varies by platform. Free.
      parameters:
        - $ref: '#/components/parameters/JobId'
      responses:
        '200':
          description: The job's current state. A failed job still returns 200, with `status` set to `failed`.
          content:
            application/json:
              schema:
                type: object
                required: [success, data]
                properties:
                  success:
                    type: boolean
                    const: true
                  data:
                    $ref: '#/components/schemas/MetadataStatus'
              examples:
                completed:
                  summary: Completed (abridged; a real result has about 80 fields)
                  value:
                    success: true
                    data:
                      jobId: e0b5df98-0867-490a-b321-cd10fdd80130
                      status: completed
                      result:
                        id: jNQXAC9IVRw
                        title: Me at the zoo
                        description: "…\n00:00 Intro\n00:05 The cool thing\n00:17 End"
                        uploader: jawed
                        uploader_id: '@jawed'
                        upload_date: '20050424'
                        duration: 19
                        view_count: 448211510
                        like_count: 20134056
                        thumbnail: https://i.ytimg.com/vi/jNQXAC9IVRw/hqdefault.jpg
                        thumbnails:
                          - { id: '44', url: 'https://i.ytimg.com/vi_webp/jNQXAC9IVRw/maxresdefault.webp', preference: 0 }
                        formats:
                          - format_id: '140'
                            url: https://rr5---sn-bvvbaxivnuxq5uu-p5is.googlevideo.com/videoplayback?…
                            ext: m4a
                            vcodec: none
                            acodec: mp4a.40.2
                            abr: 129.796
                            tbr: 129.796
                            filesize: 309288
                            protocol: https
                          - format_id: '134'
                            url: https://rr5---sn-bvvbaxivnuxq5uu-p5is.googlevideo.com/videoplayback?…
                            ext: mp4
                            height: 240
                            width: 320
                            fps: 15
                            vcodec: avc1.4D400C
                            acodec: none
                            vbr: 136.218
                            tbr: 136.218
                            filesize: 322379
                            protocol: https
                        tags: [me at the zoo, jawed karim, first youtube video]
                        categories: [Film & Animation]
                        webpage_url: https://www.youtube.com/watch?v=jNQXAC9IVRw
                        original_url: https://www.youtube.com/watch?v=jNQXAC9IVRw
                failed:
                  summary: Failed
                  value:
                    success: true
                    data:
                      jobId: e0b5df98-0867-490a-b321-cd10fdd80130
                      status: failed
                      message: Source video is unavailable.
                      code: VIDEO_UNAVAILABLE
                      documentationUrl: https://www.importly.io/docs/errors/media-unavailable
        '400':
          $ref: '#/components/responses/MissingJobId'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/JobNotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalError'

  /metadata/basic:
    post:
      tags: [Metadata]
      operationId: getBasicMetadata
      summary: Get basic metadata
      description: |
        Returns just the title, duration and thumbnail for a URL. It's faster than full metadata and suits
        link previews and import forms. Costs $0.01 per request, from the same rate-limit budget as full metadata.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MetadataRequest'
            example:
              url: https://www.youtube.com/watch?v=jNQXAC9IVRw
              webhookUrl: https://your-app.com/webhooks/importly
      responses:
        '200':
          description: The basic metadata job was queued.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QueuedJobResponse'
              example:
                success: true
                data:
                  jobId: 56380f26-3895-487a-8551-bc2a8b9c63ba
                  status: queued
                  message: Basic metadata request queued. You will receive a webhook when it's complete.
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalError'
    get:
      tags: [Metadata]
      operationId: getBasicMetadataByQuery
      summary: Get basic metadata (GET form)
      description: |
        Starts the same job as `POST /metadata/basic`, with the URL in the query string. It can't take a
        `webhookUrl`, so poll `GET /metadata/basic/status` for the result. Costs $0.01 per request.
      parameters:
        - $ref: '#/components/parameters/MediaUrl'
      responses:
        '200':
          description: The basic metadata job was queued.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QueuedJobResponse'
              example:
                success: true
                data:
                  jobId: 56380f26-3895-487a-8551-bc2a8b9c63ba
                  status: queued
                  message: 'Basic metadata request queued. '
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalError'

  /metadata/basic/status:
    get:
      tags: [Metadata]
      operationId: getBasicMetadataStatus
      summary: Get basic metadata status
      description: |
        Returns the state of a basic metadata job. Poll it until `status` is `completed` (the `result` has
        `title`, `duration` and `thumbnail`) or `failed`. Free.
      parameters:
        - $ref: '#/components/parameters/JobId'
      responses:
        '200':
          description: The job's current state. A failed job still returns 200, with `status` set to `failed`.
          content:
            application/json:
              schema:
                type: object
                required: [success, data]
                properties:
                  success:
                    type: boolean
                    const: true
                  data:
                    $ref: '#/components/schemas/BasicMetadataStatus'
              examples:
                completed:
                  summary: Completed
                  value:
                    success: true
                    data:
                      jobId: 56380f26-3895-487a-8551-bc2a8b9c63ba
                      status: completed
                      result:
                        title: Me at the zoo
                        duration: 19
                        thumbnail: https://i.ytimg.com/vi/jNQXAC9IVRw/hqdefault.jpg
                failed:
                  summary: Failed
                  value:
                    success: true
                    data:
                      jobId: 56380f26-3895-487a-8551-bc2a8b9c63ba
                      status: failed
                      message: Source video is unavailable.
                      code: VIDEO_UNAVAILABLE
                      documentationUrl: https://www.importly.io/docs/errors/media-unavailable
        '400':
          $ref: '#/components/responses/MissingJobId'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/JobNotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalError'

  /balance:
    get:
      tags: [Account]
      operationId: getBalance
      summary: Get balance
      description: |
        Returns your remaining credit in US dollars. Use it as a pre-flight check before large jobs, or to know
        when to top up. Free. Starting a job needs at least $0.01 of balance.
      responses:
        '200':
          description: Your balance.
          content:
            application/json:
              schema:
                type: object
                required: [success, data]
                properties:
                  success:
                    type: boolean
                    const: true
                  data:
                    type: object
                    required: [balance, currency]
                    properties:
                      balance:
                        type: number
                        description: Remaining credit in US dollars.
                      currency:
                        type: string
                        const: USD
              example:
                success: true
                data:
                  balance: 2.97
                  currency: USD
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalError'

  /s3-storage:
    get:
      tags: [Account settings]
      operationId: getS3Storage
      summary: Get S3 storage settings
      description: |
        Returns your saved S3-compatible bucket settings. Credentials are never returned.
      x-mint:
        metadata:
          playground: none
      responses:
        '200':
          description: Your bucket settings.
          content:
            application/json:
              schema:
                type: object
                required: [success, data]
                properties:
                  success:
                    type: boolean
                    const: true
                  data:
                    $ref: '#/components/schemas/S3StorageSettings'
              example:
                success: true
                data:
                  bucketName: your-bucket
                  region: us-east-1
                  endpoint: null
                  defaultPathPrefix: videos
                  storageClass: STANDARD
                  enabled: true
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          description: You haven't saved S3 settings.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                success: false
                error: No S3 storage configuration found
                code: NOT_FOUND
                documentationUrl: https://www.importly.io/docs/errors/not-found
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalError'
    post:
      tags: [Account settings]
      operationId: saveS3Storage
      summary: Save S3 storage settings
      description: |
        Saves the bucket that imports with `store: true` copy files to. Works with Amazon S3, Cloudflare R2,
        Backblaze B2, DigitalOcean Spaces and other S3-compatible storage. Importly first writes a small test
        object to the bucket and only saves the settings if that succeeds, so the key needs `s3:PutObject`.
        Saving again replaces the previous settings.
      x-mint:
        metadata:
          playground: none
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/S3StorageInput'
            examples:
              aws:
                summary: Amazon S3
                value:
                  accessKeyId: AKIAIOSFODNN7EXAMPLE
                  secretAccessKey: wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
                  bucketName: your-bucket
                  region: us-east-1
                  defaultPathPrefix: videos
              r2:
                summary: Cloudflare R2
                value:
                  accessKeyId: YOUR_R2_ACCESS_KEY_ID
                  secretAccessKey: YOUR_R2_SECRET_ACCESS_KEY
                  bucketName: your-bucket
                  region: auto
                  endpoint: https://ACCOUNT_ID.r2.cloudflarestorage.com
      responses:
        '200':
          description: The settings were tested and saved.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
              example:
                success: true
                message: S3 storage configuration saved successfully
        '400':
          description: A required field is missing, or the test upload to your bucket failed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                missingFields:
                  summary: Missing fields
                  value:
                    success: false
                    error: 'Missing required fields: accessKeyId, secretAccessKey, bucketName, region'
                    code: INVALID_REQUEST
                    documentationUrl: https://www.importly.io/docs/errors/invalid-request
                connectionFailed:
                  summary: Test upload failed
                  value:
                    success: false
                    error: 'Failed to connect to S3: Access Denied'
                    code: INVALID_REQUEST
                    documentationUrl: https://www.importly.io/docs/errors/invalid-request
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalError'
    delete:
      tags: [Account settings]
      operationId: deleteS3Storage
      summary: Delete S3 storage settings
      description: |
        Deletes your saved bucket settings and credentials. Imports with `store: true` then skip the copy to your bucket.
      x-mint:
        metadata:
          playground: none
      responses:
        '200':
          description: The settings were deleted.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
              example:
                success: true
                message: S3 storage configuration deleted successfully
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalError'

  /s3-storage/test:
    post:
      tags: [Account settings]
      operationId: testS3Storage
      summary: Test S3 storage settings
      description: |
        Checks bucket settings without saving them by writing a small test object
        (`importly-test-<timestamp>.txt`) to the bucket. Takes the same body as saving the settings.
      x-mint:
        metadata:
          playground: none
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/S3StorageInput'
            example:
              accessKeyId: AKIAIOSFODNN7EXAMPLE
              secretAccessKey: wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
              bucketName: your-bucket
              region: us-east-1
      responses:
        '200':
          description: The test upload succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
              example:
                success: true
                message: S3 connection test successful
        '400':
          description: A required field is missing, or the test upload failed. `error` is the storage provider's message.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                missingFields:
                  summary: Missing fields
                  value:
                    success: false
                    error: 'Missing required fields: accessKeyId, secretAccessKey, bucketName, region'
                    code: INVALID_REQUEST
                    documentationUrl: https://www.importly.io/docs/errors/invalid-request
                connectionFailed:
                  summary: Test upload failed
                  value:
                    success: false
                    error: The specified bucket does not exist
                    code: INVALID_REQUEST
                    documentationUrl: https://www.importly.io/docs/errors/invalid-request
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalError'

  /transcription-provider:
    get:
      tags: [Account settings]
      operationId: listTranscriptionProviders
      summary: List transcription provider keys
      description: |
        Lists the speech-to-text providers you can store a key for, and whether you have. Keys are never returned.
      x-mint:
        metadata:
          playground: none
      responses:
        '200':
          description: One entry per supported provider.
          content:
            application/json:
              schema:
                type: object
                required: [success, data]
                properties:
                  success:
                    type: boolean
                    const: true
                  data:
                    type: object
                    required: [providers]
                    properties:
                      providers:
                        type: array
                        items:
                          $ref: '#/components/schemas/TranscriptionProviderStatus'
              example:
                success: true
                data:
                  providers:
                    - { provider: assemblyai, configured: true, lastUsed: '2026-11-15T09:12:44.000Z' }
                    - { provider: deepgram, configured: false, lastUsed: null }
                    - { provider: openai, configured: false, lastUsed: null }
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalError'
    post:
      tags: [Account settings]
      operationId: saveTranscriptionProvider
      summary: Save a transcription provider key
      description: |
        Stores your API key for a speech-to-text provider, so `POST /transcribe` (and imports with
        `includeTranscript`) can use that provider without sending `apiKey` each time. Saving again replaces the key.
      x-mint:
        metadata:
          playground: none
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TranscriptionProviderInput'
            example:
              provider: deepgram
              apiKey: YOUR_DEEPGRAM_KEY
      responses:
        '200':
          description: The key was saved.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
              example:
                success: true
                message: Transcription provider saved successfully
        '400':
          description: A field is missing or the provider isn't supported.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                missingFields:
                  summary: Missing fields
                  value:
                    success: false
                    error: 'Missing required fields: provider, apiKey'
                    code: INVALID_REQUEST
                    documentationUrl: https://www.importly.io/docs/errors/invalid-request
                invalidProvider:
                  summary: Unsupported provider
                  value:
                    success: false
                    error: "Invalid provider: 'importly'. Supported: assemblyai, deepgram, openai"
                    code: INVALID_REQUEST
                    documentationUrl: https://www.importly.io/docs/errors/invalid-request
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalError'
    delete:
      tags: [Account settings]
      operationId: deleteTranscriptionProvider
      summary: Delete a transcription provider key
      description: Deletes your stored key for one speech-to-text provider.
      x-mint:
        metadata:
          playground: none
      parameters:
        - name: provider
          in: query
          required: true
          description: The provider whose key to delete.
          schema:
            $ref: '#/components/schemas/StoredTranscriptionProvider'
      responses:
        '200':
          description: The key was deleted.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
              example:
                success: true
                message: Transcription provider deleted successfully
        '400':
          description: '`provider` is missing or not supported.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                success: false
                error: 'Missing or invalid provider. Supported: assemblyai, deepgram, openai'
                code: INVALID_REQUEST
                documentationUrl: https://www.importly.io/docs/errors/invalid-request
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalError'

webhooks:
  importCompleted:
    post:
      tags: [Webhooks]
      operationId: importCompletedWebhook
      summary: Import completed
      description: |
        Sent once to the import's `webhookUrl` when the import succeeds. The result fields sit directly on `data`
        (not under `result`). Failed jobs don't send a webhook, and a delivery is never retried, so make your
        handler idempotent and fall back to `GET /import/status` if you need certainty.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ImportWebhook'
            examples:
              default:
                summary: Import
                value:
                  success: true
                  data:
                    jobId: a824760e-ece1-4415-8838-ce2a7785ea6b
                    type: import
                    status: completed
                    mediaUrl: https://fly.storage.tigris.dev/cdn-storage/imports/a824760e-ece1-4415-8838-ce2a7785ea6b/Me%20at%20the%20zoo.mp3?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Expires=604800&X-Amz-Signature=…
                    title: Me at the zoo
                    duration: 19
                    thumbnailUrl: https://i.ytimg.com/vi/jNQXAC9IVRw/hqdefault.jpg
                    costInDollars: 0.03
                    fileSizeBytes: 120621
                    downloadedBytes: 252182
                    filename: Me at the zoo.mp3
              withS3:
                summary: Import with a copy in your bucket
                value:
                  success: true
                  data:
                    jobId: a824760e-ece1-4415-8838-ce2a7785ea6b
                    type: import
                    status: completed
                    mediaUrl: https://fly.storage.tigris.dev/cdn-storage/imports/a824760e-ece1-4415-8838-ce2a7785ea6b/Me%20at%20the%20zoo.mp3?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Expires=604800&X-Amz-Signature=…
                    title: Me at the zoo
                    duration: 19
                    thumbnailUrl: https://i.ytimg.com/vi/jNQXAC9IVRw/hqdefault.jpg
                    costInDollars: 0.03
                    fileSizeBytes: 120621
                    downloadedBytes: 252182
                    filename: Me at the zoo.mp3
                    s3Storage:
                      url: https://your-bucket.s3.us-east-1.amazonaws.com/videos/2026/zoo.mp3
                      bucket: your-bucket
                      key: videos/2026/zoo.mp3
      responses:
        '200':
          description: Return any 2xx quickly; do heavy work asynchronously.
  transcribeCompleted:
    post:
      tags: [Webhooks]
      operationId: transcribeCompletedWebhook
      summary: Transcription completed
      description: |
        Sent once to the transcription's `webhookUrl` when it succeeds, with the transcript fields directly on `data`.
        Failed jobs don't send a webhook, and a delivery is never retried.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TranscriptionWebhook'
            example:
              success: true
              data:
                jobId: 95be812f-4a2c-410a-9fcb-3ca5b445cc44
                type: transcribe
                status: completed
                text: "All right, so here we are, in front of the elephants\nthe cool thing about these guys is that they have really...\n…"
                source: platform_captions
                language: en
                duration: 19
                data:
                  segments:
                    - { start: 1.2, end: 3.36, text: 'All right, so here we are, in front of the elephants' }
                    - { start: 5.318, end: 7.974, text: 'the cool thing about these guys is that they have really...' }
                costInDollars: 0.01
      responses:
        '200':
          description: Return any 2xx quickly; do heavy work asynchronously.
  metadataCompleted:
    post:
      tags: [Webhooks]
      operationId: metadataCompletedWebhook
      summary: Metadata completed
      description: |
        Sent once to the metadata job's `webhookUrl` when it succeeds, with the source's raw metadata (snake_case)
        directly on `data`. Failed jobs don't send a webhook, and a delivery is never retried.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MetadataWebhook'
            example:
              success: true
              data:
                jobId: e0b5df98-0867-490a-b321-cd10fdd80130
                type: metadata
                status: completed
                id: jNQXAC9IVRw
                title: Me at the zoo
                duration: 19
                thumbnail: https://i.ytimg.com/vi/jNQXAC9IVRw/hqdefault.jpg
                description: "…\n00:00 Intro\n00:05 The cool thing\n00:17 End"
                uploader: jawed
                upload_date: '20050424'
                view_count: 448211510
                formats: []
      responses:
        '200':
          description: Return any 2xx quickly; do heavy work asynchronously.
  basicMetadataCompleted:
    post:
      tags: [Webhooks]
      operationId: basicMetadataCompletedWebhook
      summary: Basic metadata completed
      description: |
        Sent once to the basic metadata job's `webhookUrl` when it succeeds, with `title`, `duration` and
        `thumbnail` directly on `data`. Failed jobs don't send a webhook, and a delivery is never retried.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BasicMetadataWebhook'
            example:
              success: true
              data:
                jobId: 56380f26-3895-487a-8551-bc2a8b9c63ba
                type: basic-metadata
                status: completed
                title: Me at the zoo
                duration: 19
                thumbnail: https://i.ytimg.com/vi/jNQXAC9IVRw/hqdefault.jpg
      responses:
        '200':
          description: Return any 2xx quickly; do heavy work asynchronously.

components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: 'Your API key from the dashboard, sent as `Authorization: Bearer <api key>`.'

  parameters:
    JobId:
      name: id
      in: query
      required: true
      description: The `jobId` returned when you started the job.
      schema:
        type: string
        format: uuid
      example: a824760e-ece1-4415-8838-ce2a7785ea6b
    MediaUrl:
      name: url
      in: query
      required: true
      description: Public media page URL (http or https). URL-encode it.
      schema:
        type: string
        format: uri
      example: https://www.youtube.com/watch?v=jNQXAC9IVRw

  headers:
    X-RateLimit-Limit:
      description: Requests allowed in the current window.
      schema:
        type: integer
    X-RateLimit-Remaining:
      description: Requests left in the current window.
      schema:
        type: integer
    X-RateLimit-Reset:
      description: When the window resets, as Unix time in milliseconds.
      schema:
        type: integer
    X-RateLimit-Window:
      description: Window length, e.g. `1 h`.
      schema:
        type: string

  responses:
    BadRequest:
      description: A parameter is missing or invalid.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            missingUrl:
              summary: Missing url
              value:
                success: false
                error: 'Missing required parameter: url'
                code: INVALID_URL
                documentationUrl: https://www.importly.io/docs/errors/invalid-url
            invalidUrl:
              summary: Invalid url
              value:
                success: false
                error: Invalid URL format - must be a valid HTTP or HTTPS URL
                code: INVALID_URL
                documentationUrl: https://www.importly.io/docs/errors/invalid-url
            webhookNotHttps:
              summary: Webhook URL isn't HTTPS
              value:
                success: false
                error: Webhook URL must use HTTPS
                code: INVALID_REQUEST
                documentationUrl: https://www.importly.io/docs/errors/invalid-request
    MissingJobId:
      description: The `id` query parameter is missing.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            success: false
            error: Missing id
            code: INVALID_REQUEST
            documentationUrl: https://www.importly.io/docs/errors/invalid-request
    Unauthorized:
      description: The API key is missing or invalid.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            missingHeader:
              summary: No Authorization header
              value:
                success: false
                error: 'Missing or invalid Authorization header. Must be in format: Bearer YOUR_API_KEY'
                code: UNAUTHORIZED
                documentationUrl: https://www.importly.io/docs/errors/unauthorized
            invalidKey:
              summary: Unknown key
              value:
                success: false
                error: Invalid API key
                code: UNAUTHORIZED
                documentationUrl: https://www.importly.io/docs/errors/unauthorized
    PaymentRequired:
      description: Your balance is below the $0.01 needed to start a job. Add credits on the Billing page.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/InsufficientBalanceError'
          example:
            success: false
            error: Insufficient balance. Please add credits to your account.
            code: INSUFFICIENT_BALANCE
            endpoint: /import
            balanceRequired: 0.01
            documentationUrl: https://www.importly.io/docs/errors/insufficient-credits
    JobNotFound:
      description: No job with that `id` belongs to your account.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            success: false
            error: Import job not found
            code: NOT_FOUND
            documentationUrl: https://www.importly.io/docs/errors/not-found
    TooManyRequests:
      description: You hit the hourly rate limit for this endpoint. Wait `retryAfter` seconds and retry.
      headers:
        X-RateLimit-Limit:
          $ref: '#/components/headers/X-RateLimit-Limit'
        X-RateLimit-Remaining:
          $ref: '#/components/headers/X-RateLimit-Remaining'
        X-RateLimit-Reset:
          $ref: '#/components/headers/X-RateLimit-Reset'
        X-RateLimit-Window:
          $ref: '#/components/headers/X-RateLimit-Window'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/RateLimitError'
          example:
            success: false
            error: 'Rate limit exceeded. Limit: 240 requests per 1 h'
            code: RATE_LIMITED
            limit: 240
            remaining: 0
            reset: 1763200000000
            retryAfter: 1800
            endpoint: /import
            documentationUrl: https://www.importly.io/docs/errors/rate-limited
    InternalError:
      description: Unexpected server error. Retry with exponential backoff.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            success: false
            error: Internal server error
            code: INTERNAL_ERROR
            documentationUrl: https://www.importly.io/docs/errors/server-error

  schemas:
    Error:
      type: object
      required: [success, error, code]
      properties:
        success:
          type: boolean
          const: false
        error:
          type: string
          description: What went wrong, in plain English.
        code:
          type: string
          description: |
            A stable, machine-readable error code: `UNAUTHORIZED`, `INSUFFICIENT_BALANCE`, `RATE_LIMITED`,
            `INVALID_URL`, `INVALID_REQUEST`, `NOT_FOUND` or `INTERNAL_ERROR`.
          examples: [INVALID_URL]
        documentationUrl:
          type: string
          format: uri
          description: A page explaining this error and how to fix it.
          examples: ['https://www.importly.io/docs/errors/invalid-url']
    InsufficientBalanceError:
      allOf:
        - $ref: '#/components/schemas/Error'
        - type: object
          required: [code]
          properties:
            code:
              type: string
              const: INSUFFICIENT_BALANCE
            endpoint:
              type: string
              description: The rate-limit bucket the request counted against.
            balanceRequired:
              type: number
              description: Minimum balance in US dollars needed to start the job.
    RateLimitError:
      allOf:
        - $ref: '#/components/schemas/Error'
        - type: object
          properties:
            limit:
              type: integer
              description: Requests allowed per window.
            remaining:
              type: integer
              description: Requests left in the window.
            reset:
              type: integer
              description: When the window resets, as Unix time in milliseconds.
            retryAfter:
              type: integer
              description: Seconds to wait before retrying.
            endpoint:
              type: string
              description: The rate-limit bucket the request counted against.
            concurrentLimit:
              type: integer
              description: Present instead of `limit` when too many of your jobs are already running.
            currentConcurrent:
              type: integer
              description: Present with `concurrentLimit`.
    MessageResponse:
      type: object
      required: [success, message]
      properties:
        success:
          type: boolean
          const: true
        message:
          type: string

    JobStatusValue:
      type: string
      enum: [queued, running, completed, failed]
      description: '`queued` and `running` mean keep polling; `completed` and `failed` are final.'
    QueuedJobResponse:
      type: object
      required: [success, data]
      properties:
        success:
          type: boolean
          const: true
        data:
          type: object
          required: [jobId, status, message]
          properties:
            jobId:
              type: string
              format: uuid
              description: Pass this as `id` to the matching status endpoint.
            status:
              type: string
              const: queued
            message:
              type: string

    WebhookUrl:
      type: string
      format: uri
      description: |
        HTTPS URL that receives the result when the job succeeds. It must not point to a private or
        internal address. Failed jobs don't send a webhook.
      example: https://your-app.com/webhooks/importly

    ImportRequest:
      type: object
      required: [url]
      properties:
        url:
          type: string
          format: uri
          description: Public media page URL, e.g. a YouTube, TikTok or podcast episode link.
          example: https://www.youtube.com/watch?v=jNQXAC9IVRw
        includeVideo:
          type: boolean
          default: true
          description: |
            Include the video stream. Set to `false` for audio only. When a platform has no separate audio stream
            (common on TikTok), Importly downloads the smallest video and extracts the audio; you're billed for
            `downloadedBytes`, not the extracted file's `fileSizeBytes`.
        includeAudio:
          type: boolean
          default: true
          description: Include the audio stream. Set to `false` for video only. At least one of `includeVideo` and `includeAudio` must be true.
        videoQuality:
          type: string
          enum: [lowest, 144p, 240p, 360p, 480p, 720p, 1080p, 1440p, 2160p, best]
          default: 720p
          description: Highest video resolution to download. Importly picks the best stream at or below it.
        audioQuality:
          type: string
          enum: [lowest, low, medium, high, best]
          default: medium
          description: Highest audio bitrate to download (`low` ≤ 64 kbps, `medium` ≤ 128 kbps, `high` ≤ 192 kbps).
        webhookUrl:
          $ref: '#/components/schemas/WebhookUrl'
        includeTranscript:
          type: boolean
          default: false
          description: Also transcribe the media. The result gains a `transcript` object, billed like a transcription job.
        transcriptProvider:
          $ref: '#/components/schemas/TranscriptionProvider'
        transcriptApiKey:
          type: string
          description: Your key for `assemblyai`, `deepgram` or `openai`. Optional if you saved one with `POST /transcription-provider`.
        transcriptLanguage:
          type: string
          description: |
            Spoken language as a two-letter code, e.g. `es`. It picks the caption track, or is sent to the provider.
            Without it, `importly`, `deepgram` and `assemblyai` transcribe as English.
          example: en
        transcriptOptions:
          type: object
          additionalProperties: true
          description: |
            Options passed through to `transcriptProvider` (same as `providerOptions` on `POST /transcribe`),
            e.g. AssemblyAI's `speaker_labels`. Ignored with `importly`. Setting it skips captions, so set `transcriptProvider` too.
        store:
          type: boolean
          default: false
          description: Also copy the file to your own S3-compatible bucket. Requires saved S3 storage settings.
        storagePath:
          type: string
          description: Folder prefix in your bucket, e.g. `videos/2026`. Defaults to the prefix in your S3 settings.
        storageFilename:
          type: string
          description: Filename in your bucket without extension (added automatically). Defaults to the media title.
        storageBucket:
          type: string
          description: Use this bucket instead of the one in your S3 settings.
        storageClass:
          type: string
          description: S3 storage class, e.g. `STANDARD` or `INTELLIGENT_TIERING`.
        storageReturnLocation:
          type: boolean
          deprecated: true
          description: Has no effect. `s3Storage.url` always holds the object URL.

    TranscribeRequest:
      type: object
      required: [url]
      properties:
        url:
          type: string
          format: uri
          description: Public media URL to transcribe.
          example: https://www.youtube.com/watch?v=jNQXAC9IVRw
        language:
          type: string
          description: |
            Spoken language as a two-letter code, e.g. `es`. For captions it picks the track (English if present
            when omitted). For speech-to-text it's sent to the provider; when omitted, `importly`, `deepgram` and
            `assemblyai` transcribe as English and `openai` auto-detects.
          example: en
        provider:
          $ref: '#/components/schemas/TranscriptionProvider'
        apiKey:
          type: string
          description: Your key for the chosen provider. Not needed for `importly`, or if you saved one with `POST /transcription-provider`.
        providerOptions:
          type: object
          additionalProperties: true
          description: |
            Options passed through to your provider under its own option names, e.g. `{ "speaker_labels": true }`
            for AssemblyAI or `{ "model": "nova-3" }` for Deepgram. Options that change where the provider reads audio
            or sends results are dropped. Ignored with `importly`. Always set `provider` too.
        maxCostDollars:
          type: number
          exclusiveMinimum: 0
          description: |
            Cap for built-in speech-to-text. If the estimated per-minute charge exceeds it, the job fails with
            `MAX_COST_EXCEEDED` and the estimate instead of running. If the duration
            can't be determined up front, the cap is charged and the unused part refunded afterward. Covers the per-minute charge only, not the audio download.
        webhookUrl:
          $ref: '#/components/schemas/WebhookUrl'

    TranscriptionProvider:
      type: string
      enum: [importly, assemblyai, deepgram, openai]
      description: |
        Speech-to-text provider. `importly` is built in and needs no key. Setting a provider skips captions and
        always runs speech-to-text; omit it to use the video's existing captions.
    StoredTranscriptionProvider:
      type: string
      enum: [assemblyai, deepgram, openai]

    MetadataRequest:
      type: object
      required: [url]
      properties:
        url:
          type: string
          format: uri
          description: Public media page URL, e.g. a YouTube, TikTok or podcast episode link.
          example: https://www.youtube.com/watch?v=jNQXAC9IVRw
        webhookUrl:
          $ref: '#/components/schemas/WebhookUrl'

    S3Location:
      type: object
      properties:
        url:
          type: string
          description: Full URL of the object in your bucket.
        bucket:
          type: string
        key:
          type: string
          description: Object key (path within the bucket).
    TranscriptSegment:
      type: object
      properties:
        start:
          type: number
          description: Start time in seconds.
        end:
          type: number
          description: End time in seconds.
        text:
          type: string
    TranscriptFields:
      type: object
      required: [text, source]
      properties:
        text:
          type: string
          description: The full transcript as plain text.
        source:
          type: string
          enum: [platform_captions, importly, assemblyai, deepgram, openai]
          description: Where the transcript came from.
        language:
          type: [string, 'null']
        duration:
          type: [number, 'null']
          description: Media length in seconds.
        data:
          type: object
          description: Timestamped segments, plus any extra fields your provider returns.
          properties:
            segments:
              type: array
              items:
                $ref: '#/components/schemas/TranscriptSegment'
        costInDollars:
          type: number
          description: What the transcription cost.
        downloadCostInDollars:
          type: number
          description: Speech-to-text only. The audio download's share of the cost.
    TranscriptSkipped:
      type: object
      required: [status, reason]
      properties:
        status:
          type: string
          const: skipped
        reason:
          type: string
        costInDollars:
          type: number
          const: 0
    ImportResult:
      type: object
      properties:
        mediaUrl:
          type: string
          description: Signed download link on Importly storage. Expires after 7 days.
        title:
          type: string
        duration:
          type: number
          description: Length in seconds.
        thumbnailUrl:
          type: string
          description: The source platform's own thumbnail.
        filename:
          type: string
          description: The delivered file's name, from the media title.
        fileSizeBytes:
          type: integer
          description: Size of the delivered file.
        downloadedBytes:
          type: integer
          description: Bytes downloaded from the source. This is what's billed.
        costInDollars:
          type: number
          description: What the import cost (the transcript is reported separately in `transcript.costInDollars`).
        transcript:
          description: Only with `includeTranscript`. The transcript, or a skipped marker if it couldn't be produced.
          oneOf:
            - $ref: '#/components/schemas/TranscriptFields'
            - $ref: '#/components/schemas/TranscriptSkipped'
        s3Storage:
          $ref: '#/components/schemas/S3Location'
        s3StorageError:
          type: string
          description: Only with `store`, if the copy to your bucket failed. The import itself still succeeds.
    MetadataResult:
      type: object
      additionalProperties: true
      description: The source's raw metadata in snake_case. Which fields exist varies by platform.
      properties:
        id:
          type: string
        title:
          type: string
        description:
          type: string
        duration:
          type: number
          description: Length in seconds.
        uploader:
          type: string
        uploader_id:
          type: string
        upload_date:
          type: string
          description: '`YYYYMMDD`'
        view_count:
          type: integer
        like_count:
          type: integer
        thumbnail:
          type: string
        thumbnails:
          type: array
          items:
            type: object
            additionalProperties: true
        formats:
          type: array
          description: |
            Every available stream (`format_id`, `ext`, `height`, `width`, `vcodec`, `acodec`, `tbr`, `filesize`, `url`, …).
            Stream URLs are short-lived and often tied to the fetching IP; download with `POST /import` instead.
          items:
            type: object
            additionalProperties: true
        tags:
          type: array
          items:
            type: string
        categories:
          type: array
          items:
            type: string
        webpage_url:
          type: string
    BasicMetadataResult:
      type: object
      properties:
        title:
          type: [string, 'null']
        duration:
          type: [number, 'null']
          description: Length in seconds.
        thumbnail:
          type: [string, 'null']

    ImportStatus:
      type: object
      required: [jobId, status]
      properties:
        jobId:
          type: string
          format: uuid
        status:
          $ref: '#/components/schemas/JobStatusValue'
        result:
          $ref: '#/components/schemas/ImportResult'
        message:
          type: string
          description: Only when `failed`. Why the job failed.
        code:
          type: string
          description: Only when `failed`, usually. A stable error code, e.g. `VIDEO_PRIVATE`, `PLAYLIST_NOT_SUPPORTED` or `FILE_TOO_LARGE`.
        documentationUrl:
          type: string
          format: uri
          description: Only when `failed` with a known `code`. A page explaining the error and how to fix it, e.g. `https://www.importly.io/docs/errors/media-unavailable`.
        startedAt:
          type: [string, 'null']
          format: date-time
        completedAt:
          type: [string, 'null']
          format: date-time
    TranscriptionStatus:
      type: object
      required: [jobId, status]
      properties:
        jobId:
          type: string
          format: uuid
        status:
          $ref: '#/components/schemas/JobStatusValue'
        result:
          $ref: '#/components/schemas/TranscriptFields'
        message:
          type: string
          description: Only when `failed`. Why the job failed.
        code:
          type: string
          description: Only when `failed`, usually. A stable error code, e.g. `TRANSCRIPTION_PROVIDER_REQUIRED` or `MAX_COST_EXCEEDED`.
        documentationUrl:
          type: string
          format: uri
          description: Only when `failed` with a known `code`. A page explaining the error and how to fix it, e.g. `https://www.importly.io/docs/errors/media-unavailable`.
        quote:
          type: object
          description: With `TRANSCRIPTION_PROVIDER_REQUIRED`, when the duration is known. What built-in speech-to-text would cost for this media.
          properties:
            provider:
              type: string
              const: importly
            estimatedMinutes:
              type: integer
            estimatedCostDollars:
              type: number
    MetadataStatus:
      type: object
      required: [jobId, status]
      properties:
        jobId:
          type: string
          format: uuid
        status:
          $ref: '#/components/schemas/JobStatusValue'
        result:
          $ref: '#/components/schemas/MetadataResult'
        message:
          type: string
          description: Only when `failed`. Why the job failed.
        code:
          type: string
          description: Only when `failed`, usually. A stable error code, e.g. `VIDEO_UNAVAILABLE` or `VIDEO_PRIVATE`.
        documentationUrl:
          type: string
          format: uri
          description: Only when `failed` with a known `code`. A page explaining the error and how to fix it, e.g. `https://www.importly.io/docs/errors/media-unavailable`.
    BasicMetadataStatus:
      type: object
      required: [jobId, status]
      properties:
        jobId:
          type: string
          format: uuid
        status:
          $ref: '#/components/schemas/JobStatusValue'
        result:
          $ref: '#/components/schemas/BasicMetadataResult'
        message:
          type: string
          description: Only when `failed`. Why the job failed.
        code:
          type: string
          description: Only when `failed`, usually. A stable error code, e.g. `VIDEO_UNAVAILABLE`.
        documentationUrl:
          type: string
          format: uri
          description: Only when `failed` with a known `code`. A page explaining the error and how to fix it, e.g. `https://www.importly.io/docs/errors/media-unavailable`.

    S3StorageSettings:
      type: object
      properties:
        bucketName:
          type: string
        region:
          type: string
        endpoint:
          type: [string, 'null']
          description: Set for S3-compatible storage other than Amazon S3.
        defaultPathPrefix:
          type: [string, 'null']
        storageClass:
          type: [string, 'null']
        enabled:
          type: boolean
    S3StorageInput:
      type: object
      required: [accessKeyId, secretAccessKey, bucketName, region]
      properties:
        accessKeyId:
          type: string
          description: Access key ID of a key that can `s3:PutObject` on the bucket.
        secretAccessKey:
          type: string
        bucketName:
          type: string
        region:
          type: string
          description: The bucket's region, e.g. `us-east-1` (`auto` for Cloudflare R2).
        endpoint:
          type: string
          format: uri
          description: |
            Required for S3-compatible storage other than Amazon S3, e.g. `https://<account-id>.r2.cloudflarestorage.com`
            or `https://s3.<region>.backblazeb2.com`.
        defaultPathPrefix:
          type: string
          description: Folder prefix for uploads when an import doesn't set `storagePath`.
        storageClass:
          type: string
          description: Default S3 storage class, e.g. `STANDARD`.

    TranscriptionProviderStatus:
      type: object
      required: [provider, configured, lastUsed]
      properties:
        provider:
          $ref: '#/components/schemas/StoredTranscriptionProvider'
        configured:
          type: boolean
          description: Whether you've saved a key for this provider.
        lastUsed:
          type: [string, 'null']
          format: date-time
    TranscriptionProviderInput:
      type: object
      required: [provider, apiKey]
      properties:
        provider:
          $ref: '#/components/schemas/StoredTranscriptionProvider'
        apiKey:
          type: string
          description: Your API key for that provider.

    WebhookEnvelope:
      type: object
      required: [success, data]
      properties:
        success:
          type: boolean
          const: true
          description: Always `true`; webhooks are only sent for successful jobs.
    WebhookJobFields:
      type: object
      required: [jobId, type, status]
      properties:
        jobId:
          type: string
          format: uuid
          description: Match this with the `jobId` you got when you started the job.
        status:
          type: string
          const: completed
    ImportWebhook:
      allOf:
        - $ref: '#/components/schemas/WebhookEnvelope'
        - type: object
          properties:
            data:
              allOf:
                - $ref: '#/components/schemas/WebhookJobFields'
                - type: object
                  properties:
                    type:
                      type: string
                      const: import
                - $ref: '#/components/schemas/ImportResult'
    TranscriptionWebhook:
      allOf:
        - $ref: '#/components/schemas/WebhookEnvelope'
        - type: object
          properties:
            data:
              allOf:
                - $ref: '#/components/schemas/WebhookJobFields'
                - type: object
                  properties:
                    type:
                      type: string
                      const: transcribe
                - $ref: '#/components/schemas/TranscriptFields'
    MetadataWebhook:
      allOf:
        - $ref: '#/components/schemas/WebhookEnvelope'
        - type: object
          properties:
            data:
              allOf:
                - $ref: '#/components/schemas/WebhookJobFields'
                - type: object
                  properties:
                    type:
                      type: string
                      const: metadata
                - $ref: '#/components/schemas/MetadataResult'
    BasicMetadataWebhook:
      allOf:
        - $ref: '#/components/schemas/WebhookEnvelope'
        - type: object
          properties:
            data:
              allOf:
                - $ref: '#/components/schemas/WebhookJobFields'
                - type: object
                  properties:
                    type:
                      type: string
                      const: basic-metadata
                - $ref: '#/components/schemas/BasicMetadataResult'
