Skip to main content
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

​
text
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

​
id
string
The unique session ID. Pass this value as sessionId in subsequent message, transcript, cancel, and delete calls.
​
runId
string
The workflow run ID for the background execution driving this session. Useful for diagnostics and support requests.
​
noConnectors
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."
  }'

​
Errors

StatusMeaning
400text is missing or empty.
401The request is not authenticated. Ensure your session cookie is valid and has not expired.
403Your organisation’s plan does not allow new session creation. Upgrade your plan to continue.
429Rate 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.
502Knoq could not reach the upstream AI provider. Wait a moment and try again.