Scribiz Jobs API

openapi: 3.2.0
info:
  title: Scribiz Jobs API
  version: 1.0.0
  description: 'Operations tagged Jobs across 2 of this provider''s published API definitions: openapi.json, scribiz-openapi.json. Each path carries the servers of the definition it was published in.'
servers:
- description: 'The one public base for every client: https://scribiz.com/api (Better Auth at /api/auth, remote MCP at https://scribiz.com/mcp). The proxy routes both paths to this API.'
  url: https://scribiz.com/api
tags:
- name: Jobs
paths:
  /v1/ask:
    post:
      description: 'One question about a Context. It costs 0.1 minute, or what it cost when that is more (priced like a proxied call, at $0.005 a minute): a question about a long video costs more than one about a short one. The check before the question uses the size of the Context. Never starts the on-screen layer.'
      operationId: ask
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AskRequest'
        description: JSON
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AskResponse'
          description: Answered.
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: invalid_request
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: unauthorized, invalid_api_key or invalid_token
        '402':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: quota_exceeded
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: insufficient_scope, session_required, account_required, turnstile_required, bad_origin
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: not_found
        '409':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: job_not_ready
        '413':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: body_too_large
        '429':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: rate_limited, too_many_in_flight, anonymous_limit, daily_spend_limit
      security:
      - apiKey:
        - all
      - bearer:
        - all
      - cookie: []
      - {}
      summary: Ask a question about a video
      tags:
      - Jobs
    servers:
    - description: 'The one public base for every client: https://scribiz.com/api (Better Auth at /api/auth, remote MCP at https://scribiz.com/mcp). The proxy routes both paths to this API.'
      url: https://scribiz.com/api
  /v1/context:
    post:
      description: Quotes the job (length, minutes, plan limits), then queues it. The 202 body says what it will cost; follow `events_url` for progress and `result_url` for the Context.
      operationId: createContext
      parameters:
      - description: Repeats of the same key with the same body return the same job.
        in: header
        name: Idempotency-Key
        required: false
        schema:
          maxLength: 200
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ContextRequest'
        description: JSON
      responses:
        '202':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobCreated'
          description: Queued.
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: invalid_request
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: unauthorized, invalid_api_key or invalid_token
        '402':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: 'quota_exceeded: out of minutes'
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: insufficient_scope, session_required, account_required, turnstile_required, bad_origin
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: not_found
        '413':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: video_too_long
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: The source cannot be read (source_unavailable, url_unsupported, ...).
        '429':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: rate_limited, too_many_in_flight, anonymous_limit, daily_spend_limit
        '451':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: blocked_content
        '503':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: busy, not_configured
      security:
      - apiKey:
        - all
      - bearer:
        - all
      - cookie: []
      - {}
      summary: Start a job for a link or an upload
      tags:
      - Jobs
    servers:
    - description: 'The one public base for every client: https://scribiz.com/api (Better Auth at /api/auth, remote MCP at https://scribiz.com/mcp). The proxy routes both paths to this API.'
      url: https://scribiz.com/api
  /v1/jobs:
    get:
      description: 'The account''s jobs across every device and surface (web, phone + watch, Mac app, CLI, MCP, Telegram, WhatsApp) that are running or still have a result, newest first, without the results themselves (read one with GET /v1/jobs/{id}). `source_kind` names the origin in machine-readable form; `label` is the optional user tag. Needs an account: a job started without one is reached by its link.'
      operationId: listJobs
      parameters:
      - description: Jobs on a page (1 to 100, default 50).
        in: query
        name: limit
        schema:
          maximum: 100
          minimum: 1
          type: integer
      - description: 'Only jobs created before this time (epoch ms): pass `next_before` of the page before.'
        in: query
        name: before
        schema:
          type: integer
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  jobs:
                    items:
                      properties:
                        created_at:
                          type: integer
                        error_code:
                          type:
                          - string
                          - 'null'
                        expires_at:
                          type: integer
                        file_name:
                          type:
                          - string
                          - 'null'
                        finished_at:
                          type:
                          - integer
                          - 'null'
                        input:
                          type: object
                        job_id:
                          type: string
                        label:
                          type:
                          - string
                          - 'null'
                        media_seconds:
                          type:
                          - number
                          - 'null'
                        minutes_charged:
                          type:
                          - number
                          - 'null'
                        mode:
                          type: string
                        provider:
                          type:
                          - string
                          - 'null'
                        source_kind:
                          type: string
                        status:
                          enum:
                          - queued
                          - running
                          - succeeded
                          - failed
                          - canceled
                          type: string
                        title:
                          type:
                          - string
                          - 'null'
                        via:
                          type:
                          - string
                          - 'null'
                      type: object
                    type: array
                  next_before:
                    description: Null on the last page.
                    type:
                    - integer
                    - 'null'
                type: object
          description: One page of jobs.
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: invalid_request
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: unauthorized, invalid_api_key or invalid_token
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: insufficient_scope, session_required, account_required, turnstile_required, bad_origin
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: not_found
        '429':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: rate_limited, too_many_in_flight, anonymous_limit, daily_spend_limit
      security:
      - apiKey:
        - read
      - bearer:
        - read
      - cookie: []
      summary: List the account's jobs
      tags:
      - Jobs
    servers:
    - description: 'The one public base for every client: https://scribiz.com/api (Better Auth at /api/auth, remote MCP at https://scribiz.com/mcp). The proxy routes both paths to this API.'
      url: https://scribiz.com/api
  /v1/jobs/{id}:
    delete:
      description: Cancels a job that is queued or running; deletes the result of one that has finished.
      operationId: cancelJob
      parameters:
      - description: The job id (job_...).
        in: path
        name: id
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                type: object
          description: Cancelled or deleted.
        '202':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Job'
          description: Cancel requested; the job is still winding down.
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: invalid_request
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: unauthorized, invalid_api_key or invalid_token
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: insufficient_scope, session_required, account_required, turnstile_required, bad_origin
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: not_found
        '429':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: rate_limited, too_many_in_flight, anonymous_limit, daily_spend_limit
      security:
      - apiKey:
        - all
      - bearer:
        - all
      - cookie: []
      - {}
      summary: Cancel or delete a job
      tags:
      - Jobs
    get:
      description: An account's job is readable by that account only. An anonymous job is readable by whoever holds its id, for 24 hours.
      operationId: getJob
      parameters:
      - description: The job id (job_...).
        in: path
        name: id
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Job'
          description: The job.
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: invalid_request
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: unauthorized, invalid_api_key or invalid_token
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: insufficient_scope, session_required, account_required, turnstile_required, bad_origin
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: not_found
        '410':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: job_expired
        '429':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: rate_limited, too_many_in_flight, anonymous_limit, daily_spend_limit
      security:
      - apiKey:
        - read
      - bearer:
        - read
      - cookie: []
      - {}
      summary: State, progress and the Context when done
      tags:
      - Jobs
    servers:
    - description: 'The one public base for every client: https://scribiz.com/api (Better Auth at /api/auth, remote MCP at https://scribiz.com/mcp). The proxy routes both paths to this API.'
      url: https://scribiz.com/api
  /v1/jobs/{id}/events:
    get:
      description: 'Server-sent events. `id` is the event number (resume with Last-Event-ID), `event` is the type, `data` is the engine''s ProgressEvent as JSON. A `: ping` comment every 15 s. The stream ends after `done` or `error`.'
      operationId: jobEvents
      parameters:
      - description: The job id (job_...).
        in: path
        name: id
        required: true
        schema:
          type: string
      - in: header
        name: Last-Event-ID
        required: false
        schema:
          type: integer
      responses:
        '200':
          content:
            text/event-stream:
              schema:
                type: string
          description: The event stream.
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: invalid_request
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: unauthorized, invalid_api_key or invalid_token
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: insufficient_scope, session_required, account_required, turnstile_required, bad_origin
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: not_found
        '429':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: rate_limited, too_many_in_flight, anonymous_limit, daily_spend_limit
      security:
      - apiKey:
        - read
      - bearer:
        - read
      - cookie: []
      - {}
      summary: Progress events of a job
      tags:
      - Jobs
    servers:
    - description: 'The one public base for every client: https://scribiz.com/api (Better Auth at /api/auth, remote MCP at https://scribiz.com/mcp). The proxy routes both paths to this API.'
      url: https://scribiz.com/api
components:
  schemas:
    Error:
      properties:
        error:
          additionalProperties: true
          properties:
            code:
              description: snake_case.
              type: string
            engineCode:
              description: The engine's own code (QUOTA, SOURCE_UNAVAILABLE, ...) when there is one.
              type: string
            hint:
              type: string
            message:
              type: string
          required:
          - code
          - message
          type: object
      required:
      - error
      type: object
    ContextOptions:
      additionalProperties: false
      properties:
        detail:
          enum:
          - transcript
          - brief
          - full
        diarize:
          oneOf:
          - type: boolean
          - const: auto
        effort:
          deprecated: true
          description: 'Removed on 2026-10-09. Still accepted, whatever it holds, and ignored: the job runs as it would without it. Send `detail: "transcript"` for the words alone and `proofread: "full"` for the full proofread.'
        glossary:
          description: Accounts only. Terms, product names, and contact names for synthesis glossary corrections.
          items:
            maxLength: 100
            type: string
          maxItems: 50
          type: array
        include_words:
          description: Accounts only. Keep the word list in the result.
          type: boolean
        owner:
          additionalProperties: false
          description: Accounts only. Account owner name, notes, glossary, and time zone.
          properties:
            glossary:
              items:
                maxLength: 100
                type: string
              maxItems: 50
              type: array
            name:
              maxLength: 100
              type: string
            notes:
              maxLength: 300
              type: string
            time_zone:
              maxLength: 80
              type: string
          type: object
        proofread:
          oneOf:
          - type: boolean
          - enum:
            - terms
            - full
            - auto
        quality:
          description: Accounts only.
          enum:
          - standard
          - high
        visual:
          additionalProperties: false
          description: Accounts only.
          properties:
            fps:
              maximum: 2
              minimum: 0.1
              type: number
            max_scenes:
              maximum: 200
              minimum: 1
              type: integer
          type: object
        vocabulary:
          description: Accounts only.
          items:
            maxLength: 100
            type: string
          maxItems: 50
          type: array
      type: object
    ErrorInfo:
      description: 'The engine''s error: what a failed job carries and what the SSE `error` event holds.'
      properties:
        code:
          type: string
        hint:
          type: string
        message:
          type: string
        retryAfterMs:
          type: number
        retryable:
          type: boolean
        scope:
          enum:
          - job
          - queue
          - account
        stage:
          type: string
        status:
          type: number
      required:
      - code
      - message
      - retryable
      - scope
      - stage
      type: object
    AskRequest:
      additionalProperties: false
      description: Exactly one of job_id or context.
      properties:
        context:
          description: 'The Context of a finished job, exactly as it was returned (at most 1 MB). A link or a file reference is not a Context: it is refused with 400.'
          type: object
        job_id:
          type: string
        question:
          maxLength: 8000
          minLength: 1
          type: string
      required:
      - question
      type: object
    Job:
      properties:
        attempt:
          type: integer
        cache_hit:
          type:
          - boolean
          - 'null'
        cancel_requested:
          type: boolean
        created_at:
          description: Epoch milliseconds.
          type: integer
        degraded:
          type: object
        error:
          oneOf:
          - $ref: '#/components/schemas/ErrorInfo'
          - type: 'null'
        estimate:
          oneOf:
          - $ref: '#/components/schemas/Quote'
          - type: 'null'
        events_url:
          type: string
        expires_at:
          type: integer
        finished_at:
          type:
          - integer
          - 'null'
        input:
          type: object
        job_id:
          type: string
        minutes_charged:
          type:
          - number
          - 'null'
        mode:
          type: string
        progress:
          description: 0 to 1, never going backwards; null until known.
          type:
          - number
          - 'null'
        result:
          oneOf:
          - $ref: '#/components/schemas/Context'
          - type: 'null'
        result_url:
          type: string
        stage:
          type:
          - string
          - 'null'
        started_at:
          type:
          - integer
          - 'null'
        status:
          enum:
          - queued
          - running
          - succeeded
          - failed
          - canceled
      required:
      - job_id
      - status
      - mode
      - estimate
      - result
      - error
      - events_url
      - result_url
      - created_at
      - expires_at
      type: object
    JobCreated:
      properties:
        degraded:
          type: object
        estimate:
          $ref: '#/components/schemas/Quote'
        events_url:
          type: string
        idempotent_replay:
          type: boolean
        job_id:
          type: string
        mode:
          type: string
        queue_position:
          type: integer
        result_url:
          type: string
        status:
          type: string
        upload_id:
          type: string
      required:
      - job_id
      - status
      - events_url
      - result_url
      - estimate
      type: object
    Context:
      description: 'The result of a video: transcript, what was on screen, summary and chapters. Times are seconds. The same JSON the CLI writes with --format json.'
      properties:
        coverage:
          type: object
        id:
          description: youtube:<id>, instagram:<id>, ... or local:<key> for an upload.
          type: string
        meta:
          type: object
        produced:
          type: object
        schema:
          const: 1
        source:
          type: object
        synthesis:
          type:
          - object
          - 'null'
        tiers:
          items:
            type: object
          type: array
        transcript:
          type:
          - object
          - 'null'
        usage:
          type: object
        visual:
          type:
          - object
          - 'null'
        warnings:
          items:
            type: object
          type: array
      required:
      - schema
      - id
      - meta
      - source
      - transcript
      - visual
      - synthesis
      - tiers
      - usage
      - warnings
      type: object
    AskResponse:
      properties:
        answer:
          type: string
        citations:
          items:
            properties:
              end:
                type: number
              start:
                type: number
              text:
                type: string
            required:
            - start
            - end
            - text
            type: object
          type: array
        minutes_charged:
          type: number
        notes:
          items:
            type: string
          type: array
      required:
      - answer
      - citations
      - minutes_charged
      type: object
    ContextRequest:
      additionalProperties: false
      description: Exactly one of url or upload_id.
      properties:
        language:
          oneOf:
          - type: string
          - items:
              type: string
            maxItems: 5
            type: array
        mode:
          default: auto
          enum:
          - auto
          - captions
          - audio
          - visual
          - full
          - listen
          - watch
          - both
        options:
          $ref: '#/components/schemas/ContextOptions'
        replaces_job_id:
          description: Optional. When a second recording of the same moment arrives after a single-track upload job was already created, pass that job id (same owner, same primary upload hash) to credit its usage minutes and replace it in job listings.
          type: string
        secondary_offset_seconds:
          description: 'Only with secondary_upload_id. Add it to a time in the second recording to place it on the first one''s timeline (the second device''s start minus the first''s, in seconds). A hint: the offset is measured from the words.'
          maximum: 3600
          minimum: -3600
          type: number
        secondary_upload_id:
          description: 'Only with upload_id, and a different upload. A second recording of the same moment (another device''s microphone): both are read and fused into one transcript on the timeline of upload_id. Charged as one job of the longer of the two lengths.'
          type: string
        turnstile_token:
          description: Required for anonymous Listen and Watch when the server has Turnstile on.
          type: string
        upload_id:
          type: string
        url:
          maxLength: 2048
          type: string
      type: object
    Quote:
      properties:
        cached:
          description: 'Everything is already stored: nothing is charged.'
          type: boolean
        caption_credits:
          description: Maximum caption credits for a strict YouTube request. Media minutes are zero.
          minimum: 0
          type: integer
        charges_as:
          enum:
          - caption-item
          - captions
          - audio
          - visual
          - full
        length_known:
          const: false
          description: Present (false) when the length of the source could not be read before the run (a YouTube link that yt-dlp and the YouTube page both refused; a direct media link not yet downloaded). The job is charged from the length it measures.
        max_media_seconds:
          description: 'Only with `length_known: false` on a YouTube link: the longest stretch the job reads (a clip that ends there): never more than the plan allows per video and never more than the minutes left. `minutes` is the most the job can then use. When the server can get the video''s own captions they answer instead, also for a longer video, and the job costs less.'
          type: number
        media_seconds:
          description: 'Seconds of media the quote is for; null when the length is not known (`length_known: false`).'
          type:
          - number
          - 'null'
        minutes:
          description: 'Minutes this job uses when it runs as quoted (0 when cached), including the half minute for each media minute when the full proofread is part of it (`proofread: "full"` or a `vocabulary`). It is charged only if the pass runs. With `length_known: false`: the most it can use.'
          type: number
        tiers:
          items:
            enum:
            - captions
            - audio
            - visual
            - synthesis
          type: array
      required:
      - minutes
      - media_seconds
      - tiers
      - cached
      - charges_as
      type: object
  securitySchemes:
    apiKey:
      description: 'An API key (sbz_live_...), as X-API-Key. Keys are made in the dashboard or by `scribiz login`. Each key has one scope, named in an operation''s security requirement. `all`: Everything a key can do: start jobs, upload, ask, cancel, the Gemini proxy and listing keys. Includes read. `mcp`: The remote MCP server at /mcp. Includes read. `read`: Read jobs and their events.'
      in: header
      name: X-API-Key
      type: apiKey
      x-scopes:
        all: 'Everything a key can do: start jobs, upload, ask, cancel, the Gemini proxy and listing keys. Includes read.'
        mcp: The remote MCP server at /mcp. Includes read.
        read: Read jobs and their events.
    bearer:
      description: 'An API key (sbz_live_...) or a session token from the device flow. Each key has one scope, named in an operation''s security requirement. `all`: Everything a key can do: start jobs, upload, ask, cancel, the Gemini proxy and listing keys. Includes read. `mcp`: The remote MCP server at /mcp. Includes read. `read`: Read jobs and their events. A session token has every scope.'
      scheme: bearer
      type: http
      x-scopes:
        all: 'Everything a key can do: start jobs, upload, ask, cancel, the Gemini proxy and listing keys. Includes read.'
        mcp: The remote MCP server at /mcp. Includes read.
        read: Read jobs and their events.
    cookie:
      description: The browser session (same-origin /api/*).
      in: cookie
      name: better-auth.session_token
      type: apiKey
x-refined-from:
- openapi.json
- scribiz-openapi.json