create_channel_call
const url = 'https://app.everruns.com/api/v1/agents/example/channels/example/voice/calls';const options = { method: 'POST', headers: {'Content-Type': 'application/json'}, body: '{"provider_id":"example","sdp":"example","session_id":"example"}'};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request POST \ --url https://app.everruns.com/api/v1/agents/example/channels/example/voice/calls \ --header 'Content-Type: application/json' \ --data '{ "provider_id": "example", "sdp": "example", "session_id": "example" }'Call an agent’s voice channel. Starts a new session for the call, or continues an existing session of the agent.
Parameters
Section titled “ Parameters ”Path Parameters
Section titled “Path Parameters”Request Bodyrequired
Section titled “Request Bodyrequired”Request body for a call to an agent’s voice channel.
object
Realtime provider binding, as in VoiceCallRequest.
The browser’s WebRTC SDP offer.
Continue an existing session of the channel’s agent (for example a text conversation). When omitted, the call starts a new session.
Examplegenerated
{ "provider_id": "example", "sdp": "example", "session_id": "example"}Responses
Section titled “ Responses ”Session and realtime WebRTC call started
A channel call: the session it talks to and the call itself.
object
The session the call is attached to.
object
Number of active (enabled) schedules for this session. Populated when the session is fetched for API responses.
Outcome-oriented status derived from status and the last turn result.
This is the value the sessions list groups by and the facet rail counts.
ID of the agent working in this session (format: agent_{32-hex}). Optional.
Revision of the agent’s history this session started on, when the
agent had one. everruns history show <agent> --revision N shows the
configuration that ran.
When this session was archived; None means active. Archived sessions
are hidden from default list results and shown by opting in
(include_archived=true). Unlike is_pinned, archive is a property of
the session itself rather than of the viewer.
Validated config passed by host at blueprint spawn time.
Example: {"target_repo": "acme/everruns"}.
Blueprint ID. When set, reason_activity and act_activity build RuntimeAgent from the blueprint definition instead of from harness_id/agent_id.
Session-level capabilities (additive to agent capabilities). Applied after agent capabilities when building RuntimeAgent.
Per-agent capability configuration
Associates a capability with an agent, including optional per-agent configuration. The config field allows the same capability to behave differently per-agent.
object
Per-agent configuration for this capability (capability-specific)
Reference to the capability ID
Timestamp when the session was created.
Total events recorded for this session (EVE-868). Derived from the
session’s event sequence rather than counted, so the session detail
tab bar costs no extra scan over events.
None on payloads built outside the database read path.
Aggregated UI features from all active capabilities (harness + agent + session). Computed at read time from the capability registry. Known features: “file_system”, “schedules”, “secrets”, “key_value”, “sql_database”, “leased_resources”.
Non-directory files in this session’s workspace (EVE-868). Read from
workspaces.file_count. Counts persisted files only: capability-provided
virtual mounts are served from memory and are not included.
Timestamp when the session finished (completed or failed).
Parent event sequence the fork was taken at (the fork point). NULL unless this session is a fork.
Session this one was forked from. NULL for sessions that were not forked.
Distinct from parent_session_id (subagent nesting): forking is a
user-initiated “branch from here” relationship.
Session objective visible to the runtime agent at system-prompt level.
ID of the harness for this session (format: harness_{32-hex}).
Session-level client hints — arbitrary key-value pairs declared by the
client at session creation time. These are defaults for every turn;
per-message controls.hints override these key-by-key (shallow merge).
Examples: {"setup_connection": true, "rich_media": true}
Unique identifier for the session (format: session_{32-hex}).
Starting files for a new file tree (additive to agent/harness files). Matching paths override earlier layers. Rejected when attaching workspace_id.
Starter file copied into a new session from an agent or harness.
object
File content: plain text or base64-encoded binary.
Content encoding: text or base64.
Prevent session-side edits or deletes when true.
Absolute path within the session workspace. /workspace prefix is accepted.
Whether this session is pinned by the current user. Only populated when the request has an authenticated user context.
Locale for localized agent behavior and formatting (BCP 47, e.g. uk-UA).
Maximum number of LLM iterations per turn for this session.
Remote MCP servers scoped to this session only.
object
Session-, agent-, or harness-scoped remote MCP server configuration.
This intentionally mirrors the mcpServers object shape used by common MCP
client config files while staying within Everruns’ current remote-HTTP-only
support.
object
Identity whose grant this attachment requests.
Arguments passed to the stdio command.
Authentication mode used when executing tools from this scoped server.
Executable to spawn for a stdio transport server.
Whether a missing sign-in may pause the turn with an in-chat Connect
card (ask, the default) or fails the call with a settings link
(never).
Whether the server’s tools are listed only when the model asks for
them through tool search (false, the default, lists them at turn
start).
Which elicitation modes this server may use (url by default).
Environment variables set for the stdio command.
object
Additional HTTP headers sent on MCP requests (HTTP transport only).
object
Provider id used to resolve a user-scoped bearer token.
Protocol-era adoption policy for the MCP client (auto negotiates).
Whether to discover tool definitions live from this server.
MCP transport type. Only remote HTTP is supported today.
URL of the remote MCP server endpoint. Required for HTTP transport; empty/ignored for stdio.
LLM model ID to use for this session (format: model_{32-hex}). Overrides the agent’s default model if set.
Network access list controlling which hosts/URLs this session can reach. Merged with harness and agent layers (allowed: intersect, blocked: union).
object
Allowed host patterns. If non-empty, only matching URLs are permitted. An empty list means “no restriction from this layer” (inherit parent).
Blocked host patterns. Always denied, even if matched by allowed.
Organization this session belongs to (format: org_{32-hex}).
Preview text from the last assistant response (truncated).
Owning principal for this session.
Request-level parallel tool calling preference (EVE-598).
None (default) preserves provider defaults. Some(true) signals the
provider that parallel tool calls are wanted; Some(false) requests at
most one tool call per turn and forces serial execution. Merged across
harness/agent/session layers (overlay wins).
Parent session that spawned this subagent. NULL for top-level sessions. Used to compute governed subagent delegation depth.
Fixed end-user identity for a Playground conversation; independent of the resident service.
Preview text from the first user message (truncated).
Denormalized effective human owner of the owning principal lineage.
Generated one-sentence description of what the run did, and where it failed (EVE-867). Absent until a terminal turn has been summarised, and always absent for chat threads and for deployments with no utility LLM, so a reader must have a fallback rather than treating this as required.
How this session was started. Server-owned for every ingress path.
Timestamp when the session started executing.
Current execution status of the session.
object
object
Session-level system prompt override. Prepended to the agent’s system prompt when building RuntimeAgent.
Tags for organizing and filtering sessions.
Background work owned by this session — subagents, external agents and
background tools (EVE-868). Read from sessions.task_count. This is
what the Work tab holds; active_schedule_count describes only the
schedules it also lists.
Human-readable title for the session.
Client-side tools for this session (additive to agent tools).
Built-in tool - executed by the worker via ToolRegistry
object
Category for tool_search namespace grouping (from parent capability)
Whether this tool’s schema can be deferred via tool_search
Tool description for LLM
Human-readable display name for UI rendering (e.g., “Get Current Time” for get_current_time)
Original full parameter schema saved by DeferSchemaHook before stripping.
Serialized only when present so durable reason-to-act scheduling can
preserve deferred schemas for tool_search in the act phase.
Semantic hints describing the tool’s behavioral properties
object
Capability that contributed this tool definition.
Reporting uses this attribution only as metadata. It must never contain tool arguments, results, prompts, or any other sensitive payload.
Human-readable capability name snapshot for reporting.
Scheduling conflict key. Tool calls within the same act batch that share
a non-empty concurrency_class are executed sequentially in arrival
order; calls in different classes (or with no class) run concurrently.
Set this on tools that mutate shared session state so that, e.g., two
file writes or two SQL mutations in one batch do not race. Read-only
tools should leave this None so they always parallelize. See
everruns-engine’s tool scheduler for how the act phase consumes it.
Tool performs significant CPU-bound or otherwise non-yielding work in
process (e.g. an in-process interpreter). When true, the act scheduler
runs the call on its own task (tokio::spawn) so a long CPU burst does
not starve the cooperative polling of I/O-bound tools in the same batch.
Distinct from long_running, which describes wall-clock time for
I/O-bound work (those tools yield at await points and need no offload).
Tool may irreversibly destroy or delete data. Subset of non-readonly — a tool can be non-readonly (writes) without being destructive (e.g., create/update operations).
Calling the tool repeatedly with the same arguments produces the same effect. Safe to retry on transient failures.
Tool may take significant time to complete (> ~5s typical). Useful for clients to show progress indicators and set timeouts.
Host-owned annotations that core does not interpret.
The typed hints above are the vocabulary core itself reasons about. This
is the escape hatch for everything a host wants to carry alongside a
tool — risk tiers for an approval UI, presentation hints, an embedder’s
routing keys — without adding a field to core for each one. Core reads
nothing here and no driver sends it to a provider; it travels with the
definition so a consumer sees it at the point of decision (e.g. a
PreToolUseHook gating on what the tool declared).
The schema belongs to whoever writes it. Never put credentials or other sensitive payload here: like the rest of the definition, it is persisted and surfaced to clients.
Entity noun for operation-based narration (e.g. “agent”, “harness”).
When set, the narration system reads the operation argument and
produces verb-based narration like “Created agent: Neon Cartographer”
instead of the generic “Ran Manage Agents”.
Tool interacts with external entities beyond the local system (network calls, third-party APIs, cloud services).
Tool output should be persisted to session VFS before truncation.
When set, the tool_output_persistence capability (EVE-222, EVE-245) writes
stdout to /outputs/{tool_call_id}.stdout and stderr to
/outputs/{tool_call_id}.stderr, injecting full_output, total_lines,
and output_files into the result.
Tool does not modify any state (read-only queries, lookups). When true: safe to call speculatively, result can be cached.
Tool requires API keys, credentials, or other secrets to function. Useful for UI to show connection prompts and for LLMs to anticipate authentication failures.
Replay-safety class used by the durable Act activity (EVE-530).
Controls what happens when a worker reclaims a stale running claim:
Pure/Idempotent tools are re-executed; AtMostOnce tools are
settled as interrupted to prevent double side-effects.
None is treated conservatively as AtMostOnce.
Tool must stay a direct tool call and never runs from inside a shell
script (tools_in_shell): it pauses or shapes the turn, or its result
only makes sense to the model directly.
Tool supports detached background execution via spawn_background.
When true, the tool may be executed asynchronously outside the current
foreground tool call and report status back later.
Tool name (used by LLM and for registry lookup)
JSON schema for tool parameters
Tool policy (auto or requires_approval)
Client-side tool - executed by the client, not the server
object
Category for tool_search namespace grouping (from parent capability)
Whether this tool’s schema can be deferred via tool_search
Tool description for LLM
Human-readable display name for UI rendering
Original full parameter schema saved by DeferSchemaHook before stripping.
Serialized only when present so durable reason-to-act scheduling can
preserve deferred schemas for tool_search in the act phase.
Semantic hints describing the tool’s behavioral properties
object
Capability that contributed this tool definition.
Reporting uses this attribution only as metadata. It must never contain tool arguments, results, prompts, or any other sensitive payload.
Human-readable capability name snapshot for reporting.
Scheduling conflict key. Tool calls within the same act batch that share
a non-empty concurrency_class are executed sequentially in arrival
order; calls in different classes (or with no class) run concurrently.
Set this on tools that mutate shared session state so that, e.g., two
file writes or two SQL mutations in one batch do not race. Read-only
tools should leave this None so they always parallelize. See
everruns-engine’s tool scheduler for how the act phase consumes it.
Tool performs significant CPU-bound or otherwise non-yielding work in
process (e.g. an in-process interpreter). When true, the act scheduler
runs the call on its own task (tokio::spawn) so a long CPU burst does
not starve the cooperative polling of I/O-bound tools in the same batch.
Distinct from long_running, which describes wall-clock time for
I/O-bound work (those tools yield at await points and need no offload).
Tool may irreversibly destroy or delete data. Subset of non-readonly — a tool can be non-readonly (writes) without being destructive (e.g., create/update operations).
Calling the tool repeatedly with the same arguments produces the same effect. Safe to retry on transient failures.
Tool may take significant time to complete (> ~5s typical). Useful for clients to show progress indicators and set timeouts.
Host-owned annotations that core does not interpret.
The typed hints above are the vocabulary core itself reasons about. This
is the escape hatch for everything a host wants to carry alongside a
tool — risk tiers for an approval UI, presentation hints, an embedder’s
routing keys — without adding a field to core for each one. Core reads
nothing here and no driver sends it to a provider; it travels with the
definition so a consumer sees it at the point of decision (e.g. a
PreToolUseHook gating on what the tool declared).
The schema belongs to whoever writes it. Never put credentials or other sensitive payload here: like the rest of the definition, it is persisted and surfaced to clients.
Entity noun for operation-based narration (e.g. “agent”, “harness”).
When set, the narration system reads the operation argument and
produces verb-based narration like “Created agent: Neon Cartographer”
instead of the generic “Ran Manage Agents”.
Tool interacts with external entities beyond the local system (network calls, third-party APIs, cloud services).
Tool output should be persisted to session VFS before truncation.
When set, the tool_output_persistence capability (EVE-222, EVE-245) writes
stdout to /outputs/{tool_call_id}.stdout and stderr to
/outputs/{tool_call_id}.stderr, injecting full_output, total_lines,
and output_files into the result.
Tool does not modify any state (read-only queries, lookups). When true: safe to call speculatively, result can be cached.
Tool requires API keys, credentials, or other secrets to function. Useful for UI to show connection prompts and for LLMs to anticipate authentication failures.
Replay-safety class used by the durable Act activity (EVE-530).
Controls what happens when a worker reclaims a stale running claim:
Pure/Idempotent tools are re-executed; AtMostOnce tools are
settled as interrupted to prevent double side-effects.
None is treated conservatively as AtMostOnce.
Tool must stay a direct tool call and never runs from inside a shell
script (tools_in_shell): it pauses or shapes the turn, or its result
only makes sense to the model directly.
Tool supports detached background execution via spawn_background.
When true, the tool may be executed asynchronously outside the current
foreground tool call and report status back later.
Tool name (used by LLM and for correlation)
JSON schema for tool parameters
Timestamp when the session was last updated.
Cumulative token usage for all LLM calls in this session.
object
Actual cost of this generation in USD, as reported by the provider inline
(e.g. OpenRouter’s usage.cost, which reflects real post-routing/BYOK/cache
pricing). None for providers that do not return a cost.
Number of tokens written to cache, disjoint from input_tokens
Number of tokens read from cache (reduces cost), disjoint from input_tokens
Best-effort USD cost when it cannot be derived from actual/estimated alone: already-aggregated usage, or a generation carrying a cost that belongs to neither slot. Per-generation usage normally leaves this unset and derives the effective cost from actual-else-estimated; the exception is a turn whose compaction cost is folded in, where the combined total has to live here precisely so the generation’s own actual-vs-estimated distinction survives (EVE-895).
Estimated cost of this generation in USD, derived from the model’s static
price-table profile. Computed whenever a profile with cost data exists,
independently of actual_cost_usd, so estimate-vs-actual drift can be
reconciled. None when there is no profile cost data for the model.
Number of non-cached prompt tokens (cached reads/writes are tracked separately; see the disjoint bucket convention on the struct)
Number of output/completion tokens
Optional resident virtual user for unattended/background execution.
Workspace this session is attached to (format: wsp_{32-hex}). Owns the session’s virtual filesystem. For the default 1:1 case this mirrors the session id, but clients should read it here rather than deriving it.
The started call.
object
SDP answer that completes the browser’s WebRTC handshake.
Voice channel whose settings the call uses, when there is one.
When the call’s lease expires (RFC 3339).
Speech model.
Realtime provider type serving the call (e.g. openai).
Provider-side call identifier.
Provider voice.
Prefixed public identifier of the voice connection.
Example
{ "session": { "active_schedule_count": 2, "activity": "running", "agent_id": "agent_01933b5a00007000800000000000001", "agent_revision": 4, "archived_at": "2026-05-25T10:14:32Z", "blueprint_id": "blueprint_research_pack", "created_at": "2026-05-25T10:00:00Z", "effective_owner": { "id": "principal_01933b5a000070008000000000000001", "kind": "user" }, "event_count": 42, "features": [ "file_system", "secrets" ], "file_count": 6, "finished_at": "2026-05-25T10:14:32Z", "forked_from_sequence": 42, "goal": "Investigate the queue latency regression", "harness_id": "harness_01933b5a00007000800000000000001", "id": "session_01933b5a00007000800000000000001", "is_pinned": false, "locale": "en-US", "max_iterations": 50, "mcpServers": { "additionalProperty": { "actsAs": "none", "auth_mode": "none", "connectInChat": "ask", "elicitation_policy": "url", "protocol_mode": "auto", "type": "http", "use": "catalog:linear" } }, "model_id": "model_01933b5a00007000800000000000001", "network_access": { "allowed": [ "*.example.com", "https://api.acme.com/" ], "blocked": [ "169.254.169.254" ] }, "organization_id": "org_00000000000000000000000000000001", "output_preview": "Here is a Q3 plan covering the three pillars we discussed...", "owner": { "id": "principal_01933b5a000070008000000000000001", "kind": "user" }, "owner_principal_id": "principal_01933b5a000070008000000000000001", "parallel_tool_calls": true, "preview": "Help me draft the Q3 marketing plan", "resolved_owner_user_id": "550e8400-e29b-41d4-a716-446655440000", "run_summary": "Ran the nightly report and failed posting it to Slack: channel_not_found.", "source": "chat", "started_at": "2026-05-25T10:00:01Z", "tags": [ "marketing", "q3", "draft" ], "task_count": 3, "title": "Q3 marketing brief", "tools": [ { "deferrable": "never", "hints": { "side_effect_class": "Pure" }, "policy": "auto", "type": "builtin" } ], "updated_at": "2026-05-25T10:14:32Z", "virtual_user_id": "identity_01933b5a00007000800000000000001", "workspace_id": "wsp_01933b5a00007000800000000000001" }}