Quickstart

1. Create an API key

Open Account, API keys and create a key with the catalogs:write, media:write and lists:write scopes. The key is shown once. Keep it in an environment variable:

export TIERO_API_KEY="tiero_sk_..."   # from tiero.io/account/api-keys

2. Upload an image

Images are optional. Upload one as multipart file (PNG, JPEG, WebP, GIF or AVIF, up to 5 MB) and keep the returned media id:

curl https://tiero.io/api/v1/media \
  -H "Authorization: Bearer $TIERO_API_KEY" \
  -F file=@posterizer.png

{ "id": "med_abcdefghijklmnop", "url": "https://img.tiero.io/...", "width": 512, "height": 512, ... }

3. Publish a catalog

Save this as catalog.json. Only spec, slug, title and items with an id and a name are required; the catalog spec lists every other field.

{
  "spec": "tiero-catalog/1",
  "slug": "my-first-catalog",
  "title": "My first catalog",
  "items": [
    { "id": "posterizer", "name": "Posterizer", "image": "med_abcdefghijklmnop" },
    { "id": "limitless", "name": "Limitless Range" },
    { "id": "clamps", "name": "Clamps" }
  ]
}

Then PUT it to the slug. The same call creates the catalog the first time and replaces it after that.

curl -X PUT https://tiero.io/api/v1/catalogs/my-first-catalog \
  -H "Authorization: Bearer $TIERO_API_KEY" \
  -H "Content-Type: application/json" \
  --data @catalog.json

{
  "slug": "my-first-catalog",
  "owner": "you",
  "version": 1,
  "rev": 1,
  "changed": true,
  "itemCount": 3,
  "removedCount": 0,
  "url": "https://tiero.io/c/you/my-first-catalog",
  "warnings": []
}

Send the same file again and you get "changed": false with no version bump, so it is safe to run from a cron job or CI on every build.

4. Read it back

Public reads need no key:

curl https://tiero.io/api/v1/catalogs/you/my-first-catalog

The response is a CatalogDTO with an ETag of "r<rev>". Send it back as If-None-Match to get a 304 when nothing changed. Catalogs with more than 60 items return "itemsPaged": true; page through /items instead.

5. Save a tier list

A list places item ids into tiers. Items you leave out stay in the unranked pool.

curl https://tiero.io/api/v1/lists \
  -H "Authorization: Bearer $TIERO_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
    "catalog": "you/my-first-catalog",
    "title": "My ranking",
    "visibility": "public",
    "schemaVersion": 1,
    "board": {
      "tiers": [
        { "id": "s", "label": "S", "color": "#e11d48", "order": 0, "itemSlugs": ["posterizer"] },
        { "id": "a", "label": "A", "color": "#f97316", "order": 1, "itemSlugs": ["clamps", "limitless"] }
      ]
    }
  }'

The response is { "list": ListDTO, "warnings": [] }. list carries the id, revision and public url; warnings names anything tiero adjusted, such as a downgraded visibility. To update the list later, PUT /api/v1/lists/{id} with If-Match: <list.revision>; a stale revision answers 412 revision_conflict.

6. Read the consensus

curl https://tiero.io/api/v1/catalogs/you/my-first-catalog/consensus

Consensus is computed from public lists in the background. Until a catalog has enough of them, the endpoint answers 404 with the current count:

{ "error": { "code": "consensus_not_ready", "message": "...", "details": { "listCount": 1 } } }

Next steps

• Every endpoint, with parameters and responses: API reference.
• Show your name and logo on boards: Branding.
• Put a board or the builder on your own site: Embeds.
• Rate limits and sizes: Limits.