Skip to main content
The Knoq REST API gives you programmatic access to Knoq’s AI knowledge platform. You can create and manage agent sessions, send messages to the AI, retrieve full conversation transcripts, and cancel in-flight sessions — all over standard HTTPS. Every API call is scoped to your authenticated user and your active organisation, so your data stays isolated within your team.

​
Base URL

All API requests are made to the following base URL: 
https://knoq.one
Every endpoint path in this reference is relative to that base. For example, the sessions list endpoint is accessed at: 
https://knoq.one/api/managed-agents/sessions

​
Content type

All request bodies must be sent as JSON. Set the Content-Type header on every POST and DELETE request: 
Content-Type: application/json
All successful responses are returned as JSON objects. Error responses follow the same structure — a JSON body with an error field describing what went wrong.

​
Authentication

The Knoq API authenticates requests using session cookies issued when you sign in to Knoq. There is no standalone API key system — every request must carry a valid session cookie alongside the correct Origin header to pass CSRF checks on mutating routes. For full details on obtaining a session, constructing authenticated requests, and handling 401/403 responses, see the Authentication guide.

​
Rate limits

Knoq enforces per-user rate limits to protect platform stability. Requests that exceed a limit receive a 429 Too Many Requests response. The Retry-After header on that response tells you how many seconds to wait before retrying.
LimitThreshold
Messages sent60 per minute, per user
Sessions created10 per minute, per user
These limits are applied per authenticated user, not per IP address or API client. If you are building a tool that drives heavy automated traffic, batch your requests and respect the Retry-After value on 429 responses.

​
Error codes

The API uses standard HTTP status codes. When a request fails, the response body contains an error field with a human-readable description. 
{
  "error": "text is required"
}
Status codeMeaning
400Bad request — A required parameter is missing, empty, or invalid. Check the error field for details on which field failed validation.
401Not authenticated — Your session cookie is missing or has expired. Re-authenticate and retry.
403Forbidden — Your plan does not include the feature you are trying to use, or the request failed a CSRF origin check.
404Not found — The session or resource you referenced does not exist, or it belongs to a different user or organisation.
429Rate limit exceeded — You have sent too many requests in the current window, or your organisation has reached its monthly query limit. Check the Retry-After header and wait before retrying.
502Upstream error — The AI provider returned an error or was unreachable. Retry with backoff.
503Service unavailable — Knoq is temporarily unable to handle the request. Retry with backoff.
A 403 can mean either a plan-limit rejection or a CSRF check failure. If you are calling mutating endpoints (POST, DELETE) from outside a browser, make sure you are sending Origin: https://knoq.one with every request.

​
Available endpoints

Sessions

Create, list, and delete AI agent sessions. A session represents a persistent conversation thread.

Messaging

Send follow-up messages to an active session and retrieve the full transcript of a conversation.

SCIM

Provision and deprovision users and groups in Knoq from your identity provider using the SCIM 2.0 protocol.