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

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.

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.

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