Create Session

Create a new session with an agent assigned to work in it

POST /v1/sessions

Creates a new session. Sessions are top-level entities under organizations, with an agent assigned to work in each session.

Request Body

agent_id · string · required

The ID of the agent to assign to this session. Must be a valid agent ID with the agent_ prefix.

title · string

Optional title for the session.

tags · string[]

Optional tags for organizing and filtering sessions.

model_id · string

Optional model override for this session. When set, this model will be used instead of the agent’s default model.

capabilities · object[]

Optional session-level capabilities that are additive to the agent’s capabilities.

When building the RuntimeAgent:

1. Agent capabilities are applied first
2. Session capabilities are applied after (additive)

This enables temporarily extending an agent’s capabilities for specific sessions without modifying the agent configuration.

Each capability object contains:

• ref (string, required): Capability reference ID (e.g., “current_time”, “web_fetch”)
• config (object, optional): Configuration overrides for the capability

Response

Returns the created Session object.

id · string

The session’s public ID with the session_ prefix.

agent_id · string

The ID of the agent assigned to this session.

title · string

The session title.

tags · string[]

Tags associated with the session.

model_id · string

Model override for this session, if set.

capabilities · object[]

Session-level capabilities (additive to agent capabilities).

status · string

Current session status: started, active, or idle.

Status transitions:

• started → Initial state
• active → Processing a turn
• idle → Waiting for input

Sessions work indefinitely — after processing, status returns to idle.

features · string[]

Computed at read time by aggregating features from all active capabilities (not stored).

created_at · string

ISO 8601 timestamp when the session was created.

updated_at · string

ISO 8601 timestamp when the session was last updated.

Example

curl -X POST https://api.everruns.com/v1/sessions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "agent_01234567-89ab-cdef-0123-456789abcdef",
    "title": "Research Session",
    "tags": ["research", "web"],
    "model_id": "gpt-4o",
    "capabilities": [
      { "ref": "current_time" },
      { "ref": "web_fetch", "config": { "timeout_ms": 30000 } }
    ]
  }'

Notes

• The agent_id field is required and must reference a valid agent
• Session capabilities extend the agent’s capabilities without modifying the agent
• Sessions are direct children of organizations, not agents
• All entity IDs use the dual-ID pattern (internal UUID PK + external public_id)