Skip to content
Docs
GitHub
Deprecated route

Use the canonical channel route. The legacy alias remains available; no removal date has been announced.

Open replacement: POST /v1/channels/{channel_id}/sessions →

Removal date: not announced.

Start a session (legacy)

Deprecated

Start a session on an api channel. The session starts idle; send a message to start a turn.

Public APIEverruns Cloud and self-hosted Platform

POST/v1/e/{channel_id}/sessions
channel_id
required
string

Api channel ID

Optional title. May be empty.

Media typeapplication/json

Start an idle session on an Agent API channel. The body may be empty. Send a message to begin a turn.

object
title

Optional title for the session.

string | null
<= 200 characters

Example

{
"title": "Order 42"
}

Responses

201Session started

Session started

Media typeapplication/json

A session as an execution caller sees it: no instructions, tools, owners or costs, which are management’s.

object
archived
required
boolean
created_at
required
string format: date-time
id
required
string
last_turn_status

Outcome of the last finished turn: completed, failed or cancelled.

string | null
parent_session_id
string | null
pending_approvals

Held-back tool calls the session waits on. Same rule as pending_questions.

Array<object> | null

A held-back tool call the session waits on. Same shape as serve’s pending_approvals item, plus answerable.

object
agent
One of:

The asking agent, when another agent in the run asked.

object
id
required

The agent’s id, as /v1/agents/{agent_id} takes it.

string
name
required

The agent’s display name.

string
answerable
required

Always true: the person using the agent answers its approvals.

boolean
arguments
required
object
arguments_truncated

arguments is a truncated preview; the decision still binds to the full arguments.

boolean
expires_at
required

When the request counts as rejected (RFC 3339).

string
risk
required

Why the gate asked: destructive, open_world, mutating or policy.

string
session_id

The asking agent’s session, when another agent in the run asked. Answer on this session; the server routes it.

string | null
tool_call_id
required

The request to name in POST …/tool-approvals.

string
tool_name
required
string
pending_questions

Question sets the session waits on. Only GET …/sessions/{id} reads them; a list leaves them out.

Array<object> | null

An ask_user question set the session waits on. Same shape as serve’s pending_questions item.

object
agent
One of:

The asking agent, when another agent in the run asked.

object
id
required

The agent’s id, as /v1/agents/{agent_id} takes it.

string
name
required

The agent’s display name.

string
expires_at

When the server stops waiting (RFC 3339).

string | null
questions
required

The questions as asked: kind, id, header, question, options, multi_select, allow_other.

Array<object>
object
session_id

The asking agent’s session, when another agent in the run asked. Answer on this session; the server routes it.

string | null
tool_call_id
required

The ask_user call to name in POST …/question-answers.

string
pinned
required
boolean
status
required

started, active, idle, waitingforinput or failed.

string
title
string | null
updated_at
required
string format: date-time
work
One of:

What the latest turn is doing or got done. Only GET …/sessions/{id} reads it. Under full visibility it is the whole report; otherwise the public view: state, plan counts, facts, the agent’s own summary and links, never step labels or approval prompts.

object
agent_name

Agent name snapshot at turn start.

string | null
attention
One of:

The open request when the work waits on a person.

object
kind
required

What kind of answer is needed.

string
Allowed values: approval question action
prompt
required

One line naming what is asked (“Run git push”).

string
tool_call_ids
required

Open client-side call ids that carry the request.

Array<string>
duration_ms

Elapsed time: to the end when finished, to the read time while running.

integer | null format: int64
ended_at

When the work ended.

string | null format: date-time
headline
required

One line, always present: the current step while working, the request while waiting, the result when finished.

string
model

Model of the latest generation.

string | null
omitted_steps

Steps run but no longer listed.

integer format: int32
plan
One of:

The plan the agent shared, if any.

object
current

The item in progress, in its “doing” form when the tool has one.

string | null
done
required

Items done or skipped.

integer format: int32
items
required

Plan items in order.

Array<object>

One checklist line in [BackgroundProgress::steps].

object
status
required

State of one checklist line.

string
Allowed values: pending in_progress done skipped
title
required
string
total
required

Items in total.

integer format: int32
result
One of:

What finished work produced. Absent while working.

object
artifacts

Files, links, pull requests and sessions the work produced.

Array<object>

Typed link to something the task produced.

object
name
required
string
path

Session VFS path, when the artifact lives in the session filesystem.

string | null
type
required

Artifact type: “file”, “url”, “session”, “pr”, etc.

string
url

External URL, when the artifact lives elsewhere.

string | null
checks

How the agent checked the work (“ran the 12 billing tests”), when it reported.

string | null
facts

Measured facts, in display order.

Array<object>

One measured fact.

object
kind
required

Which fact.

string
Allowed values: files_changed issues tasks_started steps
value
required

Its value.

integer format: int64
outcome
One of:

The agent’s own verdict, when it reported.

string
Allowed values: done failed
summary

One or two sentences on what changed.

string | null
summary_source
One of:

Where the summary came from.

string
Allowed values: agent reply
started_at

When the work started.

string | null format: date-time
state
required

Where the work stands.

string
Allowed values: working needs_you done failed stopped
steps
required

Steps in order, newest last, bounded by [MAX_REPORT_STEPS].

Array<object>

One step of the work: a tool call, labelled by its narration.

object
duration_ms

How long the step took, once finished.

integer | null format: int64
id
required

The tool call id.

string
label
required

What the step is doing (“Running tests”) or what came out of it (“Read AGENTS.md”).

string
progress
One of:

Live progress while running.

object
current

Items done so far, when the tool knows a count.

integer | null format: int64
label

The tool’s latest status line.

string | null
total

Items in total, when the tool knows a count.

integer | null format: int64
started_at

When the step started.

string | null format: date-time
state
required

Where the step stands.

string
Allowed values: running done issue
tool_name
required

Tool name.

string
turn_id
required

The turn the report describes.

string

Example

{
"id": "session_01933b5a000070008000000000000001",
"pending_approvals": [
{
"agent": {
"id": "agent_01933b5a00007000800000000000001",
"name": "Research Assistant"
}
}
],
"pending_questions": [
{
"agent": {
"id": "agent_01933b5a00007000800000000000001",
"name": "Research Assistant"
}
}
],
"status": "idle",
"work": {
"agent_name": "Billing fixer",
"attention": {
"kind": "approval",
"prompt": "Deploy to staging"
},
"duration_ms": 133000,
"ended_at": "2026-10-23T12:02:13Z",
"headline": "Step 3 of 4 · Running `cargo test`",
"model": "gpt-6.1-sol",
"omitted_steps": 0,
"plan": {
"current": "Run the tests",
"done": 2,
"items": [
{
"status": "pending"
}
],
"total": 4
},
"result": {
"checks": "Ran the 12 billing tests",
"facts": [
{
"kind": "files_changed",
"value": 3
}
],
"outcome": "done",
"summary": "Fixed the proration rounding and added a test.",
"summary_source": "agent"
},
"started_at": "2026-10-23T12:00:00Z",
"state": "working",
"steps": [
{
"duration_ms": 4200,
"id": "call_01",
"label": "Ran `cargo test`, 12 tests passed",
"progress": {
"current": 7,
"label": "Rendering image 7 of 12",
"total": 12
},
"started_at": "2026-10-23T12:00:00Z",
"state": "running",
"tool_name": "bash"
}
],
"turn_id": "turn_01933b5a00007000800000000000001"
}
}
400Invalid body, or the retired api_endpoint body `{"message": …}`

Invalid body, or the retired api_endpoint body {"message": …}

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"
}
401Missing or invalid credentials

Missing or invalid credentials

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"
}
403Agent not available

Agent not available

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"
}
404Channel not found

Channel 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"
}
429Rate or daily spending limit reached

Rate or daily spending limit reached

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