API Endpoints
Every endpoint of the VULK REST API at app.vulk.dev/api/v1 — requests, responses, scopes, errors and rate limits.
The API is included in every VULK plan. Keys are created in Settings › API keys at app.vulk.dev/settings?tab=ApiKeys.
Base URL
https://app.vulk.dev/api/v1GET /api/v1 answers without a key: the base URL, the scopes, where keys are created and the list of endpoints below.
Authentication
Send the key as a Bearer token on every other request:
curl https://app.vulk.dev/api/v1/projects \
-H "Authorization: Bearer vk_sk_your_key_here"Each endpoint needs one scope; a key without it is answered 403. The scopes and what they open are on the API keys page. The API answers requests from any origin (CORS); never put a key in browser code.
Conventions
- Request bodies are JSON, at most 64 KB. Responses are JSON in camelCase; dates are ISO 8601 in UTC.
- Reads never start a generation and never spend credits.
POST /projectsandPOST /projects/:id/messagesspend the credits of your plan, as the same brief typed into the editor would. - Every authenticated answer carries
X-RateLimit-Limit,X-RateLimit-RemainingandX-RateLimit-Reset(Unix seconds). - Project ids are the ids
GET /projectsreturns. A project on another account answers404, never403.
Projects
List projects
GET /api/v1/projects?limit=20&offset=0Scope projects.read. Newest first.
| Parameter | Type | Default | Description |
|---|---|---|---|
limit | integer | 20 | How many to return, 1 to 100 |
offset | integer | 0 | How many to skip, 0 to 1000 |
{
"projects": [
{
"id": "cmgp3x8d7000a0wz4h2k1qv9r",
"title": "Bakery landing page",
"kind": "app",
"createdAt": "2026-10-13T09:12:44.000Z",
"url": "https://app.vulk.dev/chat/cmgp3x8d7000a0wz4h2k1qv9r"
}
],
"count": 1,
"pagination": { "limit": 20, "offset": 0, "count": 1, "hasMore": false }
}kind is app for a website or app, or image, video or mesh for a standalone design asset. url is the project's page in the editor.
Create a project
POST /api/v1/projects
Content-Type: application/jsonScope projects.write. Starts a build from a brief and answers an admission receipt: the build runs after the answer, and you follow it with GET /operations/:requestId.
{
"prompt": "A landing page for a bakery in Porto: hero with the shop, the week's bread, opening hours, a map and a contact form.",
"model": "auto",
"requestId": "7a1c0b7e-6a0f-4b0e-9a63-0f5c1b2d3e4f"
}| Field | Type | Required | Description |
|---|---|---|---|
prompt | string | Yes | The brief, 1 to 8,000 characters, in any language. It is handed to VULK unchanged. |
model | string | No | A model id from GET /models, or auto. Omit it to let VULK choose. |
requestId | string | No | A UUID v4 you make. Send the same requestId to retry a submit whose answer was lost: the API returns the operation it already created instead of starting a second one. Omitted, VULK makes one. |
202 Accepted
{
"requestId": "7a1c0b7e-6a0f-4b0e-9a63-0f5c1b2d3e4f",
"accepted": true,
"operationStatus": "running",
"projectId": "cmgp3x8d7000a0wz4h2k1qv9r",
"editorUrl": "https://app.vulk.dev/chat/cmgp3x8d7000a0wz4h2k1qv9r",
"nextAction": "Read GET /operations/7a1c0b7e-… until operationStatus is done, waiting or failed."
}accepted: false with operationStatus: "unconfirmed" means VULK had not recorded the operation within the wait: read the operation, then retry with exactly the same requestId and body. A retry of an already accepted requestId answers 200 with the operation state. A brief the plan or balance cannot cover answers 402.
Read a project
GET /api/v1/projects/:idScope projects.read.
{
"id": "cmgp3x8d7000a0wz4h2k1qv9r",
"title": "Bakery landing page",
"folder": "bakery-landing-page",
"versions": 3,
"versionsWithFiles": 2,
"files": 14,
"bytes": 48213,
"lastVersionStatus": "delivered",
"lastVersionError": null,
"siteName": null,
"previewUrl": "https://preview.vulk.dev/…",
"liveUrl": null,
"url": "https://app.vulk.dev/chat/cmgp3x8d7000a0wz4h2k1qv9r"
}versions counts the builds; files and bytes describe the latest one. lastVersionStatus is a word such as delivered or failed, and lastVersionError an error code when it failed. siteName and liveUrl are null while the project is unpublished — publishing is done in the editor.
Delete a project
DELETE /api/v1/projects/:idScope projects.write. Deletes the project; the action is recorded against the key.
{ "success": true, "id": "cmgp3x8d7000a0wz4h2k1qv9r", "deletedAt": "2026-10-13T10:02:11.000Z" }Read the files
GET /api/v1/projects/:id/files
GET /api/v1/projects/:id/files?path=src/App.tsxScope export.read. Without path, lists the files of the project's delivered version; with path, returns one file.
{
"projectId": "cmgp3x8d7000a0wz4h2k1qv9r",
"version": 3,
"files": [
{ "path": "index.html", "bytes": 2210 },
{ "path": "src/App.tsx", "bytes": 6180 }
],
"totalFiles": 14,
"totalBytes": 48213,
"truncated": false
}{
"projectId": "cmgp3x8d7000a0wz4h2k1qv9r",
"path": "src/App.tsx",
"bytes": 6180,
"content": "import { useState } from 'react';\n…",
"truncated": false
}A file longer than 200,000 characters is cut and truncated is true. A project that has not delivered a version with files yet answers 409; a path that is not in the project answers 404. Reading files needs a plan with source export; otherwise the API answers 402.
Send the next instruction
POST /api/v1/projects/:id/messages
Content-Type: application/jsonScope projects.write. The same body and the same receipt as Create a project, applied to an existing project: prompt is the next instruction, model and requestId are optional.
{ "prompt": "Add a pricing section under the hero with three cards." }Operations
A requestId identifies one build or one instruction. Reading it is free and safe to repeat.
Read an operation
GET /api/v1/operations/:requestIdScope projects.read.
{
"requestId": "7a1c0b7e-6a0f-4b0e-9a63-0f5c1b2d3e4f",
"projectId": "cmgp3x8d7000a0wz4h2k1qv9r",
"operationStatus": "waiting",
"stopStatus": "running",
"pendingProvider": false,
"decision": "CLARIFY",
"startedAt": "2026-10-13T09:12:45.000Z",
"finishedAt": null,
"editorUrl": "https://app.vulk.dev/chat/cmgp3x8d7000a0wz4h2k1qv9r",
"currentProjectPreviewUrl": null,
"currentProjectLiveUrl": null,
"responses": [
{
"text": "Before I build: which of these should the hero show?",
"questions": [
{ "question": "What should the hero show?", "options": ["A photo of the shop", "The bread of the week", "Both"] }
]
}
],
"responsesTruncated": false
}| Field | Values |
|---|---|
operationStatus | running while VULK works · waiting when a question needs your answer · done · failed · orphan when the process ended without a result · null before the operation was registered |
stopStatus | running · stopping after a stop request · stopped once honoured · already-delivered when the work finished first |
decision | GENERATE built · RESPOND answered in words · CLARIFY asked questions · ERROR failed · null while undecided |
pendingProvider | true while an already accepted provider call may still finish and use credits |
responses | VULK's replies to this instruction, the latest ones, at most 12; questions is present when VULK is waiting for a choice. responsesTruncated is true when replies were left out or cut. |
To answer a question, send the answer as the next instruction with POST /projects/:id/messages.
Stop an operation
POST /api/v1/operations/:requestId/stopScope projects.write. Asks the operation to stop and answers the operation state above. Work a provider has already accepted may still finish and use credits (pendingProvider). Asking twice is safe.
Models
GET /api/v1/modelsScope projects.read. The models your account may generate with, as the editor's model picker shows them.
{
"models": [
{
"id": "auto",
"name": "Auto",
"description": "VULK picks the model for the brief.",
"provider": "VULK",
"group": "recommended",
"credits": 1,
"inputs": ["text", "image"],
"locked": false,
"lockReason": null,
"requiredPlan": null
}
],
"count": 1
}credits is what one generation with the model costs. A model your plan does not include has locked: true, a lockReason and the requiredPlan that unlocks it; sending it to POST /projects answers 402.
Usage
GET /api/v1/usageScope usage.read.
{
"plan": "Pro",
"status": "active",
"billingInterval": "month",
"monthlyCredits": 400,
"renewsAt": "2026-11-01T00:00:00.000Z",
"creditBalance": 312.5,
"creditsUsedLast30Days": 87.5,
"generationsLast30Days": 41,
"failedGenerationsLast30Days": 2,
"modelsUsedLast30Days": ["auto", "anthropic/claude-sonnet-5-5"]
}status is active, trialing, past_due or none. plan, billingInterval, monthlyCredits and renewsAt are null without a subscription.
Rate limits
Each key may make 60 requests per minute.
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 42
X-RateLimit-Reset: 1760360400Past the limit:
HTTP/1.1 429 Too Many Requests
Retry-After: 23
{ "error": "Rate limit exceeded", "code": "RATE_LIMITED", "status": 429, "retryAfter": 23 }Errors
Every error has the same three fields; code is the value to branch on.
{ "error": "Missing API key. Send it as \"Authorization: Bearer vk_sk_…\". Keys are created in Settings › API keys.", "code": "UNAUTHORIZED", "status": 401 }| Status | Code | When |
|---|---|---|
| 400 | VALIDATION_ERROR | A parameter or body field is wrong; the sentence names it |
| 401 | UNAUTHORIZED | No key, a malformed key, or a revoked or expired one. The answer carries WWW-Authenticate: Bearer realm="VULK API" |
| 402 | PAYMENT_REQUIRED | The plan or credit balance does not cover the request |
| 403 | FORBIDDEN | The key lacks the scope the endpoint needs |
| 404 | NOT_FOUND | No such endpoint, project, operation or file on this account |
| 405 | METHOD_NOT_ALLOWED | The path exists, not with that verb; Allow lists the verbs |
| 409 | CONFLICT | The project has no delivered version with files yet |
| 413 | PAYLOAD_TOO_LARGE | The body is over 64 KB |
| 429 | RATE_LIMITED | Over 60 requests in a minute; wait retryAfter seconds |
| 500 | SERVER_ERROR | VULK failed; retry later |
| 503 | SERVICE_UNAVAILABLE | Generation or a dependency is temporarily unavailable; nothing was submitted |
Troubleshooting each one: API authentication issues.
Following a build
POST /projectswith the brief and arequestIdyou keep.GET /operations/:requestIdevery few seconds whileoperationStatusisrunning.- On
waiting, show thequestionsto the person and send the answer withPOST /projects/:id/messages. - On
done, readcurrentProjectPreviewUrl, the files withGET /projects/:id/files, or openeditorUrl.
The same loop is what the MCP connector runs for an AI assistant. There are no webhooks for build progress today — see Webhooks.