Skip to content
Everruns Everruns

Get or create global chat session

POST
/v1/sessions/chat
 
curl --request POST \
  --url https://app.everruns.com/api/v1/sessions/chat \
  --header 'Content-Type: application/json' \
  --data '{ "locale": "example" }'

Returns the user’s singleton global chat session. Creates one if it doesn’t exist. Uses the Platform Chat harness and tags for per-user singleton management.

Request Body

Section titled “Request Body ”
Media type application/json
One of:
null
Example generated
{
  "locale": "example"
}

Responses

Section titled “ Responses ”

200

Section titled “200 ”

Chat session returned

Media type application/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
active_schedule_count

Number of active (enabled) schedules for this session. Populated when the session is fetched for API responses.

integer | null format: int32
agent_id

ID of the agent working in this session (format: agent_{32-hex}). Optional.

string | null
agent_identity_id

Optional resident agent identity for unattended/background execution.

string | null
agent_version_id

Immutable agent version captured when the session was created or rebound.

string | null
blueprint_config

Validated config passed by host at blueprint spawn time. Example: {"target_repo": "acme/everruns"}.

object | null
blueprint_id

Blueprint ID. When set, reason_activity and act_activity build RuntimeAgent from the blueprint definition instead of from harness_id/agent_id.

string | null
capabilities

Session-level capabilities (additive to agent capabilities). Applied after agent capabilities when building RuntimeAgent.

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
created_at
required

Timestamp when the session was created.

string format: date-time
effective_owner
One of:
null
features

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

Array<string>
finished_at

Timestamp when the session finished (completed or failed).

string | null format: date-time
harness_id
required

ID of the harness for this session (format: harness_{32-hex}).

string
hints

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}

object | null
id
required

Unique identifier for the session (format: session_{32-hex}).

string
initial_files

Session-level initial files (additive to agent initial_files). Files with matching paths override agent/harness files; new paths are appended.

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
is_pinned

Whether this session is pinned by the current user. Only populated when the request has an authenticated user context.

boolean | null
locale

Locale for localized agent behavior and formatting (BCP 47, e.g. uk-UA).

string | null
max_iterations

Maximum number of LLM iterations per turn for this session.

integer | null
mcpServers

Remote MCP servers scoped to this session only.

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
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 o_auth
command

Executable to spawn for a stdio transport server.

string | null
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
tool_discovery

Whether to discover tool definitions live from this server.

boolean
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
model_id

LLM model ID to use for this session (format: model_{32-hex}). Overrides the agent’s default model if set.

string | null
network_access
One of:
null
organization_id
required

Organization this session belongs to (format: org_{32-hex}).

string
output_preview

Preview text from the last assistant response (truncated).

string | null
owner
One of:
null
owner_principal_id
required

Owning principal for this session.

string
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
parent_session_id

Parent session that spawned this subagent. NULL for top-level sessions. Used as the nesting guard in spawn_subagent.

string | null
preview

Preview text from the first user message (truncated).

string | null
resolved_owner_user_id

Denormalized effective human owner of the owning principal lineage.

string | null format: uuid
started_at

Timestamp when the session started executing.

string | null format: date-time
status
required

Current execution status of the session.

string
Allowed values: started active idle waitingfortoolresults paused
system_prompt

Session-level system prompt override. Prepended to the agent’s system prompt when building RuntimeAgent.

string | null
tags

Tags for organizing and filtering sessions.

Array<string>
title

Human-readable title for the session.

string | null
tools

Client-side tools for this session (additive to agent tools).

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_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 crate::atoms::tool_scheduler for how the act scheduler 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
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:
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 session was last updated.

string format: date-time
usage
One of:
null
workspace_id
required

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.

string
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 documented in specs/api-conventions.md 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. Closed vocabulary documented in specs/api-conventions.md — 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 
{
  "active_schedule_count": 2,
  "agent_id": "agent_01933b5a00007000800000000000001",
  "agent_identity_id": "identity_01933b5a00007000800000000000001",
  "agent_version_id": "agentver_01933b5a00007000800000000000001",
  "blueprint_id": "blueprint_research_pack",
  "created_at": "2026-05-25T10:00:00Z",
  "effective_owner": {
    "id": "principal_01933b5a000070008000000000000001",
    "kind": "user"
  },
  "features": [
    "file_system",
    "secrets"
  ],
  "finished_at": "2026-05-25T10:14:32Z",
  "harness_id": "harness_01933b5a00007000800000000000001",
  "id": "session_01933b5a00007000800000000000001",
  "is_pinned": false,
  "locale": "en-US",
  "max_iterations": 50,
  "mcpServers": {
    "additionalProperty": {
      "auth_mode": "none",
      "type": "http"
    }
  },
  "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",
  "started_at": "2026-05-25T10:00:01Z",
  "status": "started",
  "tags": [
    "marketing",
    "q3",
    "draft"
  ],
  "title": "Q3 marketing brief",
  "tools": [
    {
      "deferrable": "never",
      "hints": {
        "side_effect_class": "Pure"
      },
      "policy": "auto",
      "type": "builtin"
    }
  ],
  "updated_at": "2026-05-25T10:14:32Z",
  "workspace_id": "wsp_01933b5a00007000800000000000001",
  "allowed_actions": [
    {
      "method": "POST"
    }
  ]
}

401

Section titled “401 ”

Authentication required

500

Section titled “500 ”

Internal server error