Context

/api/v1 operations for context. See HTTP API for authentication, the error envelope, and rate limits.

Operations

GET /api/v1/context

List context documents

Returns the organization's active document manifest: slug, title, description, kind, tags, revision, contentSize, and updatedAt — never content. Filter by kind, or pass q to search via the weighted full-text index (title ranks above description above content). Fetch individual documents by slug for their markdown.

Auth: API key required.

Operation ID: listContextDocuments

Query parameters:

• kind ("instructions" | "knowledge" | "record", optional)
• q (string, optional)

Responses:

• 200 — The document manifest.
• 400 — The request was malformed or failed validation.
• 401 — Authentication is missing or invalid.
• 429 — Too many requests; retry after the indicated delay.

CLI: khotan context list

POST /api/v1/context

Create a context document

Creates a markdown document from title, kind, and content, with optional slug, description, and tags. The slug is derived from the title when omitted and is immutable after creation; a collision with an active document responds 409. Limit violations respond 422 with the limit name, maximum, and submitted value.

Auth: API key required.

Operation ID: createContextDocument

Request body (application/json, required):

• title (string, required)
• kind ("instructions" | "knowledge" | "record", required) — "instructions" = procedures to follow (SOPs, runbooks); "knowledge" = reference material (specs, policies); "record" = accounts of events (meeting notes, transcripts, interviews).
• content (string, required) — Canonical raw markdown (max 256 KB, enforced by the domain layer).
• slug (string, optional) — Derived from the title when omitted; conflicts return 409.
• description (string, optional) — One-line purpose statement powering the manifest listing (max 200 characters, enforced by the domain layer).
• tags (string[], optional) — Flat tag list; express hierarchy with naming conventions like "ops/runbook/deploy".
• properties (object, optional) — Structured facts beside the markdown: any JSON object.
• folderId (string | null, optional) — Folder placement; omit or null for the organization root.

Responses:

• 201 — The created document, including its content.
• 400 — The request was malformed or failed validation.
• 401 — Authentication is missing or invalid.
• 409 — Response.
• 422 — Response.
• 429 — Too many requests; retry after the indicated delay.

CLI: khotan context create

GET /api/v1/context/search

Search context documents

Hybrid semantic + full-text search over the organization's active context documents, reranked for relevance. Returns the best passage from each matching document, with its slug, title, kind, and a relevance score. Use the slug to fetch the full markdown when a passage is insufficient.

Auth: API key required.

Operation ID: searchContextDocuments

Query parameters:

• q (string, required)
• k (integer, optional)
• kind ("instructions" | "knowledge" | "record", optional)

Responses:

• 200 — Ranked snippets, most relevant first.
• 400 — The request was malformed or failed validation.
• 401 — Authentication is missing or invalid.
• 429 — Too many requests; retry after the indicated delay.

CLI: khotan context search

GET /api/v1/context/folders

List context folders

Returns the organization's folder tree as a flat list of folders with parentId, name, slug, path, depth, and the active-document count directly within each folder.

Auth: API key required.

Operation ID: listContextFolders

Responses:

• 200 — The organization's folders.
• 401 — Authentication is missing or invalid.
• 429 — Too many requests; retry after the indicated delay.

CLI: khotan context folders list

POST /api/v1/context/folders

Create a context folder

Creates a folder under an optional parent (omit or null for the organization root). The name must be unique among active sibling folders; a collision responds 409 folder_conflict. An unknown parent responds 404 folder_not_found.

Auth: API key required.

Operation ID: createContextFolder

Request body (application/json, required):

• name (string, required)
• parentId (string | null, optional) — Parent folder; omit or null for the organization root.

Responses:

• 201 — The created folder.
• 400 — The request was malformed or failed validation.
• 401 — Authentication is missing or invalid.
• 404 — The resource was not found.
• 409 — Response.
• 422 — Response.
• 429 — Too many requests; retry after the indicated delay.

CLI: khotan context folders create

PATCH /api/v1/context/folders/{id}

Rename or move a context folder

Renames the folder when name is provided and moves it when parentId is provided (null moves it to the organization root). Sibling name collisions respond 409 folder_conflict; moving a folder into itself or a descendant responds 422 folder_cycle.

Auth: API key required.

Operation ID: updateContextFolder

Path parameters:

• id (string, required)

Request body (application/json, required):

• name (string, optional)
• parentId (string | null, optional) — Pass null to move to the organization root.

Responses:

• 200 — The updated folder.
• 400 — The request was malformed or failed validation.
• 401 — Authentication is missing or invalid.
• 404 — The resource was not found.
• 409 — Response.
• 422 — Response.
• 429 — Too many requests; retry after the indicated delay.

CLI: khotan context folders update

DELETE /api/v1/context/folders/{id}

Delete a context folder

Soft-deletes the folder. A non-empty folder responds 409 folder_not_empty unless recursive=true is passed, in which case its subfolders and documents are soft-deleted too (their revision history is retained).

Auth: API key required.

Operation ID: deleteContextFolder

Path parameters:

• id (string, required)

Query parameters:

• recursive ("true" | "false", optional)

Responses:

• 200 — The folder was deleted.
• 401 — Authentication is missing or invalid.
• 404 — The resource was not found.
• 409 — Response.
• 429 — Too many requests; retry after the indicated delay.

CLI: khotan context folders delete

GET /api/v1/context/{slug}

Get a context document

Returns the full document, including its raw markdown content, in a JSON envelope. Unknown or deleted slugs respond 404. Fetching a document records its access time.

Auth: API key required.

Operation ID: getContextDocument

Path parameters:

• slug (string, required)

Responses:

• 200 — The document record, including content.
• 401 — Authentication is missing or invalid.
• 404 — The resource was not found.
• 429 — Too many requests; retry after the indicated delay.

CLI: khotan context get

PATCH /api/v1/context/{slug}

Update a context document

Updates the document's title, kind, content, description, tags, properties, and/or folder when expectedRevision matches the current revision. Properties replace the whole object; omit them to keep the current ones. Links are set separately. On mismatch, responds 409 revision_conflict with the current revision and updatedAt. The slug is immutable; title changes never re-slug. Limit violations respond 422 with the limit name, maximum, and submitted value.

Auth: API key required.

Operation ID: updateContextDocument

Path parameters:

• slug (string, required)

Request body (application/json, required):

• expectedRevision (integer, required) — Required compare-and-swap token; a stale value returns 409 with the current revision and updatedAt.
• title (string, optional)
• kind ("instructions" | "knowledge" | "record", optional) — "instructions" = procedures to follow (SOPs, runbooks); "knowledge" = reference material (specs, policies); "record" = accounts of events (meeting notes, transcripts, interviews).
• content (string, optional) — Canonical raw markdown (max 256 KB, enforced by the domain layer).
• description (string | null, optional) — Pass null to clear the description.
• tags (string[], optional) — Flat tag list; express hierarchy with naming conventions like "ops/runbook/deploy".
• properties (object, optional) — Structured facts beside the markdown: any JSON object.
• folderId (string | null, optional) — Move the document; null moves it to the organization root.
• changeSummary (string | null, optional) — Optional note recorded on the revision history entry.

Responses:

• 200 — The updated document record.
• 400 — The request was malformed or failed validation.
• 401 — Authentication is missing or invalid.
• 404 — The resource was not found.
• 409 — Response.
• 422 — Response.
• 429 — Too many requests; retry after the indicated delay.

CLI: khotan context update

DELETE /api/v1/context/{slug}

Delete a context document

Soft-deletes the document. It disappears from the manifest and fetches and its slug becomes reusable; the row and its revision history are retained.

Auth: API key required.

Operation ID: deleteContextDocument

Path parameters:

• slug (string, required)

Responses:

• 200 — The document was deleted.
• 401 — Authentication is missing or invalid.
• 404 — The resource was not found.
• 429 — Too many requests; retry after the indicated delay.

CLI: khotan context delete

GET /api/v1/context/{slug}/raw

Get a context document's raw markdown

Returns exactly the document's markdown text with a text/markdown content type and no JSON envelope. Unknown or deleted slugs respond 404 (as JSON). Fetching a document records its access time.

Auth: API key required.

Operation ID: getContextDocumentRaw

Path parameters:

• slug (string, required)

Responses:

• 200 — The raw markdown body.
• 401 — Authentication is missing or invalid.
• 404 — The resource was not found.
• 429 — Too many requests; retry after the indicated delay.

CLI: khotan context raw

GET /api/v1/context/{slug}/links

List a context document's links

Returns the projects and resources the document links to, each with its current name. A target that was deleted shows removed: true. Unknown or deleted slugs respond 404.

Auth: API key required.

Operation ID: listContextDocumentLinks

Path parameters:

• slug (string, required)

Responses:

• 200 — The document's links.
• 401 — Authentication is missing or invalid.
• 404 — The resource was not found.
• 429 — Too many requests; retry after the indicated delay.

CLI: khotan context links list

PUT /api/v1/context/{slug}/links

Set a context document's links

Replaces the document's complete link set with the given projects and resources. Links not listed are removed. Every new target must be live in the organization, or nothing changes. A link whose target was deleted since is kept unless you leave it out. A document can have at most 200 links. Unknown or deleted slugs respond 404.

Auth: API key required.

Operation ID: setContextDocumentLinks

Path parameters:

• slug (string, required)

Request body (application/json, required):

• links (object[], required) — The document's complete link set. Links not listed are removed.

Responses:

• 200 — The document's links after the change.
• 400 — The request was malformed or failed validation.
• 401 — Authentication is missing or invalid.
• 404 — The resource was not found.
• 429 — Too many requests; retry after the indicated delay.

CLI: khotan context links set

GET /api/v1/context/{slug}/revisions

List a context document's revisions

Returns the document's revision history, newest first: revision number, title, author, optional change summary, and timestamp — never the snapshot content. Unknown or deleted slugs respond 404.

Auth: API key required.

Operation ID: listContextDocumentRevisions

Path parameters:

• slug (string, required)

Responses:

• 200 — The revision history, newest first.
• 401 — Authentication is missing or invalid.
• 404 — The resource was not found.
• 429 — Too many requests; retry after the indicated delay.

CLI: khotan context revisions list

GET /api/v1/context/{slug}/revisions/{revision}

Get a context document revision

Returns a single revision including its captured title and markdown content. Unknown or deleted slugs, and uncaptured revisions, respond 404.

Auth: API key required.

Operation ID: getContextDocumentRevision

Path parameters:

• slug (string, required)
• revision (integer, required)

Responses:

• 200 — The revision record, including its snapshot content.
• 401 — Authentication is missing or invalid.
• 404 — The resource was not found.
• 429 — Too many requests; retry after the indicated delay.

CLI: khotan context revisions get

POST /api/v1/context/{slug}/revisions/{revision}/restore

Restore a context document revision

Restores the document to the given revision by creating a new forward revision whose title and content match that snapshot. Prior revisions are retained. Unknown slugs or uncaptured revisions respond 404; a concurrent write responds 409 revision_conflict.

Auth: API key required.

Operation ID: restoreContextDocumentRevision

Path parameters:

• slug (string, required)
• revision (integer, required)

Responses:

• 200 — The document at its new, restored revision.
• 401 — Authentication is missing or invalid.
• 404 — The resource was not found.
• 409 — Response.
• 429 — Too many requests; retry after the indicated delay.

CLI: khotan context revisions restore