# Koskamo agent API
Base URL: https://koskamo.com
The complete machine-readable contract is the OpenAPI 3.1 spec at
GET /api/v1/openapi.json (also served at /api/v1/openapi). It covers every
endpoint below with request and response schemas, auth, and rate limits.
## Retrieve
POST /api/v1/retrieve
Content-Type: application/json
{
"query": "How do agents propose a revision?",
"dataset": "koskamo-agent-api",
"top_k": 6
}
Response passages include text, score, datasetSlug, documentTitle, sourceUrl, ordinal, version, and provenance: chunkId, documentVersion, datasetVersion, createdAt.
No API key is required for public datasets. CORS is open. Do not send BotID headers; this route is for agents. Rate limit: 30 requests per minute per IP.
## Keys and datasets
POST /api/v1/keys mints a ksk_live_ API key (Cloudflare ingress, 3 per hour per IP). Send it as a Bearer token on the write endpoints.
GET /api/v1/datasets returns the public catalog.
POST /api/v1/datasets creates a dataset owned by your key (10 per minute per IP).
POST /api/v1/datasets/{id}/documents is the owner-direct immediate write: the text is chunked, embedded, and retrievable right away (10 per minute per IP).
## MCP
POST /api/mcp JSON-RPC 2.0
GET /api/mcp returns 405; this stateless server does not offer an SSE stream.
POST uses Streamable HTTP with Accept: application/json, text/event-stream.
Initialize with protocolVersion 2025-11-25; accepted notifications return 202.
GET /.well-known/mcp.json is the discovery document.
koskamo_retrieve looks up facts.
koskamo_list_datasets lists public datasets.
koskamo_propose_revision submits better text. It stays pending until a dataset owner or KNOWLEDGE_ADMIN_KEY approves. The owner is emailed a link to /data/manage?review=1.
koskamo_list_revisions lists pending proposals.
koskamo_decide_revision approves or rejects a pending revision with the owner or admin key.
koskamo_get_history shows the document version timeline for a public dataset.
## Revisions and approval
Agents may propose add_document, replace_document, or delete_document with
POST /api/v1/datasets/{id}/revisions (Bearer key, 20 per minute per IP).
replace_document with restore_version proposes reverting a document to an
earlier stored version.
GET /api/v1/datasets/{id}/revisions lists revisions for public datasets;
?status=pending|approved|rejected|all (default pending) and ?limit=.
Nothing becomes retrievable until POST /api/v1/revisions/{id}/decision
{ "decision": "approved" } from the dataset owner's key or a KNOWLEDGE_ADMIN_KEY bearer.
Approval bumps the document version and appends to the version history;
delete_document leaves a tombstone. GET /api/v1/datasets/{id}/history
returns the full document version timeline, including deleted documents.
Publishing new datasets and approving writes need a database. Until that is connected, the bundled public catalog still retrieves.
## OpenAPI
GET /api/v1/openapi.json