Icon routes
Icon routes
Content-Type: image/svg+xml; charset=utf-8. Cache-Control varies by version stability (see conventions).Summary
| Route | Purpose | Versioned? |
|---|---|---|
GET /api/v2/shapes/:shape.svg | Bare shape primitive. | no |
GET /api/v2/schemas/:version/symbols/:symbol_id.svg | Release-pinned symbol SVG. | yes |
GET /api/v2/schemas/:version/elements/:element_id/icon[.<variant>].svg | Composed icon (shape × symbol × variant). | yes |
The conceptual model behind these routes — shape, symbol, variant, and the innerColor rule — is covered in Icon composition.
GET /api/v2/shapes/:shape.svg
Return a 36×36 SVG containing only the shape primitive.
| Param | In | Description |
|---|---|---|
shape | path | One of circle, hexagon, octagon, rounded-square. |
HTTP/1.1 200 OK
Content-Type: image/svg+xml; charset=utf-8
Cache-Control: public, max-age=31536000, immutable
Errors: bad_request (400) for ids outside [a-zA-Z0-9_-]; not_found (404) for unknown shape names (the response fix_hint lists the valid shape set).
GET /api/v2/schemas/:version/symbols/:symbol_id.svg
Return the release-pinned symbol SVG.
| Param | In | Description |
|---|---|---|
version | path | Canonical version or alias. |
symbol_id | path | Matches element.symbol_id. Whitelisted to [a-zA-Z0-9_-]. |
HTTP/1.1 200 OK
Content-Type: image/svg+xml; charset=utf-8
DTPR-Content-Hash: sha256-…
Cache-Control: public, max-age=3600 # beta
Cache-Control: public, max-age=31536000, immutable # stable
GET /api/v2/schemas/:version/elements/:element_id/icon[.<variant>].svg
Return a composed icon for an element.
| Param | In | Description |
|---|---|---|
version | path | Canonical version or alias. |
element_id | path | Whitelisted to [a-zA-Z0-9_-]. |
variant | path | Optional suffix. Valid values: default (implicit — omit to use), dark, or any context.value.id defined on the element's category. |
URL forms:
/api/v2/schemas/ai@2026-04-16-beta/elements/purpose.example/icon.svg # default
/api/v2/schemas/ai@2026-04-16-beta/elements/purpose.example/icon.dark.svg # dark
/api/v2/schemas/ai@2026-04-16-beta/elements/purpose.example/icon.commercial.svg # context-colored
Fallback behavior
The route first attempts a pre-baked R2 point-read. On miss, it logs an icon_miss_fallback event and composes the SVG on the fly using the same pure compositor as the build step — the fallback output is byte-identical to the pre-baked output. Callers observe the same response; only the Cache-Control max-age differs (60 s for beta miss, 3600 s for beta hit, immutable for stable).
Errors
| Code | HTTP | Meaning |
|---|---|---|
bad_request | 400 | element_id / variant outside [a-zA-Z0-9_-]. |
not_found | 404 | Unknown version, element, symbol, or variant. fix_hint lists valid variants for unknown_variant. |
Examples
curl -s -i https://api.dtpr.io/api/v2/shapes/hexagon.svg
curl -s -i https://api.dtpr.io/api/v2/schemas/ai@2026-04-16-beta/symbols/example-symbol.svg
curl -s -i https://api.dtpr.io/api/v2/schemas/ai@2026-04-16-beta/elements/purpose.example/icon.dark.svg