Skip to content
Docs
GitHub

Import agent from file or built-in example

Preview

Two modes:

  1. From example — POST /v1/agents/import?from-example={name} (body ignored)
  2. From package — text (Markdown/TOML/YAML/JSON), ZIP, or a PackageInput envelope.

Package mode accepts:

  • Markdown with YAML front matter (if starts with —)
  • Pure YAML
  • Pure JSON
  • Plain text (treated as instructions; defaults to name agent)
  • TOML and ZIP folders, with complete assets and skill directories

If the file contains an id field and an agent with that ID already exists, the agent is updated (upsert). Returns 201 on create, 200 on update.

Public APIEverruns Cloud and self-hosted Platform

POST/v1/agents/import

See authentication for credentials and permissions.

from-example
string

Import from a built-in example by name (e.g. dad-jokes-agent). When set, the request body is ignored.

target
string

Explicit target agent name for an update. Omit to create a new agent.

format
string

Input format: markdown, toml, yaml, json or zip. Omit to detect it.

Media typetext/plain
string

Responses

200Agent updated via import

Agent updated via import

Media typeapplication/json

Wrapper that adds API and UI links to a serialized resource.

Uses self_url (not url) for the API link to avoid collision with resources that already have a url field (e.g. McpServer). The allowed_actions array carries state-aware hypermedia links — empty (and omitted from the wire shape) until the underlying resource opts into the convention by overriding ResourceUrlable::allowed_actions.

object
archived_at

Timestamp when the agent was archived.

string | null format: date-time
avatar
One of:

Avatar shown wherever the agent appears: the UI, the A2A Agent Card and its Slack app. Set with PUT /v1/agents/{agent_id}/avatar.

object
circle_url
required

Circular avatar (transparent corners), 256 px.

string
id
required

Prefixed public identifier. See ID Schema.

string
sizes
required

Edge lengths, in pixels, available for both shapes.

Array<integer>
url
required

Square avatar, 256 px.

string
capabilities

Capabilities enabled for this agent with per-agent configuration. Capabilities add tools and system prompt modifications.

Array<object>

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
config

Per-agent configuration for this capability (capability-specific)

ref
required

Reference to the capability ID

string
communication

How the agent talks to people. direct (default): its replies are what it writes. explicit: what it writes is private working notes, and people see only the messages it sends with send_message. Applies on every surface: web chat, API, Slack, A2A, AG-UI, MCP.

string
Allowed values: direct explicit
completion_check

When a turn about to finish is checked for whether it did what was asked, and continued automatically when it did not. unattended (default): sessions started by triggers and schedules, where no person is watching. always: chat too. off: never.

string
Allowed values: off unattended always
created_at
required

Timestamp when the agent was created.

string format: date-time
default_model_id

Default LLM model ID for this agent. Can be overridden at the session level.

string | null
deleted_at

Timestamp when the agent was deleted.

string | null format: date-time
description

Human-readable description of what the agent does.

string | null
display_name

Human-readable display name shown in UI (e.g. “Customer Support Agent”). Falls back to name when absent.

string | null
exposed

Whether any endpoint on this agent is currently live. Derived from the endpoint rows on read and never stored: a stored flag would be a second writer for state the endpoints already own.

boolean
exposures_suspended

Incident switch: when true, no endpoint on this agent accepts traffic (EVE-1007). Distinct from archiving — it leaves per-endpoint status untouched so clearing it restores exactly the previously live set.

boolean
forked_from_agent_id

Source agent for a forked agent.

string | null
harness_id
required

Harness that supplies the base execution environment for this agent.

string
id
required

External identifier (agent_<32-hex>). Shown as “id” in API. Client-supplied or auto-generated.

string
initial_files

Starter files copied into each new session for this agent.

Array<object>

Starter file copied into a new session from an agent or harness.

object
content
required

File content: plain text or base64-encoded binary.

string
encoding

Content encoding: text or base64.

string
is_readonly

Prevent session-side edits or deletes when true.

boolean
path
required

Absolute path within the session workspace. /workspace prefix is accepted.

string
intro_markdown

Optional Markdown intro rendered as an intro box at the top of a fresh Platform Chat thread. Images are allowed. Wins over the harness intro. Hidden once the user inputs.

string | null
is_built_in

Built-in agents (Platform Chat) are provisioned by the platform and are read-only: they cannot be modified or deleted via the API. Copy one to get an editable version.

boolean
localizations

Locale-keyed display overlays; identifiers and execution instructions are unchanged.

object
key
additional properties

Display-only translations shared by portable agent files and platform resources. Addresses, tool identifiers and execution instructions never use these values.

object
description

Localized description (1–2000 characters when set).

string | null
display_name

Localized display name (1–255 characters when set).

string | null
max_iterations

Maximum number of LLM iterations per turn for this agent.

integer | null
max_output_tokens

Ceiling on output tokens per model response, sent to the provider as max_tokens. Unset keeps the provider default. Clamped to the model’s output limit when known. Lower it when a provider rejects calls because the balance can only afford fewer tokens.

integer | null format: int32
>= 1
mcpServers

Remote MCP servers scoped to this agent and inherited by its sessions.

object
key
additional properties

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
actsAs

Identity whose grant this attachment requests.

string
Allowed values: none service user user_or_service
args

Arguments passed to the stdio command.

Array<string>
auth_mode

Authentication mode used when executing tools from this scoped server.

string
Allowed values: none api_key oauth
command

Executable to spawn for a stdio transport server.

string | null
connectInChat

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).

string
Allowed values: ask never
deferred

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).

boolean
description

Searchable server context supplied by its attachment or catalog. It is metadata, not an instruction or a credential.

string | null
elicitation_policy

Which elicitation modes this server may use (url by default).

string
Allowed values: url url_and_form none
env

Environment variables set for the stdio command.

object
key
additional properties
string
headers

Additional HTTP headers sent on MCP requests (HTTP transport only).

object
key
additional properties
string
oauth_provider_id

Provider id used to resolve a user-scoped bearer token.

string | null
protocol_mode

Protocol-era adoption policy for the MCP client (auto negotiates).

string
Allowed values: auto 2025-03-26 2025-06-18 2026-07-28
tool_discovery

Whether to discover tool definitions live from this server.

boolean
tool_labels

Risk labels for this server’s tools, by the tool’s own name: read_only never asks for approval in the normal mode, changes always asks. They win over the tool’s annotations and over a catalog preset’s saved labels. Honored on harness, agent and person-owned servers; dropped from session-scoped servers.

object
key
additional properties

A person’s saved risk label for one MCP tool.

Decision (2026-10-10): a person’s label always wins over the tool’s own annotations, because a remote server describes itself and a person who owns the integration knows better. read_only also clears open_world, since tool approval treats an outward-reaching tool like a destructive one; without that a read-only MCP tool would still ask every time.

string
Allowed values: read_only changes
tool_timeout_ms

How long one tools/call to this server may take, in milliseconds. Unset means [MCP_TOOL_TIMEOUT_DEFAULT_MS] (60 s); accepted range is [MCP_TOOL_TIMEOUT_MIN_MS]..=[MCP_TOOL_TIMEOUT_MAX_MS]. timeout is accepted as an alias, matching common mcpServers config files.

integer | null format: int64
type

MCP transport type. Only remote HTTP is supported today.

string
Allowed values: http stdio
url

URL of the remote MCP server endpoint. Required for HTTP transport; empty/ignored for stdio.

string
use
One of:

Organization catalog preset that supplies transport and authentication policy.

string
model_role
One of:

Organization model the agent follows instead of default_model_id. research uses the organization research model.

string
Allowed values: research
name
required

Name, unique per org (e.g. “customer-support”).

string
network_access
One of:

Network access list controlling which hosts/URLs agent sessions can reach. Merged with harness and session layers (allowed: intersect, blocked: union).

object
allowed

Allowed host patterns. If non-empty, only matching URLs are permitted. An empty list means “no restriction from this layer” (inherit parent).

Array<string>
blocked

Blocked host patterns. Always denied, even if matched by allowed.

Array<string>
owner_agent_id

Agent this one was created as part of, shown as “Created here” on that agent’s Agents tab and bundled into its export.

string | null
parallel_tool_calls

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).

boolean | null
root_agent_id

Root agent lineage identifier for grouping fork families.

string | null
sandbox_policy
One of:

Policy for selecting the primary Sandbox Template for new Sessions.

object
default
required

Template binding inherited when Session creation does not choose one.

string
mode
One of:

Who may choose the primary Sandbox for a Session. Older rows omit this field; one template then means fixed, while several mean selectable.

string
Allowed values: fixed selectable configurable
templates

Template snapshots addressable by binding name at Session creation.

object
key
additional properties

Desired Sandbox configuration authored by a human or application.

Containment and durability may be omitted when the target has exactly one honest answer. Resolution fills those fields before the specification is pinned to a Session.

object
bootstrap

Reproducible commands run when physical compute is initialized.

object
commands

Ordered commands replayed when creating or recovering physical compute.

Array<string>
containment
One of:

Requested isolation policy; resolution supplies an honest target default.

object
escalation

Whether the runtime may widen containment after Session creation.

string
Allowed values: never approval auto
filesystem

Filesystem mutation boundary for command execution.

object
writable_roots

Absolute roots the runtime may mutate; empty means provider default.

Array<string>
level
required

Isolation mechanism the provider must supply.

string
Allowed values: none native isolated
network
One of:
object
mode
required
string
Allowed values: deny
durability
One of:

Requested recovery guarantee; resolution supplies a target default.

string
Allowed values: checkpointed provider_snapshot none
lifecycle

Idle lifecycle policy controlled by Everruns.

object
delete_after_seconds

How long a paused Sandbox is kept, counted from its last activity, before Everruns deletes it with its files. The Session stays; its next Sandbox call provisions a fresh one. null keeps paused Sandboxes until their Session is deleted.

integer | null format: int64
idle_action

Action Everruns requests after the idle interval.

string
Allowed values: checkpoint_and_stop stop keep_running delete
idle_after_seconds

Inactivity interval before applying idle_action.

integer format: int64
target
required

Provider-neutral target plus its concrete adapter binding.

object
connection_id

Credential/transport binding for a registered machine target.

string | null
credential

Provider credential source. User and Agent bindings are resolved to an exact virtual user when the Session starts; organization bindings also pin the exact connection.

object
connection_id

Exact connection for organization grants, which may have several accounts for one provider.

string | null format: uuid
source
required

Identity scope from which the provider credential is resolved.

string
Allowed values: none session_user agent organization
virtual_user_id

Exact virtual-user owner for user, Agent, and organization grants.

string | null format: uuid
kind
required

Provider-neutral target class.

string
Allowed values: host machine vfs container managed
options

Provider-owned, non-secret configuration. Credentials are references, never values in this object.

object
provider

Concrete adapter for target kinds with more than one implementation.

string | null
template_revision_id

Immutable Sandbox Template revision this specification was copied from. The specification remains complete so Agent snapshots are portable and later template revisions cannot change an existing snapshot.

string | null
service_virtual_user_id

Org-scoped service account used when a tool acts as the agent.

string | null
short_description

Optional one-line description in simplified Markdown, shown below the chat title once the intro is hidden. Wins over the harness value.

string | null
starters

Conversation starters for a fresh Platform Chat thread. Win over the harness starters when non-empty.

Array<object>

A conversation starter shown on a fresh Platform Chat thread. Selecting one inserts its text into the composer. icon reuses the harness icon name set (HarnessIcon); unknown names fall back to the default glyph.

object
icon

Optional icon name from the harness icon set.

string | null
text
required

Prompt text inserted into the composer when selected.

string
status
required

Current lifecycle status of the agent.

string
Allowed values: active archived deleted
system_prompt
required

System prompt that defines the agent’s behavior. Sent as the first message in every conversation.

string
tags

Tags for organizing and filtering agents.

Array<string>
tools

Client-side tools registered for this agent. These tools are executed by the client, not the server.

Array
One of:

Built-in tool - executed by the worker via ToolRegistry

object
category

Category for tool_search namespace grouping (from parent capability)

string | null
deferrable

Whether this tool’s schema can be deferred via tool_search

string
Allowed values: never automatic always
description
required

Tool description for LLM

string
display_name

Human-readable display name for UI rendering (e.g., “Get Current Time” for get_current_time)

string | null
full_parameters

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.

hints

Semantic hints describing the tool’s behavioral properties

object
capability_description

Declared capability description for source-aware tool discovery. Never populate this with system prompts, conversation state or secrets.

string | null
capability_id

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.

string | null
capability_name

Human-readable capability name snapshot for reporting.

string | null
concurrency_class

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.

string | null
cpu_bound

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).

boolean | null
destructive

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).

boolean | null
idempotent

Calling the tool repeatedly with the same arguments produces the same effect. Safe to retry on transient failures.

boolean | null
long_running

Tool may take significant time to complete (> ~5s typical). Useful for clients to show progress indicators and set timeouts.

boolean | null
metadata

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.

narration_noun

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”.

string | null
open_world

Tool interacts with external entities beyond the local system (network calls, third-party APIs, cloud services).

boolean | null
persist_output

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.

boolean | null
readonly

Tool does not modify any state (read-only queries, lookups). When true: safe to call speculatively, result can be cached.

boolean | null
requires_secrets

Tool requires API keys, credentials, or other secrets to function. Useful for UI to show connection prompts and for LLMs to anticipate authentication failures.

boolean | null
side_effect_class
One of:

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.

string
Allowed values: Pure Idempotent AtMostOnce
stays_direct

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.

boolean | null
supports_background

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.

boolean | null
name
required

Tool name (used by LLM and for registry lookup)

string
parameters
required

JSON schema for tool parameters

policy

Tool policy (auto or requires_approval)

string
Allowed values: auto requires_approval client_side
type
required
string
Allowed values: builtin
updated_at
required

Timestamp when the agent was last updated.

string format: date-time
usage
One of:

Cumulative token usage across all sessions for this agent.

object
actual_cost_usd

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 | null format: double
cache_creation_tokens

Number of tokens written to cache, disjoint from input_tokens

integer | null format: int32
cache_read_tokens

Number of tokens read from cache (reduces cost), disjoint from input_tokens

integer | null format: int32
effective_cost_usd

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).

number | null format: double
estimated_cost_usd

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 | null format: double
input_tokens
required

Number of non-cached prompt tokens (cached reads/writes are tracked separately; see the disjoint bucket convention on the struct)

integer format: int32
output_tokens
required

Number of output/completion tokens

integer format: int32
allowed_actions

State-aware hypermedia actions the caller can take on this resource next (e.g. cancel, events, update). Omitted from the wire shape when empty so resources that haven’t opted into the convention don’t grow their payloads.

Array<object>

Agent-actionable link describing a follow-up the caller can take. Used in two contexts:

  • Error recovery — ErrorResponse.allowed_actions carries rels like retry, retry-later, unarchive, get-existing so the agent knows the right next call after a 4xx/429.
  • Entity hypermedia — WithUrls<T>.allowed_actions carries state-aware rels like cancel, events, self, update on the entity itself so the agent can follow links instead of reconstructing routes from prose.

The shape is intentionally identical across both contexts; the closed rel vocabulary distinguishes them.

object
hint

Short, agent-readable hint (e.g. “Shorten ‘name’ to <= 200 chars.”, “Cancel the active turn for this session.”).

string | null
href

Absolute (preferred) or relative URL the caller may invoke directly. Always present on entity hypermedia actions (WithUrls<T>.allowed_actions); optional on error-recovery actions (ErrorResponse.allowed_actions) where the matching operation_id is enough and the URI is implicit from the failed call.

string | null
method

HTTP method to use against href. Required for entity hypermedia actions; usually omitted on error-recovery actions where the same operation is retried with its original method.

string | null
operation_id

OpenAPI operationId the caller should invoke. Lets an MCP client resolve the call without parsing href.

string | null
rel
required

Link relation describing the action. Examples: self, cancel, pause, resume, events, retry, retry-later, unarchive, get-existing, delete, update.

string
schema_ref

OpenAPI $ref to the request-body schema, when the action takes one (e.g. #/components/schemas/UpdateSessionRequest). Lets a tool-calling agent fetch the input shape without scanning the whole spec.

string | null
self_url
required

Full API endpoint URL for this resource.

string
ui_link
required

Alias for view_url, used by command and MCP outputs.

string
view_url
required

Full UI URL for viewing this resource.

string

Example

{
"archived_at": "2026-05-26T00:00:00Z",
"avatar": {
"circle_url": "/v1/avatars/avatar_01933b5a000070008000000000000001/circle-256.png",
"id": "avatar_01933b5a000070008000000000000001",
"sizes": [
32,
64,
128,
256,
512
],
"url": "/v1/avatars/avatar_01933b5a000070008000000000000001/square-256.png"
},
"communication": "direct",
"completion_check": "off",
"created_at": "2026-04-01T10:00:00Z",
"default_model_id": "model_01933b5a00007000800000000000001",
"deleted_at": "2026-05-26T00:00:00Z",
"description": "Handles refund and shipping questions; escalates billing disputes.",
"display_name": "Customer Support Agent",
"forked_from_agent_id": "agent_01933b5a00007000800000000000001",
"harness_id": "harness_01933b5a00007000800000000000001",
"id": "agent_01933b5a000070008000000000000001",
"intro_markdown": "Hey, I'm Ava. Ask me anything about your account.",
"is_built_in": false,
"max_iterations": 50,
"max_output_tokens": 4096,
"mcpServers": {
"additionalProperty": {
"actsAs": "none",
"auth_mode": "none",
"connectInChat": "ask",
"elicitation_policy": "url",
"protocol_mode": "auto",
"tool_labels": {
"additionalProperty": "read_only"
},
"type": "http",
"use": "catalog:linear"
}
},
"model_role": "research",
"name": "customer-support",
"network_access": {
"allowed": [
"*.example.com",
"https://api.acme.com/"
],
"blocked": [
"169.254.169.254"
]
},
"owner_agent_id": "agent_01933b5a00007000800000000000001",
"parallel_tool_calls": true,
"root_agent_id": "agent_01933b5a00007000800000000000001",
"sandbox_policy": {
"default": "primary",
"mode": "fixed",
"templates": {
"additionalProperty": {
"containment": {
"escalation": "never",
"level": "none",
"network": {
"mode": "deny"
}
},
"durability": "checkpointed",
"lifecycle": {
"delete_after_seconds": 259200,
"idle_action": "checkpoint_and_stop",
"idle_after_seconds": 300
},
"target": {
"connection_id": "conn_01933b5a000070008000000000000001",
"credential": {
"connection_id": "00000000-0000-0000-0000-000000000002",
"source": "none",
"virtual_user_id": "00000000-0000-0000-0000-000000000001"
},
"kind": "host",
"provider": "daytona"
}
}
}
},
"short_description": "Answers account questions in seconds.",
"starters": [
{
"icon": "zap",
"text": "Triage the newest P1"
}
],
"status": "active",
"system_prompt": "You are a friendly customer support agent for Acme Corp. Verify orders before issuing refunds. Escalate any billing disputes to a human.",
"tags": [
"support",
"production"
],
"tools": [
{
"deferrable": "never",
"hints": {
"side_effect_class": "Pure"
},
"policy": "auto",
"type": "builtin"
}
],
"updated_at": "2026-05-20T14:00:00Z",
"allowed_actions": [
{
"method": "POST"
}
]
}
201Agent imported successfully

Agent imported successfully

Media typeapplication/json

Wrapper that adds API and UI links to a serialized resource.

Uses self_url (not url) for the API link to avoid collision with resources that already have a url field (e.g. McpServer). The allowed_actions array carries state-aware hypermedia links — empty (and omitted from the wire shape) until the underlying resource opts into the convention by overriding ResourceUrlable::allowed_actions.

object
archived_at

Timestamp when the agent was archived.

string | null format: date-time
avatar
One of:

Avatar shown wherever the agent appears: the UI, the A2A Agent Card and its Slack app. Set with PUT /v1/agents/{agent_id}/avatar.

object
circle_url
required

Circular avatar (transparent corners), 256 px.

string
id
required

Prefixed public identifier. See ID Schema.

string
sizes
required

Edge lengths, in pixels, available for both shapes.

Array<integer>
url
required

Square avatar, 256 px.

string
capabilities

Capabilities enabled for this agent with per-agent configuration. Capabilities add tools and system prompt modifications.

Array<object>

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
config

Per-agent configuration for this capability (capability-specific)

ref
required

Reference to the capability ID

string
communication

How the agent talks to people. direct (default): its replies are what it writes. explicit: what it writes is private working notes, and people see only the messages it sends with send_message. Applies on every surface: web chat, API, Slack, A2A, AG-UI, MCP.

string
Allowed values: direct explicit
completion_check

When a turn about to finish is checked for whether it did what was asked, and continued automatically when it did not. unattended (default): sessions started by triggers and schedules, where no person is watching. always: chat too. off: never.

string
Allowed values: off unattended always
created_at
required

Timestamp when the agent was created.

string format: date-time
default_model_id

Default LLM model ID for this agent. Can be overridden at the session level.

string | null
deleted_at

Timestamp when the agent was deleted.

string | null format: date-time
description

Human-readable description of what the agent does.

string | null
display_name

Human-readable display name shown in UI (e.g. “Customer Support Agent”). Falls back to name when absent.

string | null
exposed

Whether any endpoint on this agent is currently live. Derived from the endpoint rows on read and never stored: a stored flag would be a second writer for state the endpoints already own.

boolean
exposures_suspended

Incident switch: when true, no endpoint on this agent accepts traffic (EVE-1007). Distinct from archiving — it leaves per-endpoint status untouched so clearing it restores exactly the previously live set.

boolean
forked_from_agent_id

Source agent for a forked agent.

string | null
harness_id
required

Harness that supplies the base execution environment for this agent.

string
id
required

External identifier (agent_<32-hex>). Shown as “id” in API. Client-supplied or auto-generated.

string
initial_files

Starter files copied into each new session for this agent.

Array<object>

Starter file copied into a new session from an agent or harness.

object
content
required

File content: plain text or base64-encoded binary.

string
encoding

Content encoding: text or base64.

string
is_readonly

Prevent session-side edits or deletes when true.

boolean
path
required

Absolute path within the session workspace. /workspace prefix is accepted.

string
intro_markdown

Optional Markdown intro rendered as an intro box at the top of a fresh Platform Chat thread. Images are allowed. Wins over the harness intro. Hidden once the user inputs.

string | null
is_built_in

Built-in agents (Platform Chat) are provisioned by the platform and are read-only: they cannot be modified or deleted via the API. Copy one to get an editable version.

boolean
localizations

Locale-keyed display overlays; identifiers and execution instructions are unchanged.

object
key
additional properties

Display-only translations shared by portable agent files and platform resources. Addresses, tool identifiers and execution instructions never use these values.

object
description

Localized description (1–2000 characters when set).

string | null
display_name

Localized display name (1–255 characters when set).

string | null
max_iterations

Maximum number of LLM iterations per turn for this agent.

integer | null
max_output_tokens

Ceiling on output tokens per model response, sent to the provider as max_tokens. Unset keeps the provider default. Clamped to the model’s output limit when known. Lower it when a provider rejects calls because the balance can only afford fewer tokens.

integer | null format: int32
>= 1
mcpServers

Remote MCP servers scoped to this agent and inherited by its sessions.

object
key
additional properties

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
actsAs

Identity whose grant this attachment requests.

string
Allowed values: none service user user_or_service
args

Arguments passed to the stdio command.

Array<string>
auth_mode

Authentication mode used when executing tools from this scoped server.

string
Allowed values: none api_key oauth
command

Executable to spawn for a stdio transport server.

string | null
connectInChat

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).

string
Allowed values: ask never
deferred

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).

boolean
description

Searchable server context supplied by its attachment or catalog. It is metadata, not an instruction or a credential.

string | null
elicitation_policy

Which elicitation modes this server may use (url by default).

string
Allowed values: url url_and_form none
env

Environment variables set for the stdio command.

object
key
additional properties
string
headers

Additional HTTP headers sent on MCP requests (HTTP transport only).

object
key
additional properties
string
oauth_provider_id

Provider id used to resolve a user-scoped bearer token.

string | null
protocol_mode

Protocol-era adoption policy for the MCP client (auto negotiates).

string
Allowed values: auto 2025-03-26 2025-06-18 2026-07-28
tool_discovery

Whether to discover tool definitions live from this server.

boolean
tool_labels

Risk labels for this server’s tools, by the tool’s own name: read_only never asks for approval in the normal mode, changes always asks. They win over the tool’s annotations and over a catalog preset’s saved labels. Honored on harness, agent and person-owned servers; dropped from session-scoped servers.

object
key
additional properties

A person’s saved risk label for one MCP tool.

Decision (2026-10-10): a person’s label always wins over the tool’s own annotations, because a remote server describes itself and a person who owns the integration knows better. read_only also clears open_world, since tool approval treats an outward-reaching tool like a destructive one; without that a read-only MCP tool would still ask every time.

string
Allowed values: read_only changes
tool_timeout_ms

How long one tools/call to this server may take, in milliseconds. Unset means [MCP_TOOL_TIMEOUT_DEFAULT_MS] (60 s); accepted range is [MCP_TOOL_TIMEOUT_MIN_MS]..=[MCP_TOOL_TIMEOUT_MAX_MS]. timeout is accepted as an alias, matching common mcpServers config files.

integer | null format: int64
type

MCP transport type. Only remote HTTP is supported today.

string
Allowed values: http stdio
url

URL of the remote MCP server endpoint. Required for HTTP transport; empty/ignored for stdio.

string
use
One of:

Organization catalog preset that supplies transport and authentication policy.

string
model_role
One of:

Organization model the agent follows instead of default_model_id. research uses the organization research model.

string
Allowed values: research
name
required

Name, unique per org (e.g. “customer-support”).

string
network_access
One of:

Network access list controlling which hosts/URLs agent sessions can reach. Merged with harness and session layers (allowed: intersect, blocked: union).

object
allowed

Allowed host patterns. If non-empty, only matching URLs are permitted. An empty list means “no restriction from this layer” (inherit parent).

Array<string>
blocked

Blocked host patterns. Always denied, even if matched by allowed.

Array<string>
owner_agent_id

Agent this one was created as part of, shown as “Created here” on that agent’s Agents tab and bundled into its export.

string | null
parallel_tool_calls

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).

boolean | null
root_agent_id

Root agent lineage identifier for grouping fork families.

string | null
sandbox_policy
One of:

Policy for selecting the primary Sandbox Template for new Sessions.

object
default
required

Template binding inherited when Session creation does not choose one.

string
mode
One of:

Who may choose the primary Sandbox for a Session. Older rows omit this field; one template then means fixed, while several mean selectable.

string
Allowed values: fixed selectable configurable
templates

Template snapshots addressable by binding name at Session creation.

object
key
additional properties

Desired Sandbox configuration authored by a human or application.

Containment and durability may be omitted when the target has exactly one honest answer. Resolution fills those fields before the specification is pinned to a Session.

object
bootstrap

Reproducible commands run when physical compute is initialized.

object
commands

Ordered commands replayed when creating or recovering physical compute.

Array<string>
containment
One of:

Requested isolation policy; resolution supplies an honest target default.

object
escalation

Whether the runtime may widen containment after Session creation.

string
Allowed values: never approval auto
filesystem

Filesystem mutation boundary for command execution.

object
writable_roots

Absolute roots the runtime may mutate; empty means provider default.

Array<string>
level
required

Isolation mechanism the provider must supply.

string
Allowed values: none native isolated
network
One of:
object
mode
required
string
Allowed values: deny
durability
One of:

Requested recovery guarantee; resolution supplies a target default.

string
Allowed values: checkpointed provider_snapshot none
lifecycle

Idle lifecycle policy controlled by Everruns.

object
delete_after_seconds

How long a paused Sandbox is kept, counted from its last activity, before Everruns deletes it with its files. The Session stays; its next Sandbox call provisions a fresh one. null keeps paused Sandboxes until their Session is deleted.

integer | null format: int64
idle_action

Action Everruns requests after the idle interval.

string
Allowed values: checkpoint_and_stop stop keep_running delete
idle_after_seconds

Inactivity interval before applying idle_action.

integer format: int64
target
required

Provider-neutral target plus its concrete adapter binding.

object
connection_id

Credential/transport binding for a registered machine target.

string | null
credential

Provider credential source. User and Agent bindings are resolved to an exact virtual user when the Session starts; organization bindings also pin the exact connection.

object
connection_id

Exact connection for organization grants, which may have several accounts for one provider.

string | null format: uuid
source
required

Identity scope from which the provider credential is resolved.

string
Allowed values: none session_user agent organization
virtual_user_id

Exact virtual-user owner for user, Agent, and organization grants.

string | null format: uuid
kind
required

Provider-neutral target class.

string
Allowed values: host machine vfs container managed
options

Provider-owned, non-secret configuration. Credentials are references, never values in this object.

object
provider

Concrete adapter for target kinds with more than one implementation.

string | null
template_revision_id

Immutable Sandbox Template revision this specification was copied from. The specification remains complete so Agent snapshots are portable and later template revisions cannot change an existing snapshot.

string | null
service_virtual_user_id

Org-scoped service account used when a tool acts as the agent.

string | null
short_description

Optional one-line description in simplified Markdown, shown below the chat title once the intro is hidden. Wins over the harness value.

string | null
starters

Conversation starters for a fresh Platform Chat thread. Win over the harness starters when non-empty.

Array<object>

A conversation starter shown on a fresh Platform Chat thread. Selecting one inserts its text into the composer. icon reuses the harness icon name set (HarnessIcon); unknown names fall back to the default glyph.

object
icon

Optional icon name from the harness icon set.

string | null
text
required

Prompt text inserted into the composer when selected.

string
status
required

Current lifecycle status of the agent.

string
Allowed values: active archived deleted
system_prompt
required

System prompt that defines the agent’s behavior. Sent as the first message in every conversation.

string
tags

Tags for organizing and filtering agents.

Array<string>
tools

Client-side tools registered for this agent. These tools are executed by the client, not the server.

Array
One of:

Built-in tool - executed by the worker via ToolRegistry

object
category

Category for tool_search namespace grouping (from parent capability)

string | null
deferrable

Whether this tool’s schema can be deferred via tool_search

string
Allowed values: never automatic always
description
required

Tool description for LLM

string
display_name

Human-readable display name for UI rendering (e.g., “Get Current Time” for get_current_time)

string | null
full_parameters

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.

hints

Semantic hints describing the tool’s behavioral properties

object
capability_description

Declared capability description for source-aware tool discovery. Never populate this with system prompts, conversation state or secrets.

string | null
capability_id

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.

string | null
capability_name

Human-readable capability name snapshot for reporting.

string | null
concurrency_class

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.

string | null
cpu_bound

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).

boolean | null
destructive

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).

boolean | null
idempotent

Calling the tool repeatedly with the same arguments produces the same effect. Safe to retry on transient failures.

boolean | null
long_running

Tool may take significant time to complete (> ~5s typical). Useful for clients to show progress indicators and set timeouts.

boolean | null
metadata

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.

narration_noun

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”.

string | null
open_world

Tool interacts with external entities beyond the local system (network calls, third-party APIs, cloud services).

boolean | null
persist_output

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.

boolean | null
readonly

Tool does not modify any state (read-only queries, lookups). When true: safe to call speculatively, result can be cached.

boolean | null
requires_secrets

Tool requires API keys, credentials, or other secrets to function. Useful for UI to show connection prompts and for LLMs to anticipate authentication failures.

boolean | null
side_effect_class
One of:

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.

string
Allowed values: Pure Idempotent AtMostOnce
stays_direct

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.

boolean | null
supports_background

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.

boolean | null
name
required

Tool name (used by LLM and for registry lookup)

string
parameters
required

JSON schema for tool parameters

policy

Tool policy (auto or requires_approval)

string
Allowed values: auto requires_approval client_side
type
required
string
Allowed values: builtin
updated_at
required

Timestamp when the agent was last updated.

string format: date-time
usage
One of:

Cumulative token usage across all sessions for this agent.

object
actual_cost_usd

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 | null format: double
cache_creation_tokens

Number of tokens written to cache, disjoint from input_tokens

integer | null format: int32
cache_read_tokens

Number of tokens read from cache (reduces cost), disjoint from input_tokens

integer | null format: int32
effective_cost_usd

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).

number | null format: double
estimated_cost_usd

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 | null format: double
input_tokens
required

Number of non-cached prompt tokens (cached reads/writes are tracked separately; see the disjoint bucket convention on the struct)

integer format: int32
output_tokens
required

Number of output/completion tokens

integer format: int32
allowed_actions

State-aware hypermedia actions the caller can take on this resource next (e.g. cancel, events, update). Omitted from the wire shape when empty so resources that haven’t opted into the convention don’t grow their payloads.

Array<object>

Agent-actionable link describing a follow-up the caller can take. Used in two contexts:

  • Error recovery — ErrorResponse.allowed_actions carries rels like retry, retry-later, unarchive, get-existing so the agent knows the right next call after a 4xx/429.
  • Entity hypermedia — WithUrls<T>.allowed_actions carries state-aware rels like cancel, events, self, update on the entity itself so the agent can follow links instead of reconstructing routes from prose.

The shape is intentionally identical across both contexts; the closed rel vocabulary distinguishes them.

object
hint

Short, agent-readable hint (e.g. “Shorten ‘name’ to <= 200 chars.”, “Cancel the active turn for this session.”).

string | null
href

Absolute (preferred) or relative URL the caller may invoke directly. Always present on entity hypermedia actions (WithUrls<T>.allowed_actions); optional on error-recovery actions (ErrorResponse.allowed_actions) where the matching operation_id is enough and the URI is implicit from the failed call.

string | null
method

HTTP method to use against href. Required for entity hypermedia actions; usually omitted on error-recovery actions where the same operation is retried with its original method.

string | null
operation_id

OpenAPI operationId the caller should invoke. Lets an MCP client resolve the call without parsing href.

string | null
rel
required

Link relation describing the action. Examples: self, cancel, pause, resume, events, retry, retry-later, unarchive, get-existing, delete, update.

string
schema_ref

OpenAPI $ref to the request-body schema, when the action takes one (e.g. #/components/schemas/UpdateSessionRequest). Lets a tool-calling agent fetch the input shape without scanning the whole spec.

string | null
self_url
required

Full API endpoint URL for this resource.

string
ui_link
required

Alias for view_url, used by command and MCP outputs.

string
view_url
required

Full UI URL for viewing this resource.

string

Example

{
"archived_at": "2026-05-26T00:00:00Z",
"avatar": {
"circle_url": "/v1/avatars/avatar_01933b5a000070008000000000000001/circle-256.png",
"id": "avatar_01933b5a000070008000000000000001",
"sizes": [
32,
64,
128,
256,
512
],
"url": "/v1/avatars/avatar_01933b5a000070008000000000000001/square-256.png"
},
"communication": "direct",
"completion_check": "off",
"created_at": "2026-04-01T10:00:00Z",
"default_model_id": "model_01933b5a00007000800000000000001",
"deleted_at": "2026-05-26T00:00:00Z",
"description": "Handles refund and shipping questions; escalates billing disputes.",
"display_name": "Customer Support Agent",
"forked_from_agent_id": "agent_01933b5a00007000800000000000001",
"harness_id": "harness_01933b5a00007000800000000000001",
"id": "agent_01933b5a000070008000000000000001",
"intro_markdown": "Hey, I'm Ava. Ask me anything about your account.",
"is_built_in": false,
"max_iterations": 50,
"max_output_tokens": 4096,
"mcpServers": {
"additionalProperty": {
"actsAs": "none",
"auth_mode": "none",
"connectInChat": "ask",
"elicitation_policy": "url",
"protocol_mode": "auto",
"tool_labels": {
"additionalProperty": "read_only"
},
"type": "http",
"use": "catalog:linear"
}
},
"model_role": "research",
"name": "customer-support",
"network_access": {
"allowed": [
"*.example.com",
"https://api.acme.com/"
],
"blocked": [
"169.254.169.254"
]
},
"owner_agent_id": "agent_01933b5a00007000800000000000001",
"parallel_tool_calls": true,
"root_agent_id": "agent_01933b5a00007000800000000000001",
"sandbox_policy": {
"default": "primary",
"mode": "fixed",
"templates": {
"additionalProperty": {
"containment": {
"escalation": "never",
"level": "none",
"network": {
"mode": "deny"
}
},
"durability": "checkpointed",
"lifecycle": {
"delete_after_seconds": 259200,
"idle_action": "checkpoint_and_stop",
"idle_after_seconds": 300
},
"target": {
"connection_id": "conn_01933b5a000070008000000000000001",
"credential": {
"connection_id": "00000000-0000-0000-0000-000000000002",
"source": "none",
"virtual_user_id": "00000000-0000-0000-0000-000000000001"
},
"kind": "host",
"provider": "daytona"
}
}
}
},
"short_description": "Answers account questions in seconds.",
"starters": [
{
"icon": "zap",
"text": "Triage the newest P1"
}
],
"status": "active",
"system_prompt": "You are a friendly customer support agent for Acme Corp. Verify orders before issuing refunds. Escalate any billing disputes to a human.",
"tags": [
"support",
"production"
],
"tools": [
{
"deferrable": "never",
"hints": {
"side_effect_class": "Pure"
},
"policy": "auto",
"type": "builtin"
}
],
"updated_at": "2026-05-20T14:00:00Z",
"allowed_actions": [
{
"method": "POST"
}
]
}
400Invalid format or input exceeds limits

Invalid format or input exceeds limits

Media typeapplication/json

Standard error response.

Wire shape is RFC 9457 Problem Details: every error response includes title and status, and may include detail, code, allowed_actions, retry_after_seconds, instance, and type. The content type is rewritten to application/problem+json with the application/problem+json content type.

object
allowed_actions

Recovery actions the caller can take next.

Array<object>

Agent-actionable link describing a follow-up the caller can take. Used in two contexts:

  • Error recovery — ErrorResponse.allowed_actions carries rels like retry, retry-later, unarchive, get-existing so the agent knows the right next call after a 4xx/429.
  • Entity hypermedia — WithUrls<T>.allowed_actions carries state-aware rels like cancel, events, self, update on the entity itself so the agent can follow links instead of reconstructing routes from prose.

The shape is intentionally identical across both contexts; the closed rel vocabulary distinguishes them.

object
hint

Short, agent-readable hint (e.g. “Shorten ‘name’ to <= 200 chars.”, “Cancel the active turn for this session.”).

string | null
href

Absolute (preferred) or relative URL the caller may invoke directly. Always present on entity hypermedia actions (WithUrls<T>.allowed_actions); optional on error-recovery actions (ErrorResponse.allowed_actions) where the matching operation_id is enough and the URI is implicit from the failed call.

string | null
method

HTTP method to use against href. Required for entity hypermedia actions; usually omitted on error-recovery actions where the same operation is retried with its original method.

string | null
operation_id

OpenAPI operationId the caller should invoke. Lets an MCP client resolve the call without parsing href.

string | null
rel
required

Link relation describing the action. Examples: self, cancel, pause, resume, events, retry, retry-later, unarchive, get-existing, delete, update.

string
schema_ref

OpenAPI $ref to the request-body schema, when the action takes one (e.g. #/components/schemas/UpdateSessionRequest). Lets a tool-calling agent fetch the input shape without scanning the whole spec.

string | null
code

Stable, machine-readable error code (snake_case).

string | null
detail

Human-readable explanation specific to this occurrence.

string | null
instance

Request URI for this occurrence.

string | null
retry_after_seconds

Seconds the caller should wait before retrying (429 / transient 503).

integer | null format: int32
status
required

HTTP status code; mirrors the response status line.

integer format: int32
title
required

Short, human-readable summary of the problem (e.g. “Not Found”).

string
type

RFC 9457 problem type URI. Optional; identifies the problem class.

string | null

Example

{
"allowed_actions": [
{
"method": "POST"
}
],
"code": "session_not_found",
"detail": "Session session_01933b5a000070008000000000000001 not found in org org_01933b5a000070008000000000000001.",
"instance": "/v1/sessions/session_01933b5a000070008000000000000001",
"retry_after_seconds": 30,
"status": 404,
"title": "Session not found",
"type": "https://everruns.com/docs/errors/session_not_found"
}
403High-risk capabilities require admin role

High-risk capabilities require admin role

Media typeapplication/json

Standard error response.

Wire shape is RFC 9457 Problem Details: every error response includes title and status, and may include detail, code, allowed_actions, retry_after_seconds, instance, and type. The content type is rewritten to application/problem+json with the application/problem+json content type.

object
allowed_actions

Recovery actions the caller can take next.

Array<object>

Agent-actionable link describing a follow-up the caller can take. Used in two contexts:

  • Error recovery — ErrorResponse.allowed_actions carries rels like retry, retry-later, unarchive, get-existing so the agent knows the right next call after a 4xx/429.
  • Entity hypermedia — WithUrls<T>.allowed_actions carries state-aware rels like cancel, events, self, update on the entity itself so the agent can follow links instead of reconstructing routes from prose.

The shape is intentionally identical across both contexts; the closed rel vocabulary distinguishes them.

object
hint

Short, agent-readable hint (e.g. “Shorten ‘name’ to <= 200 chars.”, “Cancel the active turn for this session.”).

string | null
href

Absolute (preferred) or relative URL the caller may invoke directly. Always present on entity hypermedia actions (WithUrls<T>.allowed_actions); optional on error-recovery actions (ErrorResponse.allowed_actions) where the matching operation_id is enough and the URI is implicit from the failed call.

string | null
method

HTTP method to use against href. Required for entity hypermedia actions; usually omitted on error-recovery actions where the same operation is retried with its original method.

string | null
operation_id

OpenAPI operationId the caller should invoke. Lets an MCP client resolve the call without parsing href.

string | null
rel
required

Link relation describing the action. Examples: self, cancel, pause, resume, events, retry, retry-later, unarchive, get-existing, delete, update.

string
schema_ref

OpenAPI $ref to the request-body schema, when the action takes one (e.g. #/components/schemas/UpdateSessionRequest). Lets a tool-calling agent fetch the input shape without scanning the whole spec.

string | null
code

Stable, machine-readable error code (snake_case).

string | null
detail

Human-readable explanation specific to this occurrence.

string | null
instance

Request URI for this occurrence.

string | null
retry_after_seconds

Seconds the caller should wait before retrying (429 / transient 503).

integer | null format: int32
status
required

HTTP status code; mirrors the response status line.

integer format: int32
title
required

Short, human-readable summary of the problem (e.g. “Not Found”).

string
type

RFC 9457 problem type URI. Optional; identifies the problem class.

string | null

Example

{
"allowed_actions": [
{
"method": "POST"
}
],
"code": "session_not_found",
"detail": "Session session_01933b5a000070008000000000000001 not found in org org_01933b5a000070008000000000000001.",
"instance": "/v1/sessions/session_01933b5a000070008000000000000001",
"retry_after_seconds": 30,
"status": 404,
"title": "Session not found",
"type": "https://everruns.com/docs/errors/session_not_found"
}
404Example not found

Example not found

Media typeapplication/json

Standard error response.

Wire shape is RFC 9457 Problem Details: every error response includes title and status, and may include detail, code, allowed_actions, retry_after_seconds, instance, and type. The content type is rewritten to application/problem+json with the application/problem+json content type.

object
allowed_actions

Recovery actions the caller can take next.

Array<object>

Agent-actionable link describing a follow-up the caller can take. Used in two contexts:

  • Error recovery — ErrorResponse.allowed_actions carries rels like retry, retry-later, unarchive, get-existing so the agent knows the right next call after a 4xx/429.
  • Entity hypermedia — WithUrls<T>.allowed_actions carries state-aware rels like cancel, events, self, update on the entity itself so the agent can follow links instead of reconstructing routes from prose.

The shape is intentionally identical across both contexts; the closed rel vocabulary distinguishes them.

object
hint

Short, agent-readable hint (e.g. “Shorten ‘name’ to <= 200 chars.”, “Cancel the active turn for this session.”).

string | null
href

Absolute (preferred) or relative URL the caller may invoke directly. Always present on entity hypermedia actions (WithUrls<T>.allowed_actions); optional on error-recovery actions (ErrorResponse.allowed_actions) where the matching operation_id is enough and the URI is implicit from the failed call.

string | null
method

HTTP method to use against href. Required for entity hypermedia actions; usually omitted on error-recovery actions where the same operation is retried with its original method.

string | null
operation_id

OpenAPI operationId the caller should invoke. Lets an MCP client resolve the call without parsing href.

string | null
rel
required

Link relation describing the action. Examples: self, cancel, pause, resume, events, retry, retry-later, unarchive, get-existing, delete, update.

string
schema_ref

OpenAPI $ref to the request-body schema, when the action takes one (e.g. #/components/schemas/UpdateSessionRequest). Lets a tool-calling agent fetch the input shape without scanning the whole spec.

string | null
code

Stable, machine-readable error code (snake_case).

string | null
detail

Human-readable explanation specific to this occurrence.

string | null
instance

Request URI for this occurrence.

string | null
retry_after_seconds

Seconds the caller should wait before retrying (429 / transient 503).

integer | null format: int32
status
required

HTTP status code; mirrors the response status line.

integer format: int32
title
required

Short, human-readable summary of the problem (e.g. “Not Found”).

string
type

RFC 9457 problem type URI. Optional; identifies the problem class.

string | null

Example

{
"allowed_actions": [
{
"method": "POST"
}
],
"code": "session_not_found",
"detail": "Session session_01933b5a000070008000000000000001 not found in org org_01933b5a000070008000000000000001.",
"instance": "/v1/sessions/session_01933b5a000070008000000000000001",
"retry_after_seconds": 30,
"status": 404,
"title": "Session not found",
"type": "https://everruns.com/docs/errors/session_not_found"
}
500Internal server error

Internal server error

Media typeapplication/json

Standard error response.

Wire shape is RFC 9457 Problem Details: every error response includes title and status, and may include detail, code, allowed_actions, retry_after_seconds, instance, and type. The content type is rewritten to application/problem+json with the application/problem+json content type.

object
allowed_actions

Recovery actions the caller can take next.

Array<object>

Agent-actionable link describing a follow-up the caller can take. Used in two contexts:

  • Error recovery — ErrorResponse.allowed_actions carries rels like retry, retry-later, unarchive, get-existing so the agent knows the right next call after a 4xx/429.
  • Entity hypermedia — WithUrls<T>.allowed_actions carries state-aware rels like cancel, events, self, update on the entity itself so the agent can follow links instead of reconstructing routes from prose.

The shape is intentionally identical across both contexts; the closed rel vocabulary distinguishes them.

object
hint

Short, agent-readable hint (e.g. “Shorten ‘name’ to <= 200 chars.”, “Cancel the active turn for this session.”).

string | null
href

Absolute (preferred) or relative URL the caller may invoke directly. Always present on entity hypermedia actions (WithUrls<T>.allowed_actions); optional on error-recovery actions (ErrorResponse.allowed_actions) where the matching operation_id is enough and the URI is implicit from the failed call.

string | null
method

HTTP method to use against href. Required for entity hypermedia actions; usually omitted on error-recovery actions where the same operation is retried with its original method.

string | null
operation_id

OpenAPI operationId the caller should invoke. Lets an MCP client resolve the call without parsing href.

string | null
rel
required

Link relation describing the action. Examples: self, cancel, pause, resume, events, retry, retry-later, unarchive, get-existing, delete, update.

string
schema_ref

OpenAPI $ref to the request-body schema, when the action takes one (e.g. #/components/schemas/UpdateSessionRequest). Lets a tool-calling agent fetch the input shape without scanning the whole spec.

string | null
code

Stable, machine-readable error code (snake_case).

string | null
detail

Human-readable explanation specific to this occurrence.

string | null
instance

Request URI for this occurrence.

string | null
retry_after_seconds

Seconds the caller should wait before retrying (429 / transient 503).

integer | null format: int32
status
required

HTTP status code; mirrors the response status line.

integer format: int32
title
required

Short, human-readable summary of the problem (e.g. “Not Found”).

string
type

RFC 9457 problem type URI. Optional; identifies the problem class.

string | null

Example

{
"allowed_actions": [
{
"method": "POST"
}
],
"code": "session_not_found",
"detail": "Session session_01933b5a000070008000000000000001 not found in org org_01933b5a000070008000000000000001.",
"instance": "/v1/sessions/session_01933b5a000070008000000000000001",
"retry_after_seconds": 30,
"status": 404,
"title": "Session not found",
"type": "https://everruns.com/docs/errors/session_not_found"
}