Badge

GET/api/v1/badges/public-key

Get the verification public key

The service Ed25519 key used to verify badge signatures.

Authorization

bearer_token

AuthorizationBearer <token>

In: header

Response Body

`application/json`

curl -X GET "https://example.com/api/v1/badges/public-key"

{  "public_key": "string",  "signature_alg": "string"}

POST/api/v1/badges/render

Render a badge

Renders the template with live state and returns the result as JSON.

Authorization

bearer_token

AuthorizationBearer <token>

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

include_metadata?boolean

Include signed metadata in the response

parameters?

Render parameters

preview?boolean

Preview mode (skips cache writes)

template_id*string

Template identifier

version?|

Optional template version to pin

Formatint32

Range0 <= value

Response Body

`application/json`

curl -X POST "https://example.com/api/v1/badges/render" \  -H "Content-Type: application/json" \  -d '{    "template_id": "string"  }'

{  "cache": {    "hit": true,    "ttl_seconds": 0  },  "content_type": "string",  "render_id": "string",  "state_hash": "string",  "svg": "string",  "template_id": "string",  "template_version": 0,  "verification": null}

GET/api/v1/badges/render/{template_file}

Render a badge as SVG

Renders the template with live state and returns the SVG image.

Authorization

bearer_token

AuthorizationBearer <token>

In: header

Path Parameters

template_file*string

Template identifier, optionally suffixed with .svg

Query Parameters

version?integer

Optional template version to pin

Formatint32

Range0 <= value

parameters*

Render parameters supplied as additional query string entries

Response Body

`image/svg+xml`

curl -X GET "https://example.com/api/v1/badges/render/string?property1=string&property2=string"

Empty

GET/api/v1/badges/state-sources

List state sources

Authorization

bearer_token

AuthorizationBearer <token>

In: header

Query Parameters

page?integer

Formatint64

Range0 <= value

page_size?integer

Formatint64

Range0 <= value

Response Body

`application/json`

curl -X GET "https://example.com/api/v1/badges/state-sources"

{  "pagination": {    "has_more": true,    "page": 0,    "page_size": 0,    "total": 0  },  "sources": [    {      "created_at": "2019-08-24T14:15:22Z",      "fallback": null,      "field_template": "string",      "key_template": "string",      "kind": "literal",      "owner_id": "string",      "projection": null,      "source_id": "string",      "staleness": null,      "updated_at": "2019-08-24T14:15:22Z"    }  ]}

POST/api/v1/badges/state-sources

Create a state source

Registers a data source that feeds dynamic badge fields.

Authorization

bearer_token

AuthorizationBearer <token>

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

fallback?unknown

Fallback values applied when the source is missing or stale

field_template?|

Optional field template for hash/member lookups

key_template*string

Key template with placeholders, e.g. "leaderboard:season:{{season_id}}"

kind*StateSourceKind

State source kind

Value in

"literal"
"kv"
"leaderboard"
"remote_config"
"composite"

projection?unknown

Projection of source values to template variables

staleness?unknown

Staleness tolerance policy

Response Body

`application/json`

curl -X POST "https://example.com/api/v1/badges/state-sources" \  -H "Content-Type: application/json" \  -d '{    "key_template": "string",    "kind": "literal"  }'

{  "created_at": "2019-08-24T14:15:22Z",  "fallback": null,  "field_template": "string",  "key_template": "string",  "kind": "literal",  "owner_id": "string",  "projection": null,  "source_id": "string",  "staleness": null,  "updated_at": "2019-08-24T14:15:22Z"}

GET/api/v1/badges/templates

List badge templates

Authorization

bearer_token

AuthorizationBearer <token>

In: header

Query Parameters

q?string

Full-text search applied to template name and description

name?string

Filter by template name

status?string

Filter by status (draft, active, deprecated, disabled)

include_versions?boolean

Include all versions of each template

page?integer

1-indexed page number

Formatint64

Range0 <= value

page_size?integer

Page size

Formatint64

Range0 <= value

sort_by?string

Sort field (created_at, name, version)

sort_order?string

Sort order (asc or desc)

Value in

"asc"
"desc"

Response Body

`application/json`

curl -X GET "https://example.com/api/v1/badges/templates"

{  "pagination": {    "has_more": true,    "page": 0,    "page_size": 0,    "total": 0  },  "templates": [    {      "animation": null,      "cache": null,      "click_through": null,      "created_at": "2019-08-24T14:15:22Z",      "created_by": "string",      "description": "string",      "fonts": null,      "name": "string",      "placeholders": null,      "state_sources": null,      "status": "draft",      "svg_template": "string",      "template_id": "string",      "thresholds": null,      "updated_at": "2019-08-24T14:15:22Z",      "verification": null,      "version": 0,      "versions": [        {          "created_at": "2019-08-24T14:15:22Z",          "status": "draft",          "version": 0        }      ],      "visibility": "private"    }  ]}

POST/api/v1/badges/templates

Create a badge template

Registers a template with its SVG source and dynamic field bindings.

Authorization

bearer_token

AuthorizationBearer <token>

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

activate?boolean

Activate the first version immediately on create

animation?unknown

Animation policy

cache?

Cache policy

click_through?unknown

Click-through policy

description?|

Optional description

fonts?unknown

Font policy

name*string

Logical template name, unique per owner

placeholders?array<>

Declared placeholders

state_sources?array<>

Bindings from placeholders to registered state sources

svg_template*string

SVG template body with handlebars-style placeholders

thresholds?array<>

Ordered threshold rules

verification?

Verification policy

visibility?BadgeVisibility

Visibility controlling whether the template is renderable anonymously

Value in

"private"
"public"

Response Body

`application/json`

curl -X POST "https://example.com/api/v1/badges/templates" \  -H "Content-Type: application/json" \  -d '{    "name": "string",    "svg_template": "string"  }'

{  "created_at": "2019-08-24T14:15:22Z",  "name": "string",  "status": "draft",  "template_id": "string",  "version": 0,  "visibility": "private"}

GET/api/v1/badges/templates/{template_id}

Get a badge template

Authorization

bearer_token

AuthorizationBearer <token>

In: header

Path Parameters

template_id*string

Query Parameters

include_versions?boolean

Response Body

`application/json`

curl -X GET "https://example.com/api/v1/badges/templates/string"

{  "animation": null,  "cache": null,  "click_through": null,  "created_at": "2019-08-24T14:15:22Z",  "created_by": "string",  "description": "string",  "fonts": null,  "name": "string",  "placeholders": null,  "state_sources": null,  "status": "draft",  "svg_template": "string",  "template_id": "string",  "thresholds": null,  "updated_at": "2019-08-24T14:15:22Z",  "verification": null,  "version": 0,  "versions": [    {      "created_at": "2019-08-24T14:15:22Z",      "status": "draft",      "version": 0    }  ],  "visibility": "private"}

POST/api/v1/badges/templates/{template_id}/activate

Activate a template version

Authorization

bearer_token

AuthorizationBearer <token>

In: header

Path Parameters

template_id*string

Query Parameters

version?integer

Optional template version to act on (defaults to the active version)

Formatint32

Range0 <= value

Response Body

`application/json`

curl -X POST "https://example.com/api/v1/badges/templates/string/activate"

{  "active_version": 0,  "status": "draft",  "template_id": "string",  "version": 0}

POST/api/v1/badges/templates/{template_id}/cache/purge

Purge the render cache

Clears cached renders for the template.

Authorization

bearer_token

AuthorizationBearer <token>

In: header

Path Parameters

template_id*string

Response Body

`application/json`

curl -X POST "https://example.com/api/v1/badges/templates/string/cache/purge"

{  "purged_entries": 0,  "template_id": "string"}

POST/api/v1/badges/templates/{template_id}/deprecate

Deprecate a template version

Authorization

bearer_token

AuthorizationBearer <token>

In: header

Path Parameters

template_id*string

Query Parameters

version?integer

Optional template version to act on (defaults to the active version)

Formatint32

Range0 <= value

Response Body

`application/json`

curl -X POST "https://example.com/api/v1/badges/templates/string/deprecate"

{  "active_version": 0,  "status": "draft",  "template_id": "string",  "version": 0}

POST/api/v1/badges/templates/{template_id}/disable

Disable a template version

Authorization

bearer_token

AuthorizationBearer <token>

In: header

Path Parameters

template_id*string

Query Parameters

version?integer

Optional template version to act on (defaults to the active version)

Formatint32

Range0 <= value

Response Body

`application/json`

curl -X POST "https://example.com/api/v1/badges/templates/string/disable"

{  "active_version": 0,  "status": "draft",  "template_id": "string",  "version": 0}

GET/api/v1/badges/templates/{template_id}/metrics

Get template metrics

Authorization

bearer_token

AuthorizationBearer <token>

In: header

Path Parameters

template_id*string

Response Body

`application/json`

curl -X GET "https://example.com/api/v1/badges/templates/string/metrics"

{  "cache_hit_ratio": 0.1,  "cache_hits": 0,  "cache_misses": 0,  "render_count": 0,  "render_errors": {    "property1": 0,    "property2": 0  },  "render_latency_p50_ms": 0.1,  "render_latency_p95_ms": 0.1,  "template_id": "string",  "verification_failures": 0}

POST/api/v1/badges/templates/{template_id}/versions

Create a template version

Adds a new version of the template's SVG source.

Authorization

bearer_token

AuthorizationBearer <token>

In: header

Path Parameters

template_id*string

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

activate?boolean

Whether the new version immediately becomes the active version

animation?unknown

Animation policy

cache?

Cache policy

click_through?unknown

Click-through policy

description?|

Updated description

fonts?unknown

Font policy

placeholders?array<>

Declared placeholders for the new version

state_sources?array<>

Bindings from placeholders to registered state sources

svg_template*string

SVG template body for the new version

thresholds?array<>

Ordered threshold rules

verification?

Verification policy

Response Body

`application/json`

curl -X POST "https://example.com/api/v1/badges/templates/string/versions" \  -H "Content-Type: application/json" \  -d '{    "svg_template": "string"  }'

{  "active_version": 0,  "status": "draft",  "template_id": "string",  "version": 0}

PUT/api/v1/badges/templates/{template_id}/visibility

Update template visibility

Switches a template between public and private rendering.

Authorization

bearer_token

AuthorizationBearer <token>

In: header

Path Parameters

template_id*string

Query Parameters

version?integer

Optional template version to act on (defaults to the active version)

Formatint32

Range0 <= value

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

visibility*BadgeVisibility

New visibility for the template

Value in

"private"
"public"

Response Body

`application/json`

curl -X PUT "https://example.com/api/v1/badges/templates/string/visibility" \  -H "Content-Type: application/json" \  -d '{    "visibility": "private"  }'

{  "template_id": "string",  "version": 0,  "visibility": "private"}

POST/api/v1/badges/verify

Verify a badge signature

Checks a rendered badge's Ed25519 signature.

Authorization

bearer_token

AuthorizationBearer <token>

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

expires_at*string

Expiry timestamp (RFC3339) from the badge metadata

issued_at*string

Issued-at timestamp (RFC3339) from the badge metadata

public_key?|

Optional issuer public key (base64url). When present, verification uses this key instead of the service signing key, enabling offline/external verification.

signature*string

Signature value from the badge metadata

signature_alg*string

Signature algorithm from the badge metadata

state_hash*string

State hash from the badge metadata

template_id*string

Template identifier from the badge metadata

template_version*integer

Template version from the badge metadata

Formatint32

Range0 <= value

Response Body

`application/json`

curl -X POST "https://example.com/api/v1/badges/verify" \  -H "Content-Type: application/json" \  -d '{    "expires_at": "string",    "issued_at": "string",    "signature": "string",    "signature_alg": "string",    "state_hash": "string",    "template_id": "string",    "template_version": 0  }'

{  "reason": "string",  "template_id": "string",  "template_version": 0,  "valid": true}

GET/badges/public/render/{template_file}

Render a public badge anonymously

Unauthenticated rendering, public templates only.

Path Parameters

template_file*string

Template identifier, optionally suffixed with .svg

Query Parameters

version?integer

Optional template version to pin

Formatint32

Range0 <= value

parameters*

Render parameters supplied as additional query string entries

Response Body

`image/svg+xml`

curl -X GET "https://example.com/badges/public/render/string?property1=string&property2=string"

Empty

Badge

200application/json

200application/json

404

503

200image/svg+xml

404

503

200application/json

503

201application/json

400

503

200application/json

503

201application/json

400

503

200application/json

404

503

200application/json

403

404

503

200application/json

403

404

503

200application/json

403

404

503

200application/json

403

404

503

200application/json

404

503

201application/json

400

404

503

200application/json

403

404

503

200application/json

400

503

200image/svg+xml

404

On this page

`application/json`

`application/json`

`image/svg+xml`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`image/svg+xml`