Returns every org-scoped capability plus URL templates for invocations and streams. Use this first — an agent can build its entire tool catalog from this response.

GET/api/runtime/capabilities

Request

bash

curl https://copia-ai.com/api/runtime/capabilities \
  -H "Authorization: Bearer $COPIA_API_KEY"

Response

json

{
  "capabilities": [
    {
      "name": "memory_search",
      "kind": "memory",
      "description": "Search durable Copia memory for prior GTM context and decisions.",
      "parameters": {
        "type": "object",
        "properties": {
          "query": { "type": "string" },
          "limit": { "type": "integer" }
        },
        "required": ["query"]
      },
      "isReadOnly": true,
      "supportsIdempotency": true,
      "accounts": []
    }
  ],
  "sessionCreateUrl": "https://copia-ai.com/api/runtime/sessions",
  "toolInvokeUrlTemplate": "https://copia-ai.com/api/runtime/tools/{toolName}",
  "sessionToolInvokeUrlTemplate": "https://copia-ai.com/api/runtime/sessions/{sessionId}/tools/{toolName}",
  "executionEventsUrlTemplate": "https://copia-ai.com/api/runtime/executions/{executionId}/events"
}

Invoke a tool

Invokes a capability by name. Copia creates a session automatically unless you pass sessionId. The response includes the synchronous result and an executionId you can stream.

POST/api/runtime/tools/{toolName}

Body parameters

inputobjectoptional
Capability-specific input. Must match the parameters schema returned by the capabilities list.
connectedAccountIdstringoptional
Required when the capability exists on multiple connected accounts — see the 409 response below.
sessionIdstringoptional
Existing session id to attribute this call to. Omit to let Copia create a session.
titlestringoptional
Only used when Copia creates a session for you. Defaults to "Agent Runtime Session".

Request

bash

curl -X POST https://copia-ai.com/api/runtime/tools/memory_search \
  -H "Authorization: Bearer $COPIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Claude GTM runtime",
    "input": {
      "query": "enterprise fintech ICP",
      "limit": 5
    }
  }'

Response

json

{
  "session": {
    "id": "session_123",
    "title": "Claude GTM runtime",
    "source": "api",
    "interactionMode": "execute",
    "status": "active",
    "createdAt": "2026-04-15T10:00:00.000Z",
    "updatedAt": "2026-04-15T10:00:00.000Z"
  },
  "capability": {
    "name": "memory_search",
    "kind": "memory",
    "description": "Search durable Copia memory for prior GTM context and decisions.",
    "isReadOnly": true,
    "supportsIdempotency": true,
    "accounts": []
  },
  "runId": "run_123",
  "executionId": "exec_123",
  "executionEventsUrl": "https://copia-ai.com/api/runtime/executions/exec_123/events",
  "summary": "1 hits",
  "result": { "hits": [{ "path": "/topics/icp.md", "score": 10 }] }
}

Ambiguous account (409)

When a capability has more than one connected account, invocations without connectedAccountId return 409 and enumerate the options. Pick one and retry.

409 response body

json

{
  "error": "Capability \"linkedin_search_people\" requires connectedAccountId because it is available on multiple connected accounts",
  "details": {
    "availableAccounts": [
      { "connectedAccountId": "acc_1", "integrationId": "linkedin", "backend": "unipile" },
      { "connectedAccountId": "acc_2", "integrationId": "linkedin", "backend": "unipile" }
    ]
  }
}

Create a session

Create a reusable session explicitly when you want continuity across multiple direct invocations.

POST/api/runtime/sessions

Body parameters

titlestringoptional
Human-readable session label shown in the Copia dashboard.

Request

bash

curl -X POST https://copia-ai.com/api/runtime/sessions \
  -H "Authorization: Bearer $COPIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "title": "Claude GTM runtime" }'

Response

json

{
  "session": {
    "id": "session_123",
    "title": "Claude GTM runtime",
    "source": "api",
    "interactionMode": "execute",
    "status": "active",
    "createdAt": "2026-04-15T10:00:00.000Z",
    "updatedAt": "2026-04-15T10:00:00.000Z"
  }
}

Get a session

Fetch session metadata plus capability and event URL templates. Useful to re-discover templates mid-run without re-listing capabilities.

GET/api/runtime/sessions/{sessionId}

List capabilities for a session

Same payload as GET /api/runtime/capabilities — handy when your agent has a sessionId on hand and wants to re-sync its tool catalog.

GET/api/runtime/sessions/{sessionId}/capabilities

Invoke a tool inside a session

Same body as POST /api/runtime/tools/{toolName} — but the invocation is pinned to the provided session, so all executions share a parent in audit logs.

POST/api/runtime/sessions/{sessionId}/tools/{toolName}

Stream an execution

Server-sent events. Connect immediately after invocation to catch every tool_use, tool_result, checkpoint, and terminal event.

GET/api/runtime/executions/{executionId}/events

Open the stream

bash

curl -N https://copia-ai.com/api/runtime/executions/exec_123/events \
  -H "Authorization: Bearer $COPIA_API_KEY"

Example events

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

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

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

event: done
data: {"status":"completed","summary":"1 hits"}

Event reference

See Core concepts → Event stream for the full event catalog and payload shapes.

PreviousCore concepts NextErrors