> ## Documentation Index
> Fetch the complete documentation index at: https://docs.knoq.one/llms.txt
> Use this file to discover all available pages before exploring further.

# Knoq REST API reference

> Explore the Knoq REST API to programmatically create sessions, send messages, and retrieve AI-generated transcripts.

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](/api-reference/authentication).

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

| Limit            | Threshold               |
| ---------------- | ----------------------- |
| Messages sent    | 60 per minute, per user |
| Sessions created | 10 per minute, per user |

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

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

```json theme={null}
{
  "error": "text is required"
}
```

| Status code | Meaning                                                                                                                                                                                             |
| ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `400`       | **Bad request** — A required parameter is missing, empty, or invalid. Check the `error` field for details on which field failed validation.                                                         |
| `401`       | **Not authenticated** — Your session cookie is missing or has expired. Re-authenticate and retry.                                                                                                   |
| `403`       | **Forbidden** — Your plan does not include the feature you are trying to use, or the request failed a CSRF origin check.                                                                            |
| `404`       | **Not found** — The session or resource you referenced does not exist, or it belongs to a different user or organisation.                                                                           |
| `429`       | **Rate 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. |
| `502`       | **Upstream error** — The AI provider returned an error or was unreachable. Retry with backoff.                                                                                                      |
| `503`       | **Service unavailable** — Knoq is temporarily unable to handle the request. Retry with backoff.                                                                                                     |

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

## Available endpoints

<CardGroup cols={2}>
  <Card title="Sessions" icon="comment-dots" href="/api-reference/sessions/create">
    Create, list, and delete AI agent sessions. A session represents a
    persistent conversation thread.
  </Card>

  <Card title="Messaging" icon="paper-plane" href="/api-reference/messages/send">
    Send follow-up messages to an active session and retrieve the full
    transcript of a conversation.
  </Card>

  <Card title="SCIM" icon="users" href="/api-reference/scim/overview">
    Provision and deprovision users and groups in Knoq from your identity
    provider using the SCIM 2.0 protocol.
  </Card>
</CardGroup>