Skip to main content
POST
Ask CloudThinker: start an agent run, or continue a conversation.
Scope: chat:runs:write. See API Tokens.

Authorizations

Authorization
string
header
required

CloudThinker token: a personal access token ct_pat_… (fine-grained scopes, created in Settings) or an OAuth access token ct_oat_… (1 hour, from the OAuth flow). Send Authorization: Bearer <token>. Scopes have the form module:resource:read|write; write includes read.

Headers

Idempotency-Key
string
required

Unique per logical write. A retry with the same key and body returns the first result.

Required string length: 1 - 255

Path Parameters

workspace_id
string<uuid>
required

Workspace to act in. Every call names it.

Body

application/json
prompt
string
required

What to ask CloudThinker.

Required string length: 1 - 50000
conversation_id
string<uuid> | null

Continue this conversation. Omit to start a new one.

agent
string | null

Run a custom agent of this workspace, by its id or alias. Omit to use the default agent.

Required string length: 1 - 255

Response

Created

One agent run started through the API.

id
string<uuid>
required
conversation_id
string<uuid> | null
required
status
enum<string>
required
Available options:
pending,
running,
succeeded,
failed,
required_approval,
cancelled
answer
string | null
required

Final answer. Set only when status is succeeded.

message
string | null
required

Status message, for example why the run failed.

failure_kind
string | null
required
url
string | null
required

The conversation in the browser. Open it when status is required_approval.

created_at
string<date-time>
required
started_at
string<date-time> | null
required
ended_at
string<date-time> | null
required