API v2 Overview

v2 is a Cloudflare Worker. Unlike v0 and v1, which each publish a single fixed snapshot of the taxonomy, v2 serves versioned schemas: every request names the schema version it wants, and that version's content is pinned.

Schema versions

A schema version id has the canonical form type@YYYY-MM-DD or type@YYYY-MM-DD-beta — for example, an ai datachain type released on a given date. List what is published today:

curl https://api.dtpr.io/api/v2/schemas

{
  "ok": true,
  "versions": [
    { "id": "…", "status": "beta", "created_at": "…", "content_hash": "…" }
  ]
}

Use a version id from that list wherever the routes below show {version}. Both the plain ai@2026-01-01 and URL-encoded ai%402026-01-01 forms are accepted. An unregistered version returns 404 with a hint pointing back at GET /api/v2/schemas.

Endpoints

Read

Query parameters on the category and element endpoints:

• locales — Comma-separated locale codes to filter localized content
• fields — Comma-separated field names to project. The element list returns id, title, and category_id by default; the single-element endpoint returns everything
• category_id — (element list) Restrict to one category
• query / locale — (element list) Relevance-order the list by a search term
• limit / cursor — (element list) Page through results. Default 50, maximum 200; the response carries meta.next_cursor

Icons

v2 icons are composed — a shape and a symbol combined at request time — rather than served as flat files. {variant} is default, dark, or one of the context values the element's category declares (each of which also accepts a .dark companion, as in icon.vendor.dark.svg). A variant a category does not declare returns 404 with the valid list. This is the main structural difference from the frozen v0 and v1 icon namespaces, which serve the original flat SVGs at /api/v0/icons/{id}.svg and /api/v1/icons/{id}.svg.

Validation

These are POST because they take a document to check, not because they store anything. A document that fails validation is answered with 200 and { "ok": false, "errors": [...] } — the HTTP status describes the request, not the verdict.

Response envelope

Every v2 JSON response is wrapped in an envelope with an ok flag:

{
  "ok": true,
  "version": "…",
  "elements": []
}

This is a break from v0 and v1, which return bare arrays. A consumer moving from v1 to v2 has to unwrap.

Conventions shared with v1

• Locale arrays — User-facing text is returned as arrays of { locale, value } objects
• locales filtering — Same comma-separated form, and it works on every v2 read endpoint
• Public and unauthenticated — CORS is enabled for all origins

Next steps

• API overview — All three surfaces and their base URLs
• Concepts: Taxonomy — Elements, categories, and datachains
• Concepts: Localization — How locale arrays and locales work