Create a session and send the first message

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

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.

Response

string

The unique session ID. Pass this value as sessionId in subsequent message, transcript, cancel, and delete calls.

string

The workflow run ID for the background execution driving this session. Useful for diagnostics and support requests.

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.

Example

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."
  }'

{
  "id": "a3f2c1d4-e5b6-7890-abcd-ef1234567890",
  "runId": "run_01HZ9K2XQTV3N8PMYW46BRCJ5F",
  "noConnectors": false
}

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.

Overview

Sessions

Messaging

SCIM Provisioning

Create a session and send the first message

Request

Response

Example

Errors

​Request

​Response

​Example

​Errors

Request

Response

Example

Errors