Runtime API

Core concepts

The runtime surface is deliberately small. Four primitives cover everything — capabilities, sessions, executions, and event streams.

Capabilities

A capability is a single tool your organization can invoke. There are two kinds.

integrationkindoptional
A tool exposed by a connected account (LinkedIn, Gmail, Salesforce, Attio, and more). Lives behind Copia's integration gateway.
memorykindoptional
Durable GTM memory — ICP, playbook, tone, daily notes — read and written through memory_ls, memory_read, memory_search, memory_write, and memory_append.

Example capability

json

{
  "name": "linkedin_search_people",
  "kind": "integration",
  "description": "Search LinkedIn people",
  "parameters": {
    "type": "object",
    "properties": {
      "keywords": { "type": "string" }
    },
    "required": ["keywords"]
  },
  "isReadOnly": true,
  "supportsIdempotency": true,
  "accounts": [
    {
      "connectedAccountId": "acc_1",
      "integrationId": "linkedin",
      "backend": "unipile"
    }
  ]
}

Multiple accounts

When an integration capability is connected on more than one account, the capability carries all accounts[] entries. Invocations must pass connectedAccountId so Copia knows which account should execute.

Sessions

A session is a container for related executions. Direct tool invocations create a session automatically. Create one explicitly when you want continuity — a title, a single parent for audit logs, or reuse across many calls.

idstringoptional
Opaque session identifier. Pass this back on future tool calls to attribute them to the same session.
titlestringoptional
Human-readable label shown in the Copia dashboard. Defaults to "Agent Runtime Session".
sourcestringoptional
Origin of the session — api when created with an API key, user when created via the Copia web app.
interactionModeenumoptional
Currently always execute for runtime sessions. plan mode is reserved for first-class agent planning flows.
statusenumoptional
Session lifecycle: active while it's accepting new executions, archived once closed.

Executions

An execution is one tool run. Every invocation produces exactly one execution, with its own id, status timeline, and result payload. Executions are what you stream.

Hold onto executionId from the invocation response. It is the handle you need to open or replay the event stream.

Event stream

Copia emits a stable envelope first, then capability-specific progress, then a terminal event. Plain text/event-stream — any SSE client works.

Example stream

text

event: session
data: {"id":"session_123","executionId":"exec_123","runId":"run_123","interactionMode":"execute"}

event: run_status
data: {"runId":"run_123","executionId":"exec_123","status":"executing","interactionMode":"execute"}

event: tool_use
data: {"id":"runtime_abcd12","name":"memory_search","input":{"query":"enterprise fintech ICP"},"executionId":"exec_123","runId":"run_123"}

event: tool_result
data: {"id":"runtime_abcd12","name":"memory_search","output":{"hits":[{"path":"/topics/icp.md","score":10}]},"error":false,"executionId":"exec_123","runId":"run_123"}

event: done
data: {"status":"completed","summary":"1 hits","executionId":"exec_123","runId":"run_123"}

Event types

sessioneventoptional
Sent once at the start with session, execution, and run ids.
run_statuseventoptional
High-level state transitions: executing, waiting, failed, completed.
tool_useeventoptional
The capability name plus the exact invocation payload.
tool_resulteventoptional
Return payload plus an error boolean.
checkpointeventoptional
Optional human-readable summaries emitted during long runs.
doneeventoptional
Terminal success event with a summary.
erroreventoptional
Terminal failure event with a message.

Ready for endpoint-level detail? Jump to the API reference.

PreviousAuthentication NextAPI reference