mirror of
https://github.com/harivansh-afk/sandbox-agent.git
synced 2026-04-15 08:03:46 +00:00
169 lines
2.9 KiB
Text
169 lines
2.9 KiB
Text
---
|
|
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`.
|
|
|
|
## Health
|
|
|
|
<details>
|
|
<summary><strong>GET /v1/health</strong> - Connectivity check</summary>
|
|
|
|
Response:
|
|
|
|
```json
|
|
{ "status": "ok" }
|
|
```
|
|
</details>
|
|
|
|
## 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`).
|