Quickstart - Torii API

A Torii crawl is submit → poll → read. This page runs one end to end.

Submit a task

POST /v1/tasks with a source, an action, and params. Torii queues it and returns a task_id immediately.

curl -X POST https://api.torii.t.bldr.tw/v1/tasks \
  -H "Authorization: Bearer $TORII_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "source": "youtube",
    "action": "search",
    "params": { "query": "air fryer recipe", "limit": 12, "media": "video" }
  }'

Response — 202 Accepted

{ "task_id": 84213, "status": "queued" }

Poll until it finishes

GET /v1/tasks/{id}. While it runs, status is queued or running; when done it is succeeded (or failed), and a succeeded task carries the full result envelope.

curl https://api.torii.t.bldr.tw/v1/tasks/84213 \
  -H "Authorization: Bearer $TORII_TOKEN"

Response

{
  "task_id": 84213,
  "status": "succeeded",
  "result": {
    "ok": true,
    "source": "live",
    "count": 12,
    "items": [ /* … Item cards … */ ],
    "ms": 1840
  }
}

Add ?wait=8000 to POST /v1/tasks to block up to 8 seconds for the result inline, so a fast crawl needs no polling. If it isn’t done in time, you still get a task_id to poll.

Read the result

The result is a normalized Envelope. source tells you the provenance (live / cache / empty / blocked); items is an array of normalized Item cards. Media URLs are torii-hosted, so they never expire in your hands.

One Item

{
  "id": "youtube:q7u7VagLHio",
  "type": "video",
  "provider": "youtube",
  "text": "Go FREEMIUM to Reduce Your Customer Acquisition Cost",
  "author": "…",
  "author_url": "https://www.youtube.com/@…",
  "url": "https://www.youtube.com/watch?v=q7u7VagLHio",
  "thumb": "/v1/media?u=…",
  "media": [{ "kind": "video", "url": "/v1/media?u=…&kind=video&platform=youtube", "w": 640, "h": 360 }],
  "preview": { "url": "/v1/preview?platform=youtube&id=q7u7VagLHio", "w": 426, "h": 240, "seconds": 240, "status": "pending" },
  "duration_s": 363,
  "stats": { "likes": 10, "comments": 0, "shares": 0, "views": 207 },
  "provenance": "live"
}

Discover what a platform supports

Before you hardcode a platform.action, ask the catalog:

curl https://api.torii.t.bldr.tw/v1/task-sources \
  -H "Authorization: Bearer $TORII_TOKEN"

Each row is a real capability — { "name": "youtube.search", "group": "scrape", "summary": "…" }. If a platform.action isn’t listed, it genuinely doesn’t exist, and calling it returns unsupported. See API Reference → Sources.

Where to go next

The task lifecycle & Envelope

Statuses, retry/cancel, the full Envelope and Item schema, and error codes.

Media & previews

The image/video proxy, hover-to-play previews, and account health.

​Discover what a platform supports

​Where to go next

The task lifecycle & Envelope

Media & previews

Discover what a platform supports

Where to go next