Projects API
Manage projects via REST API.
Manage projects via REST API.
Authentication: Platform user token
List Projects
GET /projects
Authorization: Bearer <platform_token>Query Parameters:
page- Page number (default: 1)limit- Items per page (default: 10, max: 100)
Response:
{
"data": [
{
"id": "uuid",
"name": "my-app",
"status": "active",
"created_at": "2024-01-01T00:00:00Z",
"updated_at": "2024-01-01T00:00:00Z"
}
],
"page": 1,
"limit": 10,
"total": 1,
"has_more": false
}Get Project
GET /projects/{id}
Authorization: Bearer <platform_token>Response:
{
"id": "uuid",
"name": "my-app",
"status": "active",
"all_regions": true,
"selected_regions": ["us-east-1", "us-west-2"],
"aws_application_name": "volcano-uuid",
"created_at": "2024-01-01T00:00:00Z",
"updated_at": "2024-01-01T00:00:00Z"
}Create Project
POST /projects
Authorization: Bearer <platform_token>
Content-Type: application/jsonRequest:
{
"name": "my-app",
"all_regions": true
}To restrict a project to specific regions (PRO plan):
{
"name": "my-app",
"all_regions": false,
"selected_regions": ["us-east-1"]
}Response: 201 Created
{
"id": "uuid",
"name": "my-app",
"status": "active",
"all_regions": true,
"selected_regions": ["us-east-1", "us-west-2"],
"created_at": "2024-01-01T00:00:00Z",
"updated_at": "2024-01-01T00:00:00Z"
}Limit: Each user can create up to 1,000 projects. Requests over this cap return 403 Forbidden.
Update Project
PATCH /projects/{id}
Authorization: Bearer <platform_token>
Content-Type: application/jsonUpdate only the fields you need.
Name-only update (keeps existing region policy):
{
"name": "my-renamed-app"
}Switch to single-region deployment policy:
{
"all_regions": false,
"selected_regions": ["us-east-1"]
}Response: 200 OK with updated project.
Delete Project
DELETE /projects/{id}
Authorization: Bearer <platform_token>Response: 202 Accepted
Project deletion is asynchronous. After the request is accepted, GET /projects/{id} and GET /projects show status: "deleting" while cleanup is running. When cleanup finishes, the project no longer appears in lists and GET /projects/{id} returns 404.
Warning: Deletes all frontends, functions, databases, auth users, tokens, and variables in the project.
Export Project Configuration
GET /projects/{id}/config
Authorization: Bearer <platform_token>Exports the project's current user-facing configuration as a declarative
manifest (see the configuration manifest reference).
Returns JSON by default; request the canonical volcano-config.yaml rendering
with Accept: application/yaml or ?format=yaml. Write-only secrets (SMTP
password, OAuth client secrets, TLS material) are omitted.
Response: 200 OK with the manifest.
Apply Project Configuration
PUT /projects/{id}/config
Authorization: Bearer <platform_token>
Content-Type: application/jsonValidates and applies a configuration manifest, reconciling each declared
section server-side. Add ?dry_run=true to get the projected report without
changing anything.
Response: 200 OK with a per-resource report:
{
"results": [
{"section": "variables", "name": "STRIPE_SECRET_KEY", "action": "created"},
{"section": "realtime", "action": "updated", "notice": "disabling realtime drops active websocket connections"}
],
"skipped": [{"type": "function", "name": "hello", "reason": "not deployed"}],
"missing": [{"type": "bucket", "name": "avatars"}],
"summary": {"created": 1, "updated": 1, "deleted": 0, "unchanged": 0, "errors": 0, "skipped": 1, "missing": 1}
}skipped/missingare coverage warnings for functions, frontends, databases, and buckets (the manifest never creates or deletes them).- Validation failures return 422 with the full error list; nothing is applied.
- A concurrent apply for the same project returns 409.
- Apply-phase failures surface as per-entry
action: "error"withsummary.errors > 0; applied changes are not rolled back. - The request body is capped at 4 MiB (hosted pages, template bodies, and TLS PEMs fit comfortably; larger bodies are rejected with 400).
Get Project Usage
GET /projects/{id}/usage
Authorization: Bearer <platform_token>Returns the current-month total, the lifetime (all-time) total, and recent daily/hourly series for each tracked metric, plus a per-frontend request breakdown for the current usage period.
Response:
{
"project_id": "uuid",
"month": "2026-04",
"metrics": [
{
"metric": "Function Invocations",
"total": 1234,
"all_time": 98765,
"daily": [{ "timestamp": "2026-04-26T00:00:00Z", "value": 42 }],
"hourly": [{ "timestamp": "2026-04-27T20:00:00Z", "value": 3 }]
},
{
"metric": "Frontend Requests",
"total": 9876,
"all_time": 543210,
"daily": [{ "timestamp": "2026-04-26T00:00:00Z", "value": 321 }],
"hourly": [{ "timestamp": "2026-04-27T20:00:00Z", "value": 18 }]
}
],
"frontends": [
{
"frontend_id": "uuid",
"frontend_name": "marketing-site",
"requests": 6200
},
{
"frontend_id": "uuid",
"frontend_name": "docs-site",
"requests": 3676
}
]
}Project Status
active- Ready to usedeleting- Deletion accepted; cleanup is still runningfailed- Asynchronous deletion cleanup failed and can be retried
Region Policy Notes
all_regions: truedeploys functions to all configured regions.all_regions: false+selected_regionslimits function deployments to that subset.- Changing region policy is asynchronous; function deployments converge to the new region set.