Skip to content
Everruns

POST /v1/sessions - Create a new session

POST
/v1/sessions

Request Body required

Section titled “Request Body required ”

Request to create a session

object
agent_id
required

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

string
Example
agent_01933b5a00007000800000000000001
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
model_id

The ID of the LLM model to use for this session. Overrides the agent’s default model if specified.

string | null
Example
model_01933b5a00007000800000000000001
tags

Tags for organizing and filtering sessions.

Array<string>
Example
[
  "debugging",
  "urgent"
]
title

Human-readable title for the session.

string | null
Example
Debug login issue

Responses

Section titled “ Responses ”

201

Section titled “201 ”

Session created successfully

Session - instance of agentic loop execution. A session represents a single conversation with an agent.

object
agent_id
required

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

string
Example
agent_01933b5a00007000800000000000001
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
finished_at

Timestamp when the session finished (completed or failed).

string | null format: date-time
id
required

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

string
Example
session_01933b5a00007000800000000000001
model_id

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

string | null
Example
model_01933b5a00007000800000000000001
organization_id
required

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

string
Example
org_00000000000000000000000000000001
output_preview

Preview text from the last assistant response (truncated).

string | null
preview

Preview text from the first user message (truncated).

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

Tags for organizing and filtering sessions.

Array<string>
title

Human-readable title for the session.

string | null
updated_at
required

Timestamp when the session was last updated.

string format: date-time
usage
One of:
null

400

Section titled “400 ”

Invalid agent ID

500

Section titled “500 ”

Internal server error