> For the complete documentation index, see [llms.txt](https://docs.khotan.com/llms.txt). A markdown version of any page is available at its `index.md` URL. # Context `/api/v1` operations for context. See [HTTP API](/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`