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
Responses include assessment (candidates or no_matches) and guidance. Candidate passages are not verified answers. Check support and preserve the source and document version; if none supports the question, say no supporting evidence was found. 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 /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. koskamo_find_mcp_server searches the public MCP directory of vendor-run servers that passed a recent live check. koskamo_register_mcp_server lists a server you operate: the first call returns a claim token, and a second call with the token publishes it once a well-known file or DNS TXT proof is found and the live check passes.
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