API Reference
Drive VULK from your own code — the REST API at app.vulk.dev/api/v1 is included in every plan.
API access is included in every VULK plan — Builder, Pro, Max, Team, Business and Enterprise. Create a key in Settings › API keys and start calling.
The VULK API lets a script, a server or an AI agent do what you do in the studio: list and read your projects, start a build from a brief, send the next instruction to a project, follow the build, read the delivered files, and read your plan and usage. It is the same engine, the same plan and the same credits as the editor.
Quick start
# 1. Create a key at https://app.vulk.dev/settings?tab=ApiKeys (it starts with vk_sk_ and is shown once)
# 2. Call the API with it
curl https://app.vulk.dev/api/v1/projects \
-H "Authorization: Bearer vk_sk_your_key_here"GET https://app.vulk.dev/api/v1 needs no key and answers with the list of endpoints, the scopes and where keys are created.
Endpoints
Every endpoint, with request and response shapes, scopes, errors and rate limits
API keys
Create keys, choose their scopes, revoke them — and how keys from the previous workspace carry over
Webhooks
How to follow a build today, and where webhooks stand
MCP Integration
Use VULK from Claude, ChatGPT, Codex, Cursor or Windsurf
Calling the API from TypeScript
A small typed client over fetch — no package to install
Endpoints
| Method | Endpoint | Scope | What it does |
|---|---|---|---|
GET | /api/v1 | none | The index: endpoints, scopes, where keys are created |
GET | /api/v1/projects | projects.read | List your projects, newest first (limit, offset) |
POST | /api/v1/projects | projects.write | Start a project from a brief — answers an admission receipt |
GET | /api/v1/projects/:id | projects.read | Describe one project: versions, files, preview and live URLs |
DELETE | /api/v1/projects/:id | projects.write | Delete a project |
GET | /api/v1/projects/:id/files | export.read | List the delivered files, or read one with ?path= |
POST | /api/v1/projects/:id/messages | projects.write | Send the next instruction to a project |
GET | /api/v1/operations/:requestId | projects.read | Read an operation: status, replies, questions, links |
POST | /api/v1/operations/:requestId/stop | projects.write | Ask an operation to stop |
GET | /api/v1/models | projects.read | The models your account may generate with, and their credit cost |
GET | /api/v1/usage | usage.read | Plan, credit balance and the last 30 days |
Authentication
Every request except the index carries a Bearer token:
Authorization: Bearer vk_sk_your_api_keyKeys are created in Settings › API keys at app.vulk.dev/settings?tab=ApiKeys. A request without a key, or with a key that was revoked or has expired, is answered with 401 and a WWW-Authenticate: Bearer realm="VULK API" header.
Rate limits
Each key may make 60 requests per minute. Every authenticated answer carries the counters:
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 58
X-RateLimit-Reset: 1760360400X-RateLimit-Reset is a Unix time in seconds. Past the limit the API answers 429 with a Retry-After header and { "error": "Rate limit exceeded", "code": "RATE_LIMITED", "status": 429, "retryAfter": 23 }.
Credits
Starting a project or sending an instruction spends the credits of your plan exactly as the same request typed into the editor would. Reading — projects, files, operations, models, usage — never starts a generation and never spends credits. When your plan or balance cannot cover a request the API answers 402.
The previous API
The API of the previous VULK workspace keeps serving at https://vulk.dev/api/v1 (OpenAPI document at vulk.dev/openapi.json), with its own response shapes, for integrations built against it — including the vulk-mcp-server npm package. New integrations should use https://app.vulk.dev/api/v1, described here. Keys created in the previous workspace work on both.