Developers
Build on tiero: read catalogs and consensus boards, publish your own templates, embed boards and the builder, and connect agents.
Start here
- Quickstart Create an API key, publish a catalog and read it back with curl in five minutes.
- Catalog spec v1 The JSON format for templates: items, groups, tiers, branding and credits.
- API reference Every endpoint under /api/v1, with auth, parameters and responses.
- Embeds Free read-only boards and the premium embeddable builder.
- Branding and attribution Verified domains, provider branding and the credit line every board carries.
- Limits Rate limits, request sizes and catalog limits.
- tiero CLI Validate and push catalogs from a repo or a CI job.
- Remote MCP server Soon Let agents search catalogs, read consensus and save tier lists.
The basics
Everything lives under one versioned base path, https://tiero.io/api/v1/, and speaks JSON. The full
machine-readable description is at /api/v1/openapi.json (OpenAPI 3.1), so you can
generate a client or load it into your own tools.
- Catalogs (also called templates) are the items people rank. Providers publish them with
PUT /api/v1/catalogs/{slug}. - Lists are tier lists people make from a catalog.
- Consensus is the board built from every public list of a catalog, at
GET /api/v1/catalogs/{owner}/{slug}/consensus.
Public reads need no key and are cached for 60 seconds, with Access-Control-Allow-Origin: *, so a
browser on any site can call them.
Authentication
Writes need one of three credentials:
| Credential | Used by | How |
|---|---|---|
| API key | Servers, scripts, CI | Authorization: Bearer tiero_sk_..., created at Account, API keys with the scopes it needs |
| Session | tiero.io itself | The sign-in cookie. Cross-site writes are refused. |
| Embed token | The embedded builder | Issued after a user connects their account inside an embed. See Embeds. |
API key scopes are catalogs:write, media:write, lists:read and lists:write. Keys are shown once when you create them; store them in an environment variable, never
in code.
Errors
Every error has the same shape. code is stable and safe to branch on; message is for people.
Codes are only ever added, never renamed.
{
"error": {
"code": "validation_failed",
"message": "Catalog is invalid",
"details": { "issues": [{ "pointer": "/items/0/id", "code": "invalid_format", "message": "Invalid id" }] }
}
}A 429 carries Retry-After: wait that many seconds and try again. See Limits for the numbers.