Developers · api
Five nouns, one boundary.
Sessions, execution, policy, approvals, evidence. The SDKs are thin wrappers over exactly this, so anything the libraries can do you can do with a token and curl.
00 / conventions
- Base URL
- https://api.velone.in — or your own control-plane host in BYOC and air-gapped installs.
- Auth
- Bearer token. Service tokens for machines, device-flow tokens for humans. Approvals require a human principal.
- Versioning
- Path-versioned. Breaking changes ship a new major; we support the previous one for twelve months.
- Idempotency
- Idempotency-Key honoured on all POST endpoints that create or execute.
- Errors
- Structured JSON with a stable code, the matching policy rule where relevant, and a retry hint.
- Streaming
- Server-sent events for shell output, browser events, and approval resolution.
- Rate limits
- Per token and per session, returned in headers. 429 includes a reset timestamp.
01 / sessions
The durable worker. Everything else is scoped to a session id, and a session id is what you keep in your own database.
| Method | Path | Description |
|---|---|---|
| POST | /v1/sessions | Create a session with a name, principal, ring, policy, and region. |
| GET | /v1/sessions/:id | Current state, ring, budget consumed, evidence cursor. |
| POST | /v1/sessions/:id/suspend | Snapshot and release compute. Billing stops. |
| POST | /v1/sessions/:id/resume | Rehydrate the filesystem and continue the chain. |
| POST | /v1/sessions/:id/fork | Branch from current state into a new session. |
| DELETE | /v1/sessions/:id | Destroy the sandbox and zero its disks. |
| GET | /v1/sessions | List and filter by principal, ring, state, or region. |
02 / execution
Every call here is subject to policy before it runs. A denial returns 403 with the matching rule; an escalation blocks until a human decides or the timeout expires.
| Method | Path | Description |
|---|---|---|
| POST | /v1/sessions/:id/shell | Run a command. Streams stdout and stderr over SSE. |
| GET | /v1/sessions/:id/files/* | Read a file, path-scoped by policy. |
| PUT | /v1/sessions/:id/files/* | Write a file, path-scoped by policy. |
| POST | /v1/sessions/:id/http | Outbound request through the gateway with credential injection. |
| POST | /v1/sessions/:id/mcp | Invoke a tool on a registered MCP server. |
| POST | /v1/sessions/:id/browser | Drive a managed Chromium instance. |
03 / policy
Policy is normally a file in your repository. These endpoints exist for platform teams building their own control surface on top.
| Method | Path | Description |
|---|---|---|
| POST | /v1/policies | Upload and compile a policy document; returns a version. |
| GET | /v1/policies/:version | Fetch a compiled policy and its source digest. |
| POST | /v1/policies/:version/evaluate | Dry-run a tool call against a policy without executing. |
| GET | /v1/policies/:version/diff/:other | Structural diff between two versions. |
04 / approvals
Escalations become approval requests. Route them to Slack, email, or your own queue and resolve them with a signed decision.
| Method | Path | Description |
|---|---|---|
| GET | /v1/approvals | Pending approvals for a user or group. |
| POST | /v1/approvals/:id/grant | Approve. Requires an authenticated human principal. |
| POST | /v1/approvals/:id/deny | Deny with an optional reason returned to the agent. |
| POST | /v1/approvals/webhook | Register a destination for escalation events. |
05 / evidence
Read your own audit chain. These are the endpoints the CLI uses, and they are available to your SIEM directly.
| Method | Path | Description |
|---|---|---|
| GET | /v1/evidence | Query by session, principal, tool, decision, or time range. |
| GET | /v1/evidence/:seq | One entry with its hash and predecessor. |
| POST | /v1/evidence/export | Stream JSONL to a signed URL or your bucket. |
| GET | /v1/evidence/checkpoints | Signed chain heads for independent verification. |
| POST | /v1/evidence/replay | Reconstruct a session step by step. |
06 / a denial
What a blocked call looks like.
HTTP/1.1 403 Forbidden
content-type: application/json
{
"code": "policy_denied",
"message": "egress to telemetry.vendor.io is not allowed",
"rule": "egress.default",
"session": "session/a04f",
"ring": 2,
"evidence_seq": 5,
"retryable": false,
"hint": "add the host to egress.allow, or route via the gateway"
}keep reading
Ring 0
Get a token and try a denial.
The fastest way to understand the product is to watch a call get blocked and read the reason it gives you.