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

# API reference

> Authenticated control-plane route groups, worker endpoints, response contracts, and extension rules.

Mandala's Next.js route handlers form the shared control plane for the terminal and web clients. They are product APIs, not a public unauthenticated integration surface.

Most request and response schemas live in `packages/control-plane`. Routes reject unknown or malformed input, authenticate the user or managed CLI session, verify the selected workspace, authorize an exact permission, and return a bounded safe projection.

## Response shape

New control-plane routes use a versioned success or error envelope with metadata. Clients should branch on the stable error code, not parse human-readable messages.

Mutating requests carry expected versions, reasons, confirmation state, or idempotency keys when the operation needs them. Version conflicts return a safe error instead of overwriting newer state.

## Route groups

### Agents

`/api/mandala/agents` covers validation, installation, listing, and per-agent lifecycle operations:

* activate and deactivate;
* pause, resume, and disable;
* test runs and manual runs; and
* version history and rollback through the lifecycle service.

### Work and approvals

`/api/mandala/workflows` exposes:

* filtered, cursor-paginated work queues;
* safe item detail and review projections;
* item activity and read-only questions;
* fixture runs;
* approve, edit, reject, rework, and resolve decisions;
* short-lived execution capabilities; and
* controlled execution.

Queue and review responses intentionally omit private receipts, raw credentials, and unbounded source payloads.

### Sandbox and workspace data

`/api/mandala/sandbox/sessions` and `/api/mandala/sandbox/runs` create temporary real-data sessions and run skill definitions against cataloged workspace data.

Mappings, freshness, source coverage, and schema compatibility are checked before the run proceeds.

### Control and conversation

`/api/mandala/control` covers bounded intent parsing, request audit state, transitions, and contextual chat. Read-only questions can stream text; state changes still resolve to typed intents and use the guarded mutation routes.

### Hosted CLI authorization

`/api/mandala/cli` handles device-authorization bootstrap, inspection, browser decision, token exchange, session refresh, revocation, and workspace selection.

### Workspace services

Company, membership, invitation, profile, usage, feedback, governed memory, Context Engine setting, monitoring, and logo routes live under `/api/mandala`.

## Internal worker routes

These routes are for scheduled server-to-server work and require worker or cron secrets:

| Route                                      | Purpose                                                 |
| ------------------------------------------ | ------------------------------------------------------- |
| `/api/internal/mandala/connector-sync/run` | Sync enabled connector installations                    |
| `/api/internal/mandala/context-index/run`  | Process Context Engine outbox, jobs, and reconciliation |
| `/api/internal/email/payload`              | Resolve protected email payloads                        |
| `/api/internal/account-deletion/cleanup`   | Finish scheduled account deletion                       |

Worker routes accept bounded batches and rely on database leases and idempotency. Do not expose their secrets to the browser or CLI.

## Legacy workspace APIs

The web workspace still uses collection read routes under `/api/collections` and the aggregate route at `/api/aggregate`. They support the original page and collection surfaces and are separate from the Mandala agent control plane.

## Adding or changing a route

1. Define or update the Zod contract in `packages/control-plane` when the client shares it.
2. Authenticate and bind the request to one workspace.
3. Authorize the exact permission, not a generic signed-in check.
4. Return the smallest safe response projection.
5. Require expected versions and idempotency for state transitions where appropriate.
6. Add route tests for success, malformed input, wrong tenant, insufficient role, stale version, and replay.
7. Keep secrets, raw provider payloads, and private workflow tables out of response bodies and traces.