API Documentation

Most endpoints support content negotiation: browsers receive an HTML page, API clients receive JSON. Append ?format=json to force JSON from any browser. Badge class data is served as schema.org EducationalOccupationalCredential JSON-LD.

Badge Classes

Method & Route	Description
GET /badge-classes	Browse or search badge classes. Returns HTML (browser) or JSON (API). Supports `?q` (full-text), `?category`, `?issuer_did`, `?skill` (URI), `?status` (default `active`; `all` includes archived), `?limit` (default 50, max 200), `?offset`.
GET /badge-classes/:id	Single badge class by its identifier (URL-encoded). Returns HTML (browser) or JSON (API). HTML view shows skills, alignments, issuer, proof status, and pathways this badge is part of. JSON includes a `partOf` array.

Identifiers: Badge class identifiers are the canonical resolvable URLs returned by the issuer's public API (e.g. https://issuer.badgau.net/badgeclasses/public/{uuid}). URL-encode them when using as a path parameter.

Lifecycle: Badge classes are automatically archived when they disappear from their source node and reactivated if they reappear. Only active badge classes are returned by default.

Nodes

Method & Route	Description
GET /nodes	List registered nodes and their crawl status.
POST /nodes/register	Register a new node. Body: `{ url, name?, api_endpoint?, node_type? }`. Triggers an immediate crawl.
POST /ping	Signal that a node has new or updated content. Body: `{ url }`. Triggers an immediate crawl of that node.

Peers

Method & Route	Description
GET /peers	List known peer OpenSkillPaths registries and their sync status.
POST /peers/register	Register a peer registry. Body: `{ url }`. Triggers an immediate node list sync.

Pathways

Each pathway has a canonical identifier URL: http://localhost:3000/pathways/{uuid}. This URL serves HTML to browsers and JSON to API clients.

Method & Route	Description
GET /pathways	Browse pathways. Returns HTML or JSON. Supports `?q`, `?achievement_id` (find pathways containing a badge), `?limit`, `?offset`.
GET /pathways/:id	Single pathway by UUID, numeric ID, or URL-encoded master achievement_id. Returns HTML or JSON with full sections, slots, and enriched badge class data.
GET /pathways/:id/ctdl	Same pathway as a CTDL `ceterms:Pathway` JSON-LD document for Credential Engine interoperability.
POST /pathways	Submit a signed pathway. Requires a `JsonWebSignature2020` proof signed by the master badge issuer. Include a `uuid` for stable identity — re-submitting the same UUID updates the pathway in place.
PUT /pathways/:uuid	Re-publish an existing pathway by UUID. Same validation as POST.
DELETE /pathways/:uuid	Archive a pathway (soft delete). Requires a `JsonWebSignature2020` proof in the request body. The signer's DID must match the master badge's issuer DID. Returns 401 without proof, 403 if DID doesn't match.

How pathways work

Pathways are structured learning paths that define what badges a learner needs to earn a master credential. Submitted as signed JSON from badge album builders (e.g. Emaji).

Structure: master badge (goal) → sections (groups) → slots (individual badge references).

Section completion rules:

rule_type	Meaning
`all`	Every badge in the section is required
`one_of`	At least one badge must be earned
`n_of_m`	At least N of M badges required (set via `ruleCount`)

Ownership & signing: Submissions must be signed (JsonWebSignature2020) by the master badge issuer's DID key. OSP verifies the master badge's proof and the submission's proof, and checks both resolve to the same DID. Signing can be done directly or via the issuing platform (e.g. POST /api/v1/sign on Badgau).

Key queries:

Question	Query
What pathways is badge X part of?	`GET /pathways?achievement_id=<url>`
What do I need for master badge Y?	`GET /pathways/<achievement_id>`
Which pathways include this badge?	`GET /badge-classes/<id>` → see `partOf` field

Credential Engine

Method & Route	Description
GET /ce/status	Last Credential Engine sync state (timestamp, counts, errors).
POST /ce/sync	Trigger a manual CE sync (requires `CE_API_KEY` to be configured).

System

Method & Route	Description
GET /health	Database liveness check. Returns `{ status: "ok" }` or HTTP 503.

Trust levels

Badge classes and nodes carry optional verification fields set by external authorities — OSP records who verified the issuer, not the verification result itself.

Level	Meaning
unverified	No proof attached to the badge class
signed	Badge class carries a `JsonWebSignature2020` proof
domain_verified	Issuer DID domain matches the issuer URL
trusted_source	An external authority (Credential Engine, EBSI, eIDAS, Badgau KYC) has asserted the issuer is legitimate — recorded in `verified_by` / `verification_ref` / `verified_at`

License

Software: MIT License. Free to run, modify, and build on.

Registry data: CC BY 4.0 applies to the structured aggregation. Original issuer content (names, descriptions, graphics) remains the IP of the respective issuing organisation. Each API response carries a license field and a Link: rel="license" header.

For Badge Providers

Expose a public JSON endpoint and register your node with one curl command. OSP crawls it automatically.

Supported formats:

Format	node_type	Identifier field
Badgau (schema.org EducationalOccupationalCredential)	`badgau` (default)	`identifier` — canonical URL
Open Badges 3.0 Achievement	`ob3`	`id` — URI

Register your node

Badgau (default endpoint /api/v1/public/badge-classes):

curl -X POST http://localhost:3000/nodes/register \
  -H "Content-Type: application/json" \
  -d '{"url":"https://your-instance.example.com","name":"My Badgau Instance"}'

Open Badges 3.0 (api_endpoint required):

curl -X POST http://localhost:3000/nodes/register \
  -H "Content-Type: application/json" \
  -d '{"url":"https://your-instance.example.com","name":"My OB3 Platform","node_type":"ob3","api_endpoint":"https://your-instance.example.com/api/achievements"}'

Endpoints must support ?limit=100&offset=0 pagination and return a plain array or { "data": [...] }. For full field documentation and proof signing guidance see the Source API Guide.