> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orcapods.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Sessions

> Conversations, turns, items, subagents, and artifacts.

A session is one conversation with an agent; see [sessions and turns](/guides/sessions) for how to use one. Paths are relative to `/v1`.

To create a session, send `environment` plus either `agent_id` (a saved agent) or `agent` (an inline configuration). `input` is optional; if present, it starts the first turn. Other optional fields are `vault_ids` and `metadata`. Use `{"type":"none"}` when no sandbox is needed.

## Sessions

| Method | Path | Purpose / response |
| - | - | - |
| `GET` | `/agents/sessions` | List · `SyncCursorPage[AgentSession]` |
| `POST` | `/agents/sessions` | Create · `AgentSession` |
| `DELETE` | `/agents/sessions/{session_id}` | Delete · `AgentSessionDeleted` |
| `GET` | `/agents/sessions/{session_id}` | Get · `AgentSession` |
| `POST` | `/agents/sessions/{session_id}` | Update · `AgentSession` |

## Session items and turns

| Method | Path | Purpose / response |
| - | - | - |
| `GET` | `/agents/sessions/{session_id}/items` | List · `SyncCursorPage[AgentSessionItem]` |
| `GET` | `/agents/sessions/{session_id}/turns` | List · `SyncCursorPage[Turn]` |
| `GET` | `/agents/sessions/{session_id}/turns/{turn_id}` | Get · `Turn` |

## Subagents and their history

| Method | Path | Purpose / response |
| - | - | - |
| `GET` | `/agents/sessions/{session_id}/subagents` | List · `SyncCursorPage[Subagent]` |
| `GET` | `/agents/sessions/{session_id}/subagents/{subagent_id}` | Get · `Subagent` |
| `GET` | `/agents/sessions/{session_id}/subagents/{subagent_id}/items` | List · `SyncCursorPage[AgentSessionItem]` |
| `GET` | `/agents/sessions/{session_id}/subagents/{subagent_id}/turns` | List · `SyncCursorPage[Turn]` |
| `GET` | `/agents/sessions/{session_id}/subagents/{subagent_id}/turns/{turn_id}` | Get · `Turn` |
| `GET` | `/agents/sessions/{session_id}/subagents/{subagent_id}/turns/{turn_id}/items` | List · `SyncCursorPage[AgentSessionItem]` |

## Artifacts

| Method | Path | Purpose / response |
| - | - | - |
| `GET` | `/agents/sessions/{session_id}/artifacts` | List · `SyncCursorPage[SessionArtifact]` |
| `DELETE` | `/agents/sessions/{session_id}/artifacts/{artifact_id}` | Delete · `SessionArtifactDeleted` |
| `GET` | `/agents/sessions/{session_id}/artifacts/{artifact_id}` | Get · `SessionArtifact` |
| `GET` | `/agents/sessions/{session_id}/artifacts/{artifact_id}/content` | Download · Binary content |

Create and read a conversation:

```bash theme={"dark"}
curl -X POST "$BASE_URL/agents/sessions" \
  -H "Authorization: Bearer $API_KEY" -H 'Content-Type: application/json' \
  -d '{"agent_id":"'"$AGENT_ID"'","environment":{"type":"none"},"input":"Summarize this topic."}'
curl -H "Authorization: Bearer $API_KEY" "$BASE_URL/agents/sessions/$SESSION_ID/turns?limit=10"
curl -H "Authorization: Bearer $API_KEY" "$BASE_URL/agents/sessions/$SESSION_ID/items?limit=10"
curl -X POST "$BASE_URL/agents/sessions/$SESSION_ID" \
  -H "Authorization: Bearer $API_KEY" -H 'Content-Type: application/json' \
  -d '{"metadata":{"project":"demo"}}'
```

## Statuses

| Object | `status` values |
| - | - |
| Session | `idle`, `in_progress`, `requires_action`, `failed` |
| Turn | `queued`, `in_progress`, `waiting`, `completed`, `failed`, `cancelled` |
| Subagent | `active`, `closed` |

See [turns and statuses](/turn-lifecycle) for what each means.

## Notes

`GET .../turns` lists subagent turns alongside the session's own; they carry a non-null `subagent_id`, while session items list only the session's own conversation. `POST /agents/sessions/{session_id}` updates metadata only. List sessions accepts `agent_id`, `after`, `limit`, `order`; history and artifact lists accept `after`, `limit`, `order` (artifacts also accept `environment_id`). A turn may still be in progress after session creation: inspect its status or subscribe to [events](/reference/events). Artifact content is binary, not a JSON resource. Deleting a session does not delete its saved agent.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.