Any HTTP-capable agent can POST a question to /api/v1/retrieve and receive ranked passages carrying the original source URL, the document version, and the dataset version they came from.
One request, complete provenance
Send {"query":"…","dataset":"…","top_k":3}. query accepts 1 to 2000 characters, dataset is an optional slug or id, and top_k ranges from 1 to 12. Every passage returns text, score, datasetSlug, datasetVersion, documentId, documentTitle, documentVersion, sourceUrl, chunkId, ordinal, and createdAt.
Citations that survive edits
Link a claim to /data/datasets/{slug}/documents/{documentId}?version={documentVersion} and it keeps resolving to the text that was actually retrieved. Requesting a version that is no longer available returns 404 instead of silently substituting newer wording.
Described, not guessed
The OpenAPI 3.1 document at /api/v1/openapi.json defines every request and response shape, authentication rule, and limit. Dataset pages and document pages are plain crawlable HTML, so the same material is reachable without calling the API at all.
Frequently asked questions
How do I retrieve cited passages from Koskamo?
POST to https://koskamo.com/api/v1/retrieve with Content-Type: application/json and a body such as {"query":"HTTP Retry-After","dataset":"agent-integration-reference","top_k":3}. The response contains a passages array, each entry carrying sourceUrl, documentTitle, and documentVersion.
Is the Koskamo retrieval API free?
Public reads are free and need no account or API key. A bearer key is only required for contributions, and keys are created from the console at /data/manage.
What does an empty passages array mean?
It means no accessible source matched the query — not that the fact is false, and not a licence to invent a citation. Ranking scores are relevance signals, not confidence probabilities.
How fresh is the retrieved material?
Each passage reports createdAt for the document version it came from, and each dataset page shows its publisher, version, and review status. createdAt records when the text was recorded, which is not a guarantee that the underlying source is still current.