API overview

The Skydive API is a REST API for managing agents and their credentials programmatically. It is the surface the Skydive CLI is built on: list and create agents, mint and revoke API keys, and manage the secrets an agent’s sandbox can see.

curl https://api.skydive.com/v1/agents \
  -H "Authorization: Bearer $SKYDIVE_API_KEY"

{
  "agents": [
    {
      "id": "019f6240-72f2-7a7d-acb0-ca83fc1072dc",
      "name": "Nephew",
      "url": "https://019f6240-72f2-7a7d-acb0-ca83fc1072dc.skydive.app",
      "description": "Engineering assistant",
      "model": "anthropic/claude-opus-4-8",
      "gitUrl": "https://git.skydive.storage/anyone-agent-019f6240-72f2-7a7d-acb0-ca83fc1072dc.git"
    }
  ],
  "count": 1,
  "nextCursor": null
}

All endpoints are served from a single versioned base URL:

https://api.skydive.com/v1

Requests and responses are JSON. The API is also self-describing: the current OpenAPI document and an interactive reference are served by the API itself.

Authentication

Every request requires an API key in the Authorization header:

Authorization: Bearer sky_live_...

Keys are created from an agent’s API access settings in the app, or through the API itself. The full key value is returned exactly once, at creation. Skydive stores only a hash, so a lost key cannot be recovered, only replaced. Requests without a valid key return 401.

An API key carries the authority to act on your agents. Keep it out of client-side code and version control. If a key is exposed, revoke it and mint a new one; revocation takes effect immediately.

Scopes and binding

Every key has a scope and a binding, set at creation. Together they determine exactly what a request may do:

Property	Values	Effect
Scope	`use`	Read operations: get and list agents, list key metadata, list secret names.
	`edit`	Everything `use` allows, plus create agents, mint and revoke keys, and set or delete secrets.
Binding	agent-bound	The key acts on one agent only. It cannot read or modify any other agent, and cannot list or create agents across the workspace.
	account-level	The key acts on any agent its owner can edit, and can list and create agents.

A request that exceeds the key’s scope or binding fails with 403 and an explanatory message. It never partially succeeds. Keys minted through POST /v1/agents/{agentId}/api-keys are always agent-bound with the use scope.

Errors

The API uses conventional HTTP status codes. Every error response has the same shape: an error field with a human-readable message, and on some errors a machine-readable code.

{
  "error": "this api key lacks the required 'edit' scope"
}

Status	Meaning
`400`	The request is malformed: an invalid pagination cursor, or a secret name that is not a valid identifier.
`401`	The API key is missing, malformed, or revoked.
`403`	The key is valid, but its scope or agent binding does not permit this operation.
`404`	The resource does not exist or is not visible to you. Skydive returns `404` rather than `403` for agents you cannot view, so the existence of a private agent is never revealed.
`409`	The request conflicts with existing state, such as a name that cannot be assigned.
`429`	Agent creation quota or rate limit exceeded.
`5xx`	Something failed on Skydive’s side. Retry with backoff.

Pagination

List endpoints return results newest first and paginate with an opaque cursor. Pass limit (1 to 100, default 50) to size the page, and pass the previous response’s nextCursor to fetch the next page. A null nextCursor means you have reached the end.

curl "https://api.skydive.com/v1/agents?limit=2" \
  -H "Authorization: Bearer $SKYDIVE_API_KEY"
# ... "nextCursor": "2026-08-01T09:14:52.000Z|019f62..."

curl "https://api.skydive.com/v1/agents?limit=2&cursor=2026-08-01T09%3A14%3A52.000Z%7C019f62..." \
  -H "Authorization: Bearer $SKYDIVE_API_KEY"

Treat cursors as opaque strings: URL-encode them when passing them back, and do not parse or construct them.

Versioning

The path prefix is the API version. Within v1, response shapes are additive only: new fields may appear, but existing fields are never removed, renamed, or retyped. Breaking changes ship as a new version prefix. Write clients that ignore unknown fields.

Secrets are write-only

Secret values can be set and deleted but never read back. GET /v1/agents/{agentId}/secrets returns key names only. This matches how secrets work inside the agent’s sandbox and keeps the API from becoming a way to exfiltrate credentials. To rotate a secret, set the new value; to verify one exists, list the names.

Endpoints

Agents

List, fetch, and create agents.

API keys

Mint, list, and revoke an agent’s keys.

Secrets

Set and remove an agent’s secrets.

Get started

Agents

Talk to them

Computer

Integrations

Workspaces

Authentication

Scopes and binding

Errors

Versioning

Secrets are write-only

Endpoints

Agents

API keys

Secrets

​Authentication

​Scopes and binding

​Errors

​Pagination

​Versioning

​Secrets are write-only

​Endpoints

Agents

API keys

Secrets

Authentication

Scopes and binding

Errors

Pagination

Versioning

Secrets are write-only

Endpoints