xtrakt docs

Send a YouTube Short, Instagram post/reel or TikTok video URL, a short prompt and a JSON Schema. xtrakt watches the video and returns JSON that matches your schema.

Authentication

Send Authorization: Bearer <API key> on every request. To get a key, ask Unai.

POST /api/v1/extract

curl -sS -X POST https://xtrakt.uesteibar.com/api/v1/extract \
  -H "authorization: Bearer $XTRAKT_API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "url": "https://www.youtube.com/shorts/l9TuyjsZYOU",
    "prompt": "Summarize this video and say whether coffee is mentioned.",
    "schema": {
      "type": "object",
      "properties": {
        "summary": { "type": "string", "description": "One or two sentences" },
        "mentions_coffee": { "type": "boolean", "description": "True if coffee is shown or mentioned" }
      },
      "required": ["summary", "mentions_coffee"],
      "additionalProperties": false
    }
  }'

Request body (JSON, max 64 KB)

`url`	HTTPS link to an Instagram post, reel or tv (`/p/`, `/reel/`, `/reels/`, `/tv/`) or a YouTube Short, `watch?v=` or `youtu.be` link, or a TikTok video (`tiktok.com/@user/video/…`, `vm.tiktok.com/…`, `vt.tiktok.com/…`, `tiktok.com/t/…`). TikTok photo posts are not supported. No extra query parameters on YouTube links.
`prompt`	What to extract. 1 to 500 characters.
`schema`	The shape of the answer, as JSON Schema. Give each field a `description` saying what it should contain. See below.

Unknown fields are rejected.

Schema rules

The root must be {"type": "object"}. Only the keywords listed here are accepted; anything else returns invalid_schema naming the keyword.

type (string, number, integer, boolean, object, array, null; use ["string", "null"] for optional values)
description, title
properties, required, additionalProperties (true or false)
items, minItems, maxItems
enum, minimum, maximum, format (date, date-time, time), anyOf

Not supported: pattern, minLength, const, allOf, $ref and similar. Limits: 16 KB, 8 levels deep, 200 nodes.

If a value is not in the video, you get null when your schema allows it, otherwise the answer may be a guess. Make optional fields nullable.

Success (200)

{
  "extraction_id": "ext_0b6f2c1e-8a1d-4f5e-9c7a-3d2e1f4a5b6c",
  "data": { "summary": "…", "mentions_coffee": true },
  "source": { "provider": "youtube", "url": "https://www.youtube.com/shorts/l9TuyjsZYOU" }
}

Errors

{
  "extraction_id": "ext_0b6f2c1e-8a1d-4f5e-9c7a-3d2e1f4a5b6c",
  "error": { "code": "invalid_schema", "message": "schema.properties.a: unsupported keyword \"pattern\"" }
}

code	HTTP	meaning
`unauthorized`	401	Missing or wrong API key.
`invalid_request`	400	Bad JSON, unknown field, or bad prompt. Includes a message.
`invalid_schema`	400	Schema uses something not supported. Includes a message.
`payload_too_large`	413	Request body over 64 KB.
`unsupported_url`	422	Not a supported Instagram, TikTok or YouTube URL.
`url_source_inaccessible`	422	Private, removed or blocked post, or it timed out.
`url_source_over_limit`	422	Post too big, or the server is busy. Retry later.
`url_video_too_large`	422	A video is over 50 MB.
`url_video_too_long`	422	Video too long: YouTube over 30 minutes, Instagram/TikTok over 5 minutes in total.
`invalid_extraction`	502	The result could not be made to match your schema.
`extraction_failed`	502	Extraction failed or timed out. Retry.
`server_misconfigured`	500	Server problem. Report it with the extraction_id.

Good to know

Only public posts and videos work.
Requests time out after 90 seconds.
The response always matches your schema or is an error, but check results that matter: matching the schema does not guarantee the content is correct.

Tracing

Every response has an extraction_id (also in the x-extraction-id header). Include it when reporting a problem.