# VeilCLI — REST API Reference

The VeilCLI server exposes a local HTTP REST API. All requests use JSON. The default port is **5050**.

---

## Base URL

```
http://localhost:5050
```

Set a custom port in `.veil/settings.json` (`"port": 5051`) or via `veil start --port 5051`.

---

## Authentication

Authentication is **optional**. If you set `secret` in `settings.json`, every request must include the header:

```
X-Veil-Secret: <your-secret>
```

If no secret is configured, the API is open (localhost only by default).

---

## Request Format

All request bodies must be JSON with `Content-Type: application/json`.

---

## Response Format

All responses are JSON. Successful responses vary by endpoint. Error responses always use:

```json
{
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable description"
  }
}
```

### Error Codes

| HTTP Status | Code | Meaning |
|-------------|------|---------|
| 400 | `VALIDATION_ERROR` | Missing or invalid request body field |
| 400 | `MODE_NOT_SUPPORTED` | Agent does not support the requested mode |
| 400 | `SESSION_CLOSED` | Session has been closed |
| 400 | `COMPACTION_DISABLED` | `defaultCompaction.enabled` is false for this agent |
| 400 | `CANNOT_EDIT_SYSTEM_MESSAGE` | System messages cannot be edited |
| 400 | `CANNOT_EDIT_TOOL_MESSAGE` | Tool result messages cannot be edited |
| 400 | `CANNOT_DELETE_SYSTEM_MESSAGE` | System messages cannot be deleted |
| 400 | `MODEL_MODALITY_UNSUPPORTED` | Attachments were sent on a chat call routed through the claude-cli engine, which does not handle inline multimodal content blocks. Includes `details.attachmentType`. |
| 400 | `BUDGET_EXCEEDED` | `agent_spawn` spawn-depth pre-check failed. Includes `details.budgetType: "max_spawn_depth"`, `details.limit`, `details.actual`. **Mid-run** breaches of `max_tokens` / `max_wall_seconds` do NOT surface as a 400 — they cancel the loop (`cancelled: true` with `cancelReason: "budget_exceeded"`). |
| 401 | `UNAUTHORIZED` | Invalid or missing `X-Veil-Secret` |
| 404 | `AGENT_NOT_FOUND` | No agent with that name |
| 404 | `SESSION_NOT_FOUND` | No session with that ID |
| 404 | `MESSAGE_NOT_FOUND` | No message with that ID in the session |
| 404 | `NOT_FOUND` | Resource (e.g. memory file) not found |
| 409 | `AGENT_EXISTS` | Agent with that name already exists |
| 500 | `INTERNAL_ERROR` | Unexpected server error |

---

## Endpoints Overview

| Method | Path | Description |
|--------|------|-------------|
| WS | `/ws` | Real-time event stream (all events) |
| GET | `/health` | Liveness check |
| GET | `/status` | Full server status |
| POST | `/shutdown` | Graceful shutdown |
| **Agents** | | |
| POST | `/agents` | Create a new agent |
| GET | `/agents` | List all agents |
| GET | `/agents/:name` | Get agent details |
| PUT | `/agents/:name` | Update agent config / AGENT.md |
| DELETE | `/agents/:name` | Delete agent folder |
| POST | `/agents/:name/reload` | Hot-reload agent config from disk |
| GET | `/agents/:name/sessions` | Sessions scoped to agent |
| GET | `/agents/:name/skills` | Skills and custom tools for agent |
| **Chat** | | |
| POST | `/agents/:name/chat` | Send a chat message (supports SSE, `continue`, `attachments`) |
| **Sessions** | | |
| POST | `/sessions` | Create a new session (pre-create before chatting) |
| GET | `/sessions` | List sessions |
| GET | `/sessions/streaming` | List sessions whose chat loop is currently running |
| GET | `/sessions/:id` | Get session details |
| GET | `/sessions/:id/config` | Effective LLM params (effective + overrides + agent defaults) |
| PATCH | `/sessions/:id` | Update session metadata (title, instance_name, model, `temperature`/`max_tokens`/`reasoning`, compaction config) |
| GET | `/sessions/:id/messages` | Get session messages |
| PATCH | `/sessions/:id/messages/:msgId` | Edit a message's content |
| DELETE | `/sessions/:id/messages?after=:id` | Trim all messages after a point (query form) |
| DELETE | `/sessions/:id/messages/after/:id` | Trim all messages after a point (path form) |
| DELETE | `/sessions/:id/messages/:msgId` | Delete a single message |
| GET | `/sessions/:id/stream` | Real-time SSE stream for a session |
| GET | `/sessions/:id/context` | Inspect full session message history |
| POST | `/sessions/:id/fork` | Fork session up to a message point |
| POST | `/sessions/:id/compact` | Run default compaction on a session |
| POST | `/sessions/:id/cancel` | Cooperatively cancel an active chat loop (idempotent) |
| POST | `/sessions/:id/reset` | Clear messages, re-inject system prompt |
| DELETE | `/sessions/:id` | Close session (`?hard=true` = hard delete) |
| **Orchestration** | | |
| GET | `/orchestration/graph` | Multi-agent session/spawn graph (depth-bounded) |
| GET | `/orchestration/trace/:trace_id` | Full event tree for a trace, with totals |
| GET | `/orchestration/trace/:trace_id/stream` | SSE stream of `trace.event` rows for a trace |
| **Memory** | | |
| GET | `/memory` | List global memory files |
| GET | `/memory/:file` | Read a global memory file |
| PUT | `/memory/:file` | Write a global memory file |
| DELETE | `/memory/:file` | Delete a global memory file |
| GET | `/agents/:name/memory` | List agent memory files |
| GET | `/agents/:name/memory/:file` | Read an agent memory file |
| PUT | `/agents/:name/memory/:file` | Write an agent memory file |
| DELETE | `/agents/:name/memory/:file` | Delete an agent memory file |
| **Settings & Models** | | |
| GET | `/settings` | Get current settings (api_keys redacted) |
| PUT | `/settings` | Update settings with live reload |
| GET | `/providers` | List configured providers and routing rules |
| GET | `/models` | List all known models |
| GET | `/models/:provider/:name` | Get single model details |
| GET | `/models/custom` | Read custom models configuration |
| PUT | `/models/custom` | Write custom models configuration |
| POST | `/models/refresh` | Re-fetch models from OpenRouter and Claude CLI |
| **Completions** | | |
| POST | `/completions` | Standalone LLM call (no agent/session) |

---

## Detailed Reference

- [System endpoints](01-system.md)
- [Agents](02-agents.md) — create, update, delete, reload; agent-scoped sessions, skills
- [Chat](03-chat.md) — SSE streaming, `continue` flag, multimodal attachments
- [Sessions](05-sessions.md) — PATCH metadata, message editing, trim/delete, fork, compact, reset
- [Memory](07-memory.md) — global and agent-scoped memory files
- [Settings](08-settings.md)
- [Models](09-models.md)
- [WebSocket](09-websocket.md)
- [Completions](10-completions.md)