Introduction - Torii API

Torii is a pure-Go crawler for 19 social platforms (TikTok, Douyin, YouTube, Weibo, Bilibili, Instagram, Threads, Facebook, X, Twitch, Rumble, and more), fronted by one small HTTP API. Every platform speaks the same request shape and the same normalized response, so a consumer integrates once and adds platforms by name, not by code.

The model in one paragraph

Every acquisition is a task: you POST /v1/tasks with a source (the platform), an action (what to do — search, posts, detail, comments, …), and params. Torii queues the work, crawls it on a worker that holds the platform session, and returns a normalized Envelope of items when you poll the task. You never touch a browser, a signature, or a platform cookie.

One shape, many platforms

source + action + params in; a normalized Envelope of Item cards out. The same for every platform.

Honest provenance

Every response says where the bytes came from — live, cache, empty, or blocked — and never fabricates a result.

Media proxied, never raw

Covers and video stream through /v1/media and /v1/preview; the consumer never holds an expiring, IP-bound CDN URL.

Capabilities are discoverable

GET /v1/task-sources lists every platform.action that actually exists, so nothing is hardcoded on the caller.

For agents & LLMs

Building on Torii from an agent? There’s a single, self-contained skill file that teaches the whole API — the submit→poll→read loop, every action’s return shape, the full schema, the error model, and the media/preview contract — in one plain-text document you can fetch and read directly:

torii-api-agent.txt — the agent skill doc

Raw markdown, served as plain text. Point your agent at https://apidoc.torii.t.bldr.tw/torii-api-agent.txt and it has everything it needs to call Torii correctly — including the empty ≠ blocked contract it must never guess around.

Base URL

All endpoints are versioned under /v1.

https://api.torii.t.bldr.tw

What you can do

Verb	What it returns
`search`	Keyword results as `Item` cards
`posts`	A creator’s own videos/posts
`user`	A creator’s profile: name, handle, followers, post count, URL
`detail`	One post’s full detail, including a playable `media[].url`
`comments`	A post’s comments (threaded where the platform supports it)
`hot` / `recommended` / `trending`	Platform feeds and trend boards

Not every platform supports every verb — ask GET /v1/task-sources for the exact set. A verb a platform genuinely lacks returns unsupported (a 404), never a fabricated answer.

Next steps

Authentication

Get a bearer token and understand scopes.

Quickstart

Submit your first task and read the result.

API Reference

The task lifecycle, the Envelope, and error codes.

Agent skill doc

The whole API as one plain-text file an LLM can read directly.

​The model in one paragraph