Skip to main content
POST
/
agents
/
{agentId}
/
threads
JavaScript
import Cerca from '@cerca-dev/sdk';

const client = new Cerca({
  apiKey: process.env['CERCA_API_KEY'], // This is the default and can be omitted
});

const thread = await client.threads.create('agent_abc123');

console.log(thread.id);
{
  "agentId": "<string>",
  "completedAt": "<string>",
  "createdAt": "<string>",
  "depth": 123,
  "error": "<string>",
  "id": "<string>",
  "instructions": "<string>",
  "model": "<string>",
  "parentThreadId": "<string>",
  "result": "<string>",
  "scheduleId": "<string>",
  "scheduleSeq": 123,
  "updatedAt": "<string>",
  "message": "<string>",
  "compiledContext": {
    "enabledTools": [],
    "systemPrompt": "<string>",
    "turnId": "<string>"
  },
  "compactionSummary": "<string>",
  "compactionThroughSeq": 123,
  "composedSystemPrompt": "<string>",
  "contextWindow": {
    "compacted": true,
    "compactionThroughSeq": 123,
    "contextWindowTokens": 123,
    "llmEstimatedTokens": 123,
    "model": "<string>",
    "rawEstimatedTokens": 123
  },
  "hasMoreMessages": true,
  "messageCursor": 123,
  "messages": [
    {
      "content": [
        {
          "text": "Hello",
          "type": "text"
        }
      ],
      "createdAt": "<string>",
      "seq": 123
    }
  ],
  "subThreads": [
    {
      "completedAt": "<string>",
      "createdAt": "<string>",
      "id": "<string>",
      "messageCount": 123,
      "model": "<string>",
      "parentThreadId": "<string>",
      "result": "<string>",
      "scheduleId": "<string>",
      "scheduleSeq": 123,
      "stepCount": 123,
      "toolUseId": "<string>"
    }
  ],
  "tools": [],
  "turns": [
    {
      "completedAt": "<string>",
      "endMessageSeq": 123,
      "error": "<string>",
      "id": "<string>",
      "result": "<string>",
      "seq": 123,
      "startMessageSeq": 123,
      "startedAt": "<string>",
      "threadId": "<string>",
      "tokenUsage": {
        "inputTokens": 123,
        "outputTokens": 123
      },
      "message": "<string>"
    }
  ],
  "activeTurnModel": "<string>"
}

Documentation Index

Fetch the complete documentation index at: https://docs.cerca.dev/llms.txt

Use this file to discover all available pages before exploring further.

Authorizations

Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Path Parameters

agentId
string
required
Minimum string length: 1
Example:

"agent_abc123"

Body

application/json
instructions
string
model
string
systemPrompt
string

Deprecated alias for instructions; accepted for backwards compatibility.

tools
string[]

Per-thread tool subset. Omit to inherit the agent's full effective tools; pass [] to run with no configurable tools. Provided entries can only narrow the agent's effective tools.

Configurable runtime tool name, configurable namespace wildcard such as sandbox., or external namespace wildcard such as google.. At thread and turn scope, entries can only narrow the agent's effective tools.

Minimum string length: 1
message
string

Response

Thread created.

agentId
string
required
completedAt
string | null
required
createdAt
string
required
depth
number
required
error
string | null
required
id
string
required
instructions
string | null
required
model
string
required
parentThreadId
string | null
required
result
string | null
required
scheduleId
string | null
required
scheduleSeq
number | null
required
status
enum<string>
required

idle threads can accept a new turn or be closed. running threads have an active turn. awaiting threads are paused on external input such as approvals. closed threads are terminal.

Available options:
idle,
running,
awaiting,
closed
updatedAt
string
required
message
string
required
compiledContext
object
required
compactionSummary
string | null
required
compactionThroughSeq
number | null
required
composedSystemPrompt
string | null
required
contextWindow
object
required
hasMoreMessages
boolean
required
lastTurnStatus
enum<string> | null
required
Available options:
completed,
failed,
null
messageCursor
number | null
required
messages
object[]
required
subThreads
object[]
required
tools
enum<string>[]
required
Available options:
get_time,
sub_thread,
wait,
tool.call,
tool.discover,
artifact.read,
agent.threads.list,
agent.threads.get,
agent.approvals.cancel,
agent.approvals.grant_thread,
agent.approvals.grant_agent,
agent.create,
agent.approvals.update,
tool.connect,
sandbox.exec,
sandbox.read,
sandbox.write_file,
sandbox.read_file,
sandbox.spawn,
sandbox.stdin,
sandbox.session_read,
sandbox.kill,
sandbox.list_sessions,
sandbox.sync_artifact,
memory.read,
memory.list,
memory.search,
memory.write,
memory.delete,
db.query,
web.search,
web.fetch,
agent.schedule.list,
agent.schedule.create,
agent.schedule.update,
agent.schedule.delete,
agent.schedule.trigger
turns
object[]
required
externalToolNamespaces
Available options:
all
activeTurnModel
string | null