Support / API reference

REST API

Programmatic, read-only access to your workspace's knowledge — list roles and knowledge items, and ask grounded questions. Part of the Pro plan. This is v1 (read + ask); writing data through the API is planned for v2.

Base URL

The API lives on your workspace host. Replace your-org with your slug:

https://your-org.knowledgeretention.help/api/v1

Authentication

Create a key at API keys in your workspace (Pro admins). The secret is shown once. Send it as a Bearer token:

curl https://your-org.knowledgeretention.help/api/v1/roles \
  -H "Authorization: Bearer kr_live_xxxxxxxx"

A key carries scopes: read (list endpoints) and/or ask (/answer).

Endpoints

GET/v1/rolesscope: read

List captured roles.

{ "data": { "roles": [ { "id": "…", "name": "Treasurer", "status": "covered", … } ] } }

GET/v1/knowledgescope: read

List knowledge items with provenance. Query params: roleId, limit (default 100, max 500), cursor. Cursor-paginated — follow nextCursor until it is null.

curl "https://your-org.knowledgeretention.help/api/v1/knowledge?limit=100" \
  -H "Authorization: Bearer kr_live_xxxxxxxx"

{ "data": { "items": [ … ] }, "nextCursor": "eyJ0Ijoi…" }

GET/v1/membersscope: read

List the workspace roster.

{ "data": { "members": [ { "email": "a@org.org", "role": "admin", "joined_at": "…" } ] } }

POST/v1/answerscope: ask

Ask a plain-language question; get a grounded answer with citations (and an honest “I don't know” when the knowledge base can't support one).

curl -X POST https://your-org.knowledgeretention.help/api/v1/answer \
  -H "Authorization: Bearer kr_live_xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"question":"When is the annual grant report due?"}'

{ "data": { "answer": "…", "confident": true, "citations": [ … ] } }

Rate limits

Per key: 120 requests/min for read endpoints, 20/min for /answer. Every response includes RateLimit-Limit, RateLimit-Remaining, and RateLimit-Reset (seconds). Over the limit returns 429.

Errors

Failures return { "errors": [ { "code", "message" } ] }. Branch on the stable code:

HTTP	code	Meaning
400	invalid_input	Bad request / malformed cursor
401	unauthorized	Missing, invalid, or revoked key
402	plan_required	Workspace is not on Pro
402	subscription_lapsed	Subscription canceled
403	insufficient_scope	Key lacks the required scope
429	rate_limited	Rate limit exceeded
503	ai_unavailable	AI temporarily unavailable (/answer)

API agreement

By using the KnowledgeRetention API you agree that it is provided in the hope that it will be useful, but WITHOUT ANY WARRANTY — without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. We reserve the right to restrict or deny access at any time.

Machine-readable spec: openapi.yaml.