Authentication
A short-lived bearer token in the Authorization header. Every request is re-evaluated: identity, tenant, scope, permission, visibility, and version state.
A verified token carries: id, identity type, exactly one tenant, and scopes — a missing claim is a full refusal.
GET /v1/me — The caller's identity, roles, and permissions in the current tenant.
Scopes
A scope is a ceiling in the token. A service client gets the intersection of its token scopes and the scopes granted to its account.
| Scope | Meaning |
|---|---|
| curriculum:read | Reading curricula, frameworks, grade levels. |
| outcome:read | Reading outcomes, skills, standards. |
| association:read | Reading graph relations. |
| alignment:read | Reading alignments and mapping sets. |
| evidence:read | Reading evidence statements and guidance. |
| webhook:manage | Managing your own client's webhook subscription. |
Note
A service client may hold five read scopes and webhook:manage — its own webhook subscriptions, granted explicitly, never by default. Any other scope is refused by a database constraint.
Endpoints
Every path below is actually served. The v1 in the path is the contract version, not the knowledge version.
| Method | Path | Scope | Meaning |
|---|---|---|---|
| GET | /v1/academic-levels | curriculum:read | Reference data: every country in the world, curricula, subjects, education systems and their grades, and academic levels — for sync. |
| GET | /v1/alignments | alignment:read | Cross-curriculum mapping sets and their approved alignments. |
| GET | /v1/associations | association:read | The version's internal graph relations. |
| GET | /v1/countries | curriculum:read | Reference data: every country in the world, curricula, subjects, education systems and their grades, and academic levels — for sync. |
| GET | /v1/curricula | curriculum:read | Listing curricula and details with each one's latest published version. |
| GET | /v1/curricula/{id} | curriculum:read | Listing curricula and details with each one's latest published version. |
| GET | /v1/curriculum-types | curriculum:read | Reference data: every country in the world, curricula, subjects, education systems and their grades, and academic levels — for sync. |
| GET | /v1/education-systems | curriculum:read | Reference data: every country in the world, curricula, subjects, education systems and their grades, and academic levels — for sync. |
| GET | /v1/education-systems/{id}/grade-levels | curriculum:read | Reference data: every country in the world, curricula, subjects, education systems and their grades, and academic levels — for sync. |
| GET | /v1/evidence | evidence:read | An outcome's evidence bundle: statements, indicators, guidance. |
| GET | /v1/framework-domains | curriculum:read | Taxonomy: macro areas, domains, strands, standards. |
| GET | /v1/framework-macros | curriculum:read | Taxonomy: macro areas, domains, strands, standards. |
| GET | /v1/framework-outcomes | outcome:read | Framework outcomes and details at a release. |
| GET | /v1/framework-outcomes/{id} | outcome:read | Framework outcomes and details at a release. |
| GET | /v1/framework-standards | curriculum:read | Taxonomy: macro areas, domains, strands, standards. |
| GET | /v1/framework-standards/{id} | curriculum:read | Taxonomy: macro areas, domains, strands, standards. |
| GET | /v1/framework-strands | curriculum:read | Taxonomy: macro areas, domains, strands, standards. |
| GET | /v1/framework-versions | curriculum:read | Framework releases (MAJOR.MINOR.PATCH). |
| GET | /v1/frameworks | curriculum:read | Frameworks, read by id or stable code. |
| GET | /v1/frameworks/applicable | curriculum:read | The frameworks valid per subject and grade for an education system or a country, by the binding rule: custom for the system, then for the country, then general. |
| GET | /v1/frameworks/{id} | curriculum:read | Frameworks, read by id or stable code. |
| GET | /v1/grade-levels | curriculum:read | The curriculum's reference grade levels (unversioned). |
| GET | /v1/mapping-sets | alignment:read | Cross-curriculum mapping sets and their approved alignments. |
| GET | /v1/mapping-sets/{id} | alignment:read | Cross-curriculum mapping sets and their approved alignments. |
| GET | /v1/outcomes | outcome:read | Listing outcomes and details, with version pinning and path expansion. |
| GET | /v1/outcomes/{id} | outcome:read | Listing outcomes and details, with version pinning and path expansion. |
| GET | /v1/sources | source:read:metadata | Source metadata only — no reference-only content. |
| GET | /v1/sources/{id} | source:read:metadata | Source metadata only — no reference-only content. |
| GET | /v1/subject-areas | curriculum:read | Reference data: every country in the world, curricula, subjects, education systems and their grades, and academic levels — for sync. |
| GET | /v1/versions | curriculum:read | One curriculum's versions and their states. |
| GET | /v1/webhooks | webhook:manage | This client's own subscriptions — never another client's, never a secret. |
| POST | /v1/webhooks | webhook:manage | Subscribe an https URL to events; the signing secret is in this answer only. |
| DELETE | /v1/webhooks/{id} | webhook:manage | Delete a subscription; nothing more is sent to it. |
| GET | /v1/webhooks/{id} | webhook:manage | This client's own subscriptions — never another client's, never a secret. |
| POST | /v1/webhooks/{id}/rotate-secret | webhook:manage | A new signing secret, in this answer only; the old one stops at once. |
Reserved in contract, unserved
These paths are named in the contract but have no route in this build. Do not call them — they will fail.
- /v1/subjects
- /v1/skills
- /v1/standards
- /v1/search
- /v1/exports
- /v1/diffs
- /v1/overlays
- /v1/translations
- /v1/audit-events
- /v1/tenants
Version pinning
Pass version on every knowledge read, or leave resolution to latest_published — the response always returns the full resolved number.