API reference

The Volcano REST API lets you manage projects, deploy functions and frontends, provision databases, and handle user authentication.

Base URL

https://api.volcano.dev

For local development:

http://localhost:8000

Authentication

All API requests require authentication. Include your token in the Authorization header:

curl "https://api.volcano.dev/projects" \
  -H "Authorization: Bearer $PLATFORM_TOKEN"

Different endpoints require different token types:

See Authentication for details on each token type, and Using the API for a worked example from first token to first deploy.

A machine-readable description of everything below is available at https://api.volcano.dev/openapi.yaml — see OpenAPI specification for generating a client or importing the API into a REST client.

Request format

Send JSON data in request bodies:

curl -X POST "https://api.volcano.dev/projects" \
  -H "Authorization: Bearer $PLATFORM_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "my-project"}'

For file uploads (function deployment), use multipart/form-data:

curl -X POST "https://api.volcano.dev/projects/$PROJECT_ID/functions" \
  -H "Authorization: Bearer $PLATFORM_TOKEN" \
  -F "name=hello" \
  -F "runtime=nodejs24.x" \
  -F "handler=handler" \
  -F "code=@function.zip"

Response format

Success responses

Single resource:

{
  "id": "proj_abc123",
  "name": "my-project",
  "status": "active",
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-15T10:30:00Z"
}

Paginated list:

{
  "data": [
    { "id": "proj_abc123", "name": "project-1" },
    { "id": "proj_def456", "name": "project-2" }
  ],
  "page": 1,
  "limit": 10,
  "total": 25,
  "has_more": true,
  "next": "/projects?page=2&limit=10"
}

Error responses

{
  "error": "project not found"
}

HTTP status codes

Pagination

List endpoints support pagination with page and limit parameters:

curl "https://api.volcano.dev/projects?page=2&limit=20" \
  -H "Authorization: Bearer $PLATFORM_TOKEN"

The response includes pagination metadata:

{
  "data": [...],
  "page": 2,
  "limit": 20,
  "total": 45,
  "has_more": true,
  "next": "/projects?page=3&limit=20"
}

Rate limiting

The user authentication endpoints are rate limited per project and client IP, in hourly windows you configure per project. They report the quota on every response:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 73

Over the limit they return 429:

HTTP/1.1 429 Too Many Requests
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1704128400

X-RateLimit-Reset is a Unix timestamp for the end of the window. /auth/signup, /auth/forgot-password, /auth/reset-password, and /auth/user/change-email send it on a 429; /auth/signin and /auth/refresh do not.

No other endpoint sends these headers. Project management endpoints are not rate limited, so a request with a valid token is never refused for its rate. Project locks and function invocation have their own limits and return 429 without these headers.

One case does return 429 without a quota header: repeatedly presenting credentials that are not recognized. Each unrecognized value has to be checked, so a client working through many of them is rationed per source. Retry with a credential that works, or check the token still exists — a valid token is answered from cache and never counts against this.

Every response says which build and region answered:

X-Volcano-Version: <version>                  # production
X-Volcano-Version: <env>-<version>            # non-production (e.g. staging-xyz)
X-Volcano-Region: us-east-1                   # the region that served the request

Volcano's internal headers are never returned.

Capabilities

Some capabilities are not available in every environment. Check which ones accept new work before offering them:

curl "https://api.volcano.dev/capabilities"

{
  "data": [
    { "id": "sandboxes", "status": "available" },
    { "id": "sandboxes.sessions", "status": "available" },
    { "id": "sandboxes.custom_templates", "status": "unavailable" },
    { "id": "issues", "status": "available" },
    { "id": "lavaflow", "status": "unavailable" },
    { "id": "lavaflow.merge", "status": "unavailable" },
    { "id": "functions.response_streaming", "status": "available" },
    { "id": "frontend_routes", "status": "available" },
    { "id": "frontends.candidates", "status": "unavailable" },
    { "id": "databases.migrations", "status": "available" }
  ]
}

The endpoint needs no token, and every caller in an environment gets the same answer. While a capability is unavailable, requests that start new work answer 404, or 400 for a single field or option, with code feature_unavailable:

{ "error": "sandboxes are not available", "code": "feature_unavailable" }

Reading, deleting, and terminating what already exists keep working unless the whole feature is absent from the environment. Treat a missing capability or an unknown status as unavailable, and refresh the list when a route answers feature_unavailable. A capability under another, such as sandboxes.sessions, is unavailable whenever its parent is. A 503 is a temporary outage, not an unavailable capability; retry it.

Capabilities for one project

Some capabilities are offered to some projects and not others. A project's list has the same entries, and answers those per project:

curl "https://api.volcano.dev/projects/$PROJECT_ID/capabilities" \
  -H "Authorization: Bearer $PLATFORM_TOKEN"

{
  "data": [
    { "id": "sandboxes", "status": "available" },
    { "id": "issues", "status": "available" },
    { "id": "lavaflow", "status": "available" }
  ]
}

The response is shortened here; it lists every capability.

lavaflow is available there when LavaFlow is released, offered to the project's owner, and included in the owner's plan. Where it isn't, the entry says what the project can still do:

lavaflow.merge is available when lavaflow is and LavaFlow may merge fixes in the environment. read_only appears only in a project's list, and has no code. On an unavailable entry, a code names the error code its refused requests answer with; treat an unknown code as absent. Every other entry matches GET /capabilities. Any project credential can read it, including a read-only project access token.

functions.response_streaming refuses nothing. While it is unavailable, a function's own URL sends a streamed response whole, once the function finishes. A response sent whole is limited to 6 MiB, headers included; a larger one fails the invocation.

CLI version gating

A CLI reports its version via the X-Volcano-CLI-Version request header. The API can reply with these instructions:

• X-Volcano-CLI-Instruction: suggestion_version_upgrade, require_version_upgrade, low_credit_warning, or not_enough_credit.
• X-Volcano-Credit-URL: the billing page address sent with a credit instruction.
• X-Volcano-Device-Instruction: reauth.

Deprecated CLI versions are blocked with 426 Upgrade Required. Credit instructions explain the account state but do not block a request. Requests without the version header are unaffected. See CLI Version Gating.

API endpoints

Projects

See Projects for details, and Git deploy for deployment runs.

Functions

See Functions for details.

Durable functions

Durable functions are a separate collection: a standard function's id is 404 here, and a durable function's id is 404 under /projects/{id}/functions. See Durable functions for details, Durable approvals for the approval endpoints, and Durable callbacks for the callback endpoints.

Issues

Issues are in preview. See Issues.

LavaFlow

Each endpoint names one project with project_id: a query parameter on reads, a body field on PUT. LavaFlow is in preview and needs the SUPERAGENT plan. See LavaFlow.

Notifications

See Notifications API and Notifications.

Frontends

See Frontend Endpoints for details.

Databases

See Databases for details.

Project locks

These endpoints accept service-role keys only. See Project locks.

Authentication

See Auth endpoints for details.

Service keys

Anon keys

Project access tokens

Creating, listing, reading, and revoking require a platform token: a project access token cannot manage project access tokens. The usage endpoints are ordinary project reads. See Project access tokens.

MCP

This endpoint takes its project from the credential, so it accepts a project access token only. See MCP server.

What's next