POST /v1
Submit an extraction job with POST /v1: request fields for 1–200 videos, an inline or saved schema, an optional webhook, the response and every error.
Request
One call submits anything from a single video to two hundred. videos is always a list, so growing from one to many changes the length of an array rather than the endpoint you call.
batch_too_large and nothing is queued.name and may set a type — one of verbatim-string, string, number, integer, boolean, date or enum (which also takes options). A type ending in [], such as string[], holds a list of values — not on the first column, and not on an enum. A description is optional and steers the extraction; without one the column name is used. Without a type, the first column is verbatim-string and the rest are string. Up to 12 columns, and the same schema runs against every video in the call. The older object form, { columns, multiple, max_rows }, is still accepted.schema: { template, descriptions }: a typed JSON template in place of the column list, with a descriptions object giving one description per field. Nested objects and nested lists are refused. See /docs/guides/writing-a-schema.multiple, keeps at most this many rows per video and drops the rest. 1 to 500.schema_version; the latest is used otherwise.Send an Idempotency-Key header to make a retry of this call safe.
Response
Extraction runs on a queue, so this answers 202 Accepted with an id rather than with rows. videos is how many were queued and items lists them. Read the job to collect the rows, or register a webhook_url and be told when there is something to collect.
Errors
400 invalid_request for a malformed body or a schema that fails validation, and 400 batch_too_large for more than 200 videos, with the message 200 video limit per batch exceeded. 401 for a bad key. 402 insufficient_credits when the workspace is out of credits. 403 plan_limit for a webhook_url on Free, and 403 forbidden for a closed workspace. 404 schema_not_found for an unknown schema_id. 409 for an Idempotency-Key reused with a different body. 429 over the per-minute limit. The full list is on error codes.
no_captions — costing nothing, while the rest of the job carries on.