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

# API overview

> The Vetta REST API — base URL, versioning, auth, and conventions.

The Vetta REST API is the programmatic interface to the hosted managed agent. Everything the [CLI](/docs/cli/overview) and the [TypeScript SDK](/docs/sdk/typescript) do is built on the endpoints documented here.

## Base URL

All requests go to a single, versioned base URL. Every path in this reference is relative to it.

```
https://api.vetta.sh/v1
```

## Versioning

The API carries **two** version coordinates, designed in from day one:

* A **path version** (`/v1`) that changes only for a wholesale redesign. There is no reflexive `/v2` — breaking changes are managed by the date version below, not the path.
* A **date version** sent per request in the `Vetta-Version` header (format `YYYY-MM-DD`), which pins the exact wire contract your integration was built against.

```bash theme={"system"}
Vetta-Version: 2026-09-01
```

Omitting the header pins your organization to the version in effect when its first key was created. Additive changes (new fields, new endpoints) are made in place within a date version; treat unknown response fields as forward-compatible and ignore them.

### Deprecation policy

Backwards-incompatible changes only ever ship behind a **new date version** — never silently. When a field or behavior is deprecated we publish it in the changelog, keep the old behavior available for a **minimum 6-month sunset window**, Pin `Vetta-Version` in production so a new default version can never break you.

<Note>
  There is no deprecation response header today. Deprecations are announced in the changelog only; do not write a client that keys off a header the API does not send.
</Note>

## Authentication

Authenticate with an organization-scoped API key in the `Authorization` header using the Bearer scheme.

```bash theme={"system"}
Authorization: Bearer sk_live_...
```

Keys belong to an [organization](/docs/api/organizations) and inherit its resources and credit balance. See [Authentication](/docs/api/authentication) for creating, scoping, and rotating keys.

## Request & response conventions

* Request and response bodies are JSON. Send `Content-Type: application/json` on any request with a body.
* Timestamps are RFC 3339 strings in UTC (e.g. `2026-08-20T17:00:00Z`), suffixed `_at`. Fields that need client-side arithmetic are also exposed as epoch millis, suffixed `_at_ms`.
* Object ids are prefixed by type — one prefix per type (e.g. `agt_` agents, `ses_` sessions, `cmp_` computers, `key_` keys, `led_` ledger entries). The random suffix is Crockford base32.
* Money is always an integer count of **micro-USD** in fields suffixed `_micro_usd` (1 USD = 1,000,000 micro-USD). Never floating-point dollars on the wire — clients convert for display only. See [Credits](/docs/api/credits).
* The single latency/price knob is the **completion window**: `immediate | priority | loose`. These exact strings travel on the wire everywhere; the default is `immediate`.

```json theme={"system"}
{
  "id": "agt_01H8XK...",
  "object": "agent",
  "created_at": "2026-08-20T17:00:00Z"
}
```

## Request ids

Every response — success or error — carries an `x-request-id` header. Log it; quoting it in a support request lets us trace the exact call. On errors the same value is mirrored inside the [error envelope](/docs/api/errors) as `error.request_id`.

```bash theme={"system"}
x-request-id: req_01H8XK2M...
```

## Idempotency

Every mutating `POST` accepts an `Idempotency-Key` header (also honored on the RPC-style verbs like top-ups, session messages, and computer creation). Reusing the same key replays the original response instead of performing the operation twice, making retries safe.

```bash theme={"system"}
Idempotency-Key: 8f14e45f-ea6b-4f1a-9c2d-1b2c3d4e5f60
```

The contract:

* **Same key, same body** → the original response is replayed. A replay carries an `Idempotency-Replayed: true` response header so you can tell a fresh result from a cached one.
* **Same key, different body** → `409` (`validation_failed`). A key binds to the exact request that first used it; reusing it with a changed payload is rejected rather than silently ignored.
* **Concurrent requests with the same key** → the first wins and the rest return `409` while it is in flight; retry after it settles to receive the replayed result.

<Note>
  Keys are scoped to your organization and retained for 24 hours. Use a fresh UUID per logical operation. Purely idempotent verbs (`GET`) ignore the header.
</Note>

## Pagination

List endpoints are cursor-paginated with `limit` and `after`, returning `{ data, has_more, next_cursor }`. The session [events](/docs/api/events) log is a separate, oldest-first `seq`-cursor contract. See [Pagination](/docs/api/pagination).

## Machine-readable description

`GET /v1/openapi.json` returns an **OpenAPI 3.1** description of this API, generated from the server's own route table — so it lists exactly the routes the deploy you are talking to serves, no more and no less. It needs no API key.

Each operation carries the scope a caller must hold as `x-vetta-scope`, and the shared [error envelope](/docs/api/errors) as its `default` response. Request and response bodies are not described yet; use the resource pages below for those.

```bash theme={"system"}
curl -fsSL https://api.vetta.sh/v1/openapi.json
```

## Errors

Errors use the single typed JSON envelope with standard HTTP status codes, and always include a `request_id`. See [Errors](/docs/api/errors).

## Rate limits & concurrency

Two independent limits apply per organization:

* **Request rate:** 6000 requests/minute per organization across the control plane (list, read, and mutate calls), and 3000 requests/minute per API key, so one key cannot spend the whole organization's budget. Fixed 60-second window.
* **Session concurrency:** 50 sessions in the `running` state at once. Starting a session beyond the cap queues it in `queued` until a slot frees.

When you exceed the request rate the API returns `429` with a `rate_limited` error and a `Retry-After` header (seconds to wait). Back off and retry after that delay. Rate-limit state is also returned in response headers:

| Header                | Meaning                                    |
| --------------------- | ------------------------------------------ |
| `RateLimit-Limit`     | Requests allowed in the current window.    |
| `RateLimit-Remaining` | Requests remaining in the window.          |
| `RateLimit-Reset`     | Seconds until the window resets.           |
| `Retry-After`         | On `429`, seconds to wait before retrying. |

`RateLimit-*` describes whichever of the two limits is closest to binding. The API also answers `429` with `rate_limited` and a `Retry-After` when the platform itself is momentarily at capacity — it never answers a capacity problem with a `500`, so a `429` is always safe to back off on and retry.

<Note>
  Concurrency limits are raised on request. The request-rate and concurrency numbers above are the default org tier; your organization's effective limits are reflected in the `RateLimit-*` headers.
</Note>

## Resources

| Page                                  | Resource                                                           |
| ------------------------------------- | ------------------------------------------------------------------ |
| [Authentication](/docs/api/authentication) | API keys and the Bearer scheme                                     |
| [Pagination](/docs/api/pagination)         | Cursor-based list pagination                                       |
| [Errors](/docs/api/errors)                 | Typed error envelope and codes                                     |
| [Agents](/docs/api/agents)                 | Versioned agent configurations                                     |
| [Models](/docs/api/models)                 | `GET /v1/models`, `GET /v1/models/{id}` — the live model catalogue |
| [Sessions](/docs/api/sessions)             | Directly-controlled agent runs                                     |
| [Events](/docs/api/events)                 | Event list + SSE stream                                            |
| [Computers](/docs/api/computers)           | Sandboxed compute environments                                     |
| [Skills](/docs/api/skills)                 | Versioned, org-scoped skills                                       |
| [Files](/docs/api/files)                   | Vetta object storage                                               |
| [Deployments](/docs/api/deployments)       | Scheduled (cron) agent runs                                        |
| [Webhooks](/docs/api/webhooks)             | Outbound webhook endpoints                                         |
| [MCP server](/docs/api/mcp)                | `POST /v1/mcp` — the API as a tool catalog for an agent            |
| [Organizations](/docs/api/organizations)   | Orgs, members, and keys                                            |
| [Credits](/docs/api/credits)               | Real-USD balance and ledger                                        |
| [Audit logs](/docs/api/audit-logs)         | Principal-attributed control-plane actions                         |
| [Identities](/docs/api/identities)         | Communication identities                                           |
| [Domains](/docs/api/domains)               | Sending and receiving domains                                      |
| [Messaging](/docs/api/messaging)           | Persona inboxes, numbers, and messages                             |
| [Connections](/docs/api/connections)       | Connector auth configs and connected accounts                      |
| [Vaults](/docs/api/vaults)                 | Credential vaults                                                  |

Every page above is one row of the same route table the [TypeScript SDK](/docs/sdk/typescript) and the [CLI](/docs/cli/overview) are generated against, so an operation you find here has a method and a command with the same name.

<CardGroup cols={2}>
  <Card title="TypeScript SDK" icon="js" href="/docs/sdk/typescript">
    `npm i @usenaive-sdk/vetta` — one typed method per route, with the full method index.
  </Card>

  <Card title="CLI" icon="terminal" href="/docs/cli/overview">
    `npm i -g @usenaive-sdk/vetta-cli` — the same surface from a terminal or CI.
  </Card>
</CardGroup>