---
title: "HTTP API"
description: "Endpoint reference for the sandbox agent daemon."
---

All endpoints are under `/v1`. Authentication uses the daemon-level token via `Authorization: Bearer <token>` or `x-sandbox-token`.

## Sessions

<details>
<summary><strong>POST /v1/sessions/{sessionId}</strong> - Create session</summary>

Request:

```json
{
  "agent": "claude",
  "agentMode": "build",
  "permissionMode": "default",
  "model": "claude-3-5-sonnet",
  "variant": "high",
  "agentVersion": "latest"
}
```

Response:

```json
{
  "healthy": true,
  "agentSessionId": "..."
}
```
</details>

<details>
<summary><strong>POST /v1/sessions/{sessionId}/messages</strong> - Send message</summary>

Request:

```json
{
  "message": "Describe the repository."
}
```
</details>

<details>
<summary><strong>GET /v1/sessions/{sessionId}/events</strong> - Fetch events</summary>

Query params:

- `offset`: last-seen event id (exclusive)
- `limit`: max number of events

Response:

```json
{
  "events": [
    {
      "id": 1,
      "timestamp": "2026-01-25T10:00:00Z",
      "sessionId": "my-session",
      "agent": "claude",
      "agentSessionId": "...",
      "data": { "message": { "role": "assistant", "parts": [{ "type": "text", "text": "..." }] } }
    }
  ],
  "hasMore": false
}
```
</details>

<details>
<summary><strong>GET /v1/sessions/{sessionId}/events/sse</strong> - Stream events (SSE)</summary>

Query params:

- `offset`: last-seen event id (exclusive)

SSE payloads are `UniversalEvent` JSON.
</details>

<details>
<summary><strong>POST /v1/sessions/{sessionId}/questions/{questionId}/reply</strong></summary>

Request:

```json
{ "answers": [["Option A"], ["Option B", "Option C"]] }
```
</details>

<details>
<summary><strong>POST /v1/sessions/{sessionId}/questions/{questionId}/reject</strong></summary>

Request:

```json
{}
```
</details>

<details>
<summary><strong>POST /v1/sessions/{sessionId}/permissions/{permissionId}/reply</strong></summary>

Request:

```json
{ "reply": "once" }
```
</details>

## Agents

<details>
<summary><strong>GET /v1/agents</strong> - List agents</summary>

Response:

```json
{
  "agents": [
    { "id": "claude", "installed": true, "version": "...", "path": "/usr/local/bin/claude" }
  ]
}
```
</details>

<details>
<summary><strong>POST /v1/agents/{agentId}/install</strong> - Install agent</summary>

Request:

```json
{ "reinstall": false }
```
</details>

<details>
<summary><strong>GET /v1/agents/{agentId}/modes</strong> - List modes</summary>

Response:

```json
{
  "modes": [
    { "id": "build", "name": "Build", "description": "Default coding mode" }
  ]
}
```
</details>

## Error handling

All errors use RFC 7807 Problem Details and stable `type` strings (e.g. `urn:sandbox-agent:error:session_not_found`).