API Documentation

All responses are JSON by default. Pathway endpoints also serve HTML pages when accessed from a browser (Accept: text/html). Append ?format=json to force JSON from a browser. Badge class data is served as schema.org EducationalOccupationalCredential.

Badge Classes

Method & Route	Description
GET /badge-classes	List all badge classes. Supports `?q` (full-text), `?category`, `?issuer_did`, `?skill` (URI), `?status` (default `active`, use `all` to include archived), `?limit` (default 50, max 200), `?offset`.
GET /badge-classes/:uuid	Single badge class by UUID. Includes a `partOf` array listing pathways this badge appears in.

Badge class lifecycle: Badge classes have a status field (active or archived). The crawler automatically archives badges that disappear from their source node and reactivates them if they reappear. By default, only active badge classes are returned.

Nodes

Method & Route	Description
GET /nodes	List all registered Badgau nodes with crawl status.
POST /nodes/register	Register a new node. Body: `{ url, name?, api_endpoint? }`. Triggers an immediate crawl.

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

Pathway endpoints support content negotiation: browsers receive an HTML page, API clients receive JSON. Use ?format=json to force JSON output.

Each pathway has a canonical identifier URL: http://localhost:3000/pathways/{uuid}. This URL is resolvable and returned in all pathway API responses as the identifier field.

Method & Route	Description
GET /pathways	List active pathways. Supports `?q` (search title/description), `?achievement_id` (find pathways containing a badge), `?limit` (default 50, max 200), `?offset`. Returns HTML or JSON.
GET /pathways/:id	Single pathway by UUID, numeric ID, or URL-encoded master achievement_id. Returns full sections, slots, and enriched badge class data. Returns HTML or JSON.
GET /pathways/:id/ctdl	Same pathway serialized as a CTDL `ceterms:Pathway` JSON-LD document.
POST /pathways	Submit a signed pathway. Must carry a `JsonWebSignature2020` proof signed by the master badge issuer. Include a `uuid` field for stable identity across re-publishes (upsert). Response includes the canonical `identifier` URL.
PUT /pathways/:uuid	Re-publish (update) an existing pathway by UUID. Same validation as POST. Upserts on UUID conflict.
DELETE /pathways/:uuid	Archive a pathway (ownership-verified soft delete). Requires a signed proof in the request body: `{ "proof": { "type": "JsonWebSignature2020", "verificationMethod": "did:web:...", "jws": "..." } }`. The signer’s DID must match the master badge’s `issuer_did`. Returns 401 without proof, 403 if DID doesn’t match.
DELETE /pathways/:uuid	Archive a pathway by UUID. Sets status to `archived` (soft delete). Returns 404 if not found or already archived.

How pathways work

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

Structure: A pathway has a master badge (the goal), one or more sections (groups of badges), and slots (individual badge references) within each section.

Identifiers: Each pathway receives a canonical URL identifier (http://localhost:3000/pathways/{uuid}) that is resolvable in both browsers and API clients. Publishers should store this identifier for re-publishing and linking. The uuid is stable across re-publishes — sending the same uuid in a POST updates the existing pathway rather than creating a duplicate.

Section completion rules:

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

Validation & ownership: The pathway submission must be signed (JsonWebSignature2020 proof) by the issuer of the master badge. OpenSkillPaths verifies both (1) the master badge’s proof in the registry and (2) the submission’s proof, then checks that both resolve to the same DID. This ensures only the credential issuer can publish or delete authoritative pathways for their badges. The signing can be done directly (if the pathway builder holds the issuer’s key) or via a signing proxy on the issuing platform (e.g. POST /api/sign on Badgau).

Deletion: Pathways are soft-deleted (archived) via DELETE /pathways/:uuid. The request must include a signed proof from the master badge’s issuer DID. This ownership verification prevents unauthorized removal.

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/<uuid>` → see `partOf` field
View a pathway in the browser	Open `http://localhost:3000/pathways/<uuid>` in a browser

Submit a pathway via POST /pathways with the badge album JSON export. See the README for the full JSON schema.

System

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

Response format

Badge classes: List endpoints return { license, total, limit, offset, data[] }. Each item in data is a schema.org EducationalOccupationalCredential object with license, usageInfo, and _meta fields.

Pathways: List endpoints return { total, limit, offset, data[] }. Each pathway includes an identifier field with the canonical resolvable URL. Single pathway responses include full sections with slots and enriched badge_class data.

Content negotiation: Pathway endpoints (/pathways, /pathways/:id) serve HTML to browsers and JSON to API clients based on the Accept header. Append ?format=json to always get JSON.

License

Software: The OpenSkillPaths server software is released under the MIT License. You are free to run your own instance, modify it, and build on top of it.

Registry data: The aggregated badge class compilation served by this API is licensed under CC BY 4.0. All API responses carry a Link: <...>; rel="license" HTTP header and a license field in the JSON body.

Scope of CC BY 4.0: This covers the structured aggregation and compilation — the registry dataset as a whole. It does not cover the original content contributed by issuers (credential names, descriptions, competency definitions, badge graphics). That content remains the intellectual property of the respective issuing organisation and is reproduced here solely on the basis of their public disclosure consent. Each item carries a usageInfo field identifying the issuer.

For Badge Providers

Want your badge classes listed here? Expose a public JSON endpoint that returns your badge classes and register it with one curl command. OpenSkillPaths then crawls your endpoint automatically on a configurable interval.

Supported source formats:

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

Register your node

Badgau nodes with the default endpoint path (/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 nodes (api_endpoint is 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"}'

Your endpoint must support ?limit=100&offset=0 pagination. Responses may be a plain array or { "data": [...] }.

For full field documentation, alignment indexing details, and proof signing guidance see the Source API Guide in the repository.