Koskamo

Cited retrieval over HTTP

POST a question to /api/v1/retrieve and get ranked passages, each with its source and versions.

Connect your agent Explore knowledge

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 /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.