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

# Create a session and send the first message

> POST /api/managed-agents/session — create a new Knoq session and send the opening message. Returns the session ID and workflow run ID.

Every Knoq conversation starts with a session. When you call this endpoint you provide the opening message, and Knoq immediately starts a background workflow that routes your query through the appropriate AI agent and connected integrations. The response gives you the `id` you'll use for all subsequent calls on this conversation and the `runId` that identifies the underlying workflow execution.

```
POST /api/managed-agents/session
```

## Request

<ParamField body="text" type="string" required>
  The opening message for the session. Must be a non-empty string. Knoq uses the first 60 characters to generate an automatic session title.
</ParamField>

## Response

<ResponseField name="id" type="string">
  The unique session ID. Pass this value as `sessionId` in subsequent message, transcript, cancel, and delete calls.
</ResponseField>

<ResponseField name="runId" type="string">
  The workflow run ID for the background execution driving this session. Useful for diagnostics and support requests.
</ResponseField>

<ResponseField name="noConnectors" type="boolean">
  `true` when your account has no integrations connected yet. When this is `true`, the agent can still respond but won't be able to query tools like Slack, Notion, or GitHub. Show a prompt in your UI encouraging the user to connect at least one integration in their Knoq settings to enable tool use.
</ResponseField>

## Example

<CodeGroup>
  ```bash curl theme={null}
  curl -X POST https://knoq.one/api/managed-agents/session \
    -H "Content-Type: application/json" \
    -H "Origin: https://knoq.one" \
    -H "Cookie: <your-session-cookie>" \
    -d '{
      "text": "Summarise the open GitHub issues assigned to me this week."
    }'
  ```

  ```json Response theme={null}
  {
    "id": "a3f2c1d4-e5b6-7890-abcd-ef1234567890",
    "runId": "run_01HZ9K2XQTV3N8PMYW46BRCJ5F",
    "noConnectors": false
  }
  ```
</CodeGroup>

## Errors

| Status | Meaning                                                                                                                                                                                                 |
| ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `400`  | `text` is missing or empty.                                                                                                                                                                             |
| `401`  | The request is not authenticated. Ensure your session cookie is valid and has not expired.                                                                                                              |
| `403`  | Your organisation's plan does not allow new session creation. Upgrade your plan to continue.                                                                                                            |
| `429`  | Rate limit exceeded. You may create at most 10 sessions per minute and 20 sessions per hour per user. The response includes a `Retry-After` header indicating how many seconds to wait before retrying. |
| `502`  | Knoq could not reach the upstream AI provider. Wait a moment and try again.                                                                                                                             |