> ## 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 Naive Managed Agents REST API — base URL, versioning, auth, and conventions.

The Naive Managed Agents REST API is the programmatic interface to the hosted managed agent. Everything the [CLI](https://vetta.sh/docs/cli/overview.md) and the [TypeScript SDK](https://vetta.sh/docs/sdk/typescript.md) 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
```

The API's identifiers (this host, the `Vetta-Version` header, `x-vetta-scope`) carry the name `vetta`. It's the same product as Naive.

## 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-30
```

| Version | What changed |
| - | - |
| `2026-09-30` | A question's fields may be `connect` (a connect card) and `media` (files and links). A pin before it is sent each as a `text` field whose placeholder says how to answer it. |
| `2026-09-01` | Unknown body keys and query parameters are refused, not dropped. |

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.

## 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](https://vetta.sh/docs/api/organizations.md) and inherit its resources and credit balance. See [Authentication](https://vetta.sh/docs/api/authentication.md) 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](https://vetta.sh/docs/api/credits.md).
* 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](https://vetta.sh/docs/api/errors.md) 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.

## Pagination

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

## 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](https://vetta.sh/docs/api/errors.md) 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](https://vetta.sh/docs/api/errors.md).

## 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.

## Resources

| Page | Resource |
| - | - |
| [Authentication](https://vetta.sh/docs/api/authentication.md) | API keys and the Bearer scheme |
| [Pagination](https://vetta.sh/docs/api/pagination.md) | Cursor-based list pagination |
| [Errors](https://vetta.sh/docs/api/errors.md) | Typed error envelope and codes |
| [Agents](https://vetta.sh/docs/api/agents.md) | Versioned agent configurations |
| [Models](https://vetta.sh/docs/api/models.md) | `GET /v1/models`, `GET /v1/models/{id}` — the live model catalogue |
| [Sessions](https://vetta.sh/docs/api/sessions.md) | Directly-controlled agent runs |
| [Events](https://vetta.sh/docs/api/events.md) | Event list + SSE stream |
| [Computers](https://vetta.sh/docs/api/computers.md) | Sandboxed compute environments |
| [Browser](https://vetta.sh/docs/api/browser.md) | A computer's managed browser: actions, saved logins and who may reopen them |
| [Mobile devices](https://vetta.sh/docs/api/mobile-devices.md) | Cloud Android phones: create, act, live view, delete |
| [Data](https://vetta.sh/docs/api/data.md) | Search the data catalogue, read a tool's input schema, run it, priced per run |
| [Social data](https://vetta.sh/docs/api/social-data.md) | The data catalogue's social domain: public social media data, no connected account |
| [Skills](https://vetta.sh/docs/api/skills.md) | Versioned, org-scoped skills |
| [Files](https://vetta.sh/docs/api/files.md) | The asset library every generated result lands in |
| [Media](https://vetta.sh/docs/api/media.md) | The media routes as one surface, and the catalogue of models they accept |
| [Images](https://vetta.sh/docs/api/images.md) | Synchronous image generation and licensed stock photos |
| [Video](https://vetta.sh/docs/api/video.md) | Video generation as a queued `med_` job |
| [Clips](https://vetta.sh/docs/api/clips.md) | Long video cut into short captioned clips, as a job |
| [Media skills](https://vetta.sh/docs/api/media-skills.md) | A skill built from 1–3 public short videos, saved to Skills |
| [Audio](https://vetta.sh/docs/api/audio.md) | Transcription and speech |
| [Database](https://vetta.sh/docs/api/database.md) | A fullstack app's database: SQL, tables, REST passthrough, migrations |
| [Storage](https://vetta.sh/docs/api/storage.md) | A fullstack app's object storage: buckets, objects, signed URLs |
| [Deployments](https://vetta.sh/docs/api/deployments.md) | Scheduled (cron) agent runs |
| [Webhooks](https://vetta.sh/docs/api/webhooks.md) | Outbound webhook endpoints |
| [MCP server](https://vetta.sh/docs/api/mcp.md) | `POST /v1/mcp` — the API as a tool catalog for an agent |
| [Organizations](https://vetta.sh/docs/api/organizations.md) | Orgs, members, and keys |
| [Credits](https://vetta.sh/docs/api/credits.md) | Real-USD balance and ledger |
| [Audit logs](https://vetta.sh/docs/api/audit-logs.md) | Principal-attributed control-plane actions |
| [Identities](https://vetta.sh/docs/api/identities.md) | Communication identities |
| [Domains](https://vetta.sh/docs/api/domains.md) | Sending and receiving domains |
| [Messaging](https://vetta.sh/docs/api/messaging.md) | Persona inboxes, numbers, and messages |
| [Connections](https://vetta.sh/docs/api/connections.md) | Connector auth configs and connected accounts |
| [Vaults](https://vetta.sh/docs/api/vaults.md) | Credential vaults |

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

> [card] [TypeScript SDK](https://vetta.sh/docs/sdk/typescript.md)
>
> `npm i @usenaive-sdk/vetta` — one typed method per route, with the full method index.

> [card] [CLI](https://vetta.sh/docs/cli/overview.md)
>
> `npm i -g @usenaive-sdk/vetta-cli` — the same surface from a terminal or CI.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.