Skip to main content
POST
/
v1
/
agents
/
{agent_id}
/
sessions
curl -X POST https://api.dari.dev/v1/agents/agt_123/sessions \
  -H "Authorization: Bearer $DARI_API_KEY"

{
  "id": "sess_123",
  "name": null,
  "agent_id": "agt_123",
  "version_id": "ver_9",
  "storage_binding_id": null,
  "internet_access": false,
  "status": "idle",
  "last_message_id": null,
  "last_message_status": null,
  "created_at": "2026-03-31T18:40:00Z",
  "metadata": {}
}

Documentation Index

Fetch the complete documentation index at: https://docs.dari.dev/llms.txt

Use this file to discover all available pages before exploring further.

Creates a durable session for an agent. The session uses the agent version that is active when the session is created. You can optionally attach string key/value metadata, session-scoped secrets, and sandbox internet access overrides when creating the session. Values passed in secrets are available to the sandbox only when their names are declared in the agent’s sandbox.secrets. The llm_api_key field is a separate per-session LLM provider override; it is used for model calls and is not injected into the sandbox environment. Secret values are accepted only when the session is created and are never returned in API responses.

​
Path Parameters

​
agent_id
string
required
Agent ID.

​
Headers

​
Authorization
string
required
Bearer token using your Dari API key.
​
Content-Type
string
If present, use application/json.

​
Request Body

​
name
string
Optional user-visible session name.
​
storage_binding_id
string
Optional storage binding ID to mount into this session.
​
metadata
object
Optional string key/value metadata. Metadata is returned by session endpoints, can be used for exact-match session filtering, and is included in session and batch webhook payloads. Use keys such as managed_run_id, kind, task_index, or llm_id to correlate sessions with your own runs.
​
secrets
object
Optional session-scoped secret values keyed by env-var-safe names. These can override stored credentials with the same names for this session. Secret names must match ^[A-Z_][A-Z0-9_]*$, and values must be non-empty strings.
​
llm_api_key
string
Optional LLM provider API key for this session. This overrides the manifest’s stored LLM credential or the Dari-managed default for provider calls only. It is never exposed to sandbox code.
​
internet_access
boolean
Optional override for whether this session’s execution sandbox can access the public internet. If omitted, Dari uses sandbox.internet_access from the agent manifest, which defaults to false.

​
Response Fields

​
id
string
Session ID.
​
name
string
User-visible session name, if one was supplied.
​
agent_id
string
Agent ID.
​
version_id
string
Agent version used by this session.
​
storage_binding_id
string
Storage binding mounted into this session, if one was supplied.
​
internet_access
boolean
Whether this session’s execution sandbox can access the public internet.
​
status
string
Current session lifecycle state, such as idle or running.
​
last_message_id
string
Most recent message ID, if any.
​
last_message_status
string
Most recent message status, if any.
​
created_at
string
ISO 8601 creation timestamp.
​
metadata
object
Session metadata as string key/value pairs.
curl -X POST https://api.dari.dev/v1/agents/agt_123/sessions \
  -H "Authorization: Bearer $DARI_API_KEY"

{
  "id": "sess_123",
  "name": null,
  "agent_id": "agt_123",
  "version_id": "ver_9",
  "storage_binding_id": null,
  "internet_access": false,
  "status": "idle",
  "last_message_id": null,
  "last_message_status": null,
  "created_at": "2026-03-31T18:40:00Z",
  "metadata": {}
}