Authentication

Torii authenticates every request with a bearer API token. Send it in the Authorization header:

Authorization: Bearer <your-token>

A missing or invalid token returns 401:

{ "ok": false, "error": { "code": "auth_required", "message": "missing bearer token" } }

Scopes

A token carries one or more scopes. A request that needs a scope the token lacks returns 403 forbidden_scope.

Scope	Grants
`read`	Discovery and fetch — `search`, `posts`, `user`, `detail`, `comments`, feeds. The scope most consumers need.
`write`	Publishing / mutations (e.g. posting a reply on platforms that support it). Write verbs are irreversible and also require `confirm=true`.
`admin`	Token and capability management.

Ask your Torii operator for a token with the scopes you need. Tokens are revocable — a revoked token immediately returns 401.

Public endpoints (no token)

Three routes are intentionally un-gated so a browser element can load them without a bearer it cannot send:

GET /v1/health

Liveness + light fleet stats.

GET /v1/media

The image/video proxy — an <img> or <video> points straight at it.

GET /v1/preview

The hover-to-play preview clip — a <video> points straight at it.

These are SSRF-allowlisted to known CDN hosts and serve no account data. POST /v1/preview/warm (a server-to-server render trigger) does require a token.

Example

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

import requests

r = requests.get(
    "https://api.torii.t.bldr.tw/v1/task-sources",
    headers={"Authorization": f"Bearer {token}"},
)
r.raise_for_status()
sources = r.json()

const res = await fetch("https://api.torii.t.bldr.tw/v1/task-sources", {
  headers: { Authorization: `Bearer ${token}` },
});
const sources = await res.json();

Getting Started

API Reference

Scopes

Public endpoints (no token)

GET /v1/health

GET /v1/media

GET /v1/preview

Example

​Scopes

​Public endpoints (no token)

GET /v1/health

GET /v1/media

GET /v1/preview

​Example

Scopes

Public endpoints (no token)

Example