GET /v1/bundle
Latest published bundle for the token's org
Returns bundle metadata plus a short-lived presigned download URL for the org's most recently published OKF bundle (tar.gz).
Bearer token scope: read
Developer docs
Public API reference
Base URL: /api/curated-data. Reads return approved content; writes create reviewable drafts. Data operations enforce the token’s scopes and classification access.
Import path templates now use {jobId} instead of {id}. Wire URLs are unchanged; generated SDK parameter names change. The two contract routes are unauthenticated.
OKF conformance
Export bundles target OKF v0.2. The Export page reports missing frontmatter, reserved paths, loose timestamps, unknown lifecycle values and broken links. Unknown author fields and loose dates remain readable; supplied verification stamps are removed on writes and approval adds server-owned stamps.
Frontmatter now documents every supported OKF field. The legacy timestamp accepts loose dates and has no date-time format constraint. Runtime validation also enforces refinements and a frontmatter size budget that JSON Schema cannot express.
OKF specificationBundle
Changes
GET /v1/changes
Read approved-view changes and readable tombstones
Latest state per document, filtered by classification and ACL. ACL changes are excluded; old paths after moves are inferable only by id. Unreadable documents stop appearing. Imports appear only on approval. ISO since is best-effort; opaque cursors resume exactly. An empty-id cursor resumes strictly after its generation.
Bearer token scope: read
Parameters (2)
since· query · optional- {"maxLength":256,"minLength":1,"type":"string"}
limit· query · optional- {"default":100,"maximum":500,"minimum":1,"type":"integer"}
Concepts
GET /v1/concepts
List approved concepts
Bearer token scope: read
Parameters (10)
type· query · optional- {"maxLength":64,"minLength":1,"type":"string"}
tag· query · optional- {"maxLength":64,"minLength":1,"type":"string"}
prefix· query · optional- {"maxLength":512,"minLength":1,"type":"string"}
status· query · optional- {"anyOf":[{"items":{"enum":["draft","stable","deprecated"],"type":"string"},"minItems":1,"type":"array"},{"type":"string"}]}
trustTier· query · optional- {"enum":["unverified","machine-confirmed","human-reviewed"],"type":"string"}
excludeStale· query · optional- {"anyOf":[{"type":"boolean"},{"enum":["true","false"],"type":"string"}]}
includeDeprecated· query · optional- {"anyOf":[{"type":"boolean"},{"enum":["true","false"],"type":"string"}]}
generatedBy· query · optional- {"maxLength":128,"minLength":1,"type":"string"}
cursor· query · optional- {"maxLength":64,"minLength":1,"type":"string"}
limit· query · optional- {"maximum":100,"minimum":1,"type":"integer"}
POST /v1/concepts
Create a concept as a draft revision
Bearer token scope: write
POST /v1/concepts/recommend
Agentically organize source material into draft concept changes
The knowledge agent navigates the existing OKF index tree, searches for duplicates, reads concepts before updating them, and writes only human-reviewable drafts.
Bearer token scope: write
GET /v1/concepts/{path}
Fetch one approved concept by path
Bearer token scope: read
Parameters (4)
maxBytes· query · optional- {"maximum":1048576,"minimum":1024,"type":"integer"}
section· query · optional- {"maxLength":200,"minLength":1,"type":"string"}
If-None-Match· header · optional- {"type":"string"}
path· path · required- The concept path, e.g. `guides/getting-started.md` (may itself contain `/` segments).
PUT /v1/concepts/{path}
Create or update a concept's open draft revision at this path
Bearer token scope: write
Parameters (1)
path· path · required- {"type":"string"}
Imports
GET /v1/imports
List recent asynchronous ingestion jobs
Bearer token scope: write
POST /v1/imports
Queue a URL or raw-text source for asynchronous ingestion
Creates an import job that enters review by default. The session-plane `bypassReview` switch is not accepted on this surface; `autoApprove: true` (requires the `auto_approve` token scope, 403 otherwise) publishes curated results on landing, attributed to the token.
Bearer token scope: write
POST /v1/imports/files
Create a presigned document upload
Bearer token scope: write
GET /v1/imports/{jobId}
Get an ingestion job
Bearer token scope: write
Parameters (1)
jobId· path · required- {"type":"string"}
POST /v1/imports/{jobId}/start
Verify an uploaded document and queue ingestion
Bearer token scope: write
Parameters (1)
jobId· path · required- {"type":"string"}
Contracts
GET /v1/okf/frontmatter.schema.json
OKF frontmatter JSON Schema
No authentication required
GET /v1/openapi.json
Public API OpenAPI contract
No authentication required
Search
GET /v1/related/{path}
Readable related concepts; restricted hops are never traversed
Bearer token scope: read
Parameters (5)
path· path · required- {"type":"string"}
depth· query · optional- {"default":1,"maximum":2,"minimum":1,"type":"integer"}
direction· query · optional- {"default":"both","enum":["out","in","both"],"type":"string"}
limit· query · optional- {"default":20,"maximum":50,"minimum":1,"type":"integer"}
semantic· query · optional- {"default":false,"type":"boolean"}
GET /v1/search
Full-text search over an org's approved concepts
Bearer token scope: read
Parameters (15)
type· query · optional- {"maxLength":64,"minLength":1,"type":"string"}
tag· query · optional- {"maxLength":64,"minLength":1,"type":"string"}
prefix· query · optional- {"maxLength":512,"minLength":1,"type":"string"}
status· query · optional- {"anyOf":[{"items":{"enum":["draft","stable","deprecated"],"type":"string"},"minItems":1,"type":"array"},{"type":"string"}]}
trustTier· query · optional- {"enum":["unverified","machine-confirmed","human-reviewed"],"type":"string"}
excludeStale· query · optional- {"anyOf":[{"type":"boolean"},{"enum":["true","false"],"type":"string"}]}
includeDeprecated· query · optional- {"anyOf":[{"type":"boolean"},{"enum":["true","false"],"type":"string"}]}
generatedBy· query · optional- {"maxLength":128,"minLength":1,"type":"string"}
q· query · required- {"maxLength":200,"minLength":1,"type":"string"}
limit· query · optional- {"maximum":50,"minimum":1,"type":"integer"}
cursor· query · optional- {"maxLength":256,"minLength":1,"type":"string"}
includeBody· query · optional- {"anyOf":[{"type":"boolean"},{"enum":["true","false"],"type":"string"}]}
contextBudget· query · optional- {"maximum":1048576,"minimum":1024,"type":"integer"}
intent· query · optional- Snippet selection only; never changes ranking.
searches· query · optional- JSON array of 1–10 {type: lex|vec|hyde, query} entries, query max 500 chars. First weighted 2×.
Reviews
GET /v1/reviews
List revisions awaiting review (or the rejection backlog)
Requires the `approve` token scope. Results are filtered to the token's allowedClassifications and path restrictions — this surface exposes unapproved content, so entitlement is enforced fail-closed.
Bearer token scope: approve
Parameters (4)
status· query · optional- {"enum":["in_review","rejected"],"type":"string"}
type· query · optional- {"maxLength":64,"minLength":1,"type":"string"}
cursor· query · optional- {"maxLength":64,"minLength":1,"type":"string"}
limit· query · optional- {"maximum":100,"minimum":1,"type":"integer"}
GET /v1/reviews/{revisionId}
Get a revision under review plus the approved baseline to diff against
Bearer token scope: approve
Parameters (1)
revisionId· path · required- {"type":"string"}
POST /v1/reviews/{revisionId}/approve
Approve an in-review revision, publishing it as the live document
Requires the `approve` token scope. The approval is attributed to the token (machine provenance, OKF `verified[]` entry). A user-scoped token additionally requires its owner to still hold the review permission; a token approving its own submission follows the org's self-approval rule.
Bearer token scope: approve
Parameters (1)
revisionId· path · required- {"type":"string"}
POST /v1/reviews/{revisionId}/reject
Reject an in-review revision with a required note
Requires the `approve` token scope. The author's draft reopens with the note attached.
Bearer token scope: approve
Parameters (1)
revisionId· path · required- {"type":"string"}
