Back
API & MCP

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/v1

GET /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 /projects and POST /projects/:id/messages spend the credits of your plan, as the same brief typed into the editor would.
  • Every authenticated answer carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset (Unix seconds).
  • Project ids are the ids GET /projects returns. A project on another account answers 404, never 403.

Projects

List projects

GET /api/v1/projects?limit=20&offset=0

Scope projects.read. Newest first.

ParameterTypeDefaultDescription
limitinteger20How many to return, 1 to 100
offsetinteger0How 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/json

Scope 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"
}
FieldTypeRequiredDescription
promptstringYesThe brief, 1 to 8,000 characters, in any language. It is handed to VULK unchanged.
modelstringNoA model id from GET /models, or auto. Omit it to let VULK choose.
requestIdstringNoA 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/:id

Scope 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/:id

Scope 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.tsx

Scope 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/json

Scope 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/:requestId

Scope 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
}
FieldValues
operationStatusrunning 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
stopStatusrunning · stopping after a stop request · stopped once honoured · already-delivered when the work finished first
decisionGENERATE built · RESPOND answered in words · CLARIFY asked questions · ERROR failed · null while undecided
pendingProvidertrue while an already accepted provider call may still finish and use credits
responsesVULK'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/stop

Scope 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/models

Scope 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/usage

Scope 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: 1760360400

Past 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 }
StatusCodeWhen
400VALIDATION_ERRORA parameter or body field is wrong; the sentence names it
401UNAUTHORIZEDNo key, a malformed key, or a revoked or expired one. The answer carries WWW-Authenticate: Bearer realm="VULK API"
402PAYMENT_REQUIREDThe plan or credit balance does not cover the request
403FORBIDDENThe key lacks the scope the endpoint needs
404NOT_FOUNDNo such endpoint, project, operation or file on this account
405METHOD_NOT_ALLOWEDThe path exists, not with that verb; Allow lists the verbs
409CONFLICTThe project has no delivered version with files yet
413PAYLOAD_TOO_LARGEThe body is over 64 KB
429RATE_LIMITEDOver 60 requests in a minute; wait retryAfter seconds
500SERVER_ERRORVULK failed; retry later
503SERVICE_UNAVAILABLEGeneration or a dependency is temporarily unavailable; nothing was submitted

Troubleshooting each one: API authentication issues.

Following a build

  1. POST /projects with the brief and a requestId you keep.
  2. GET /operations/:requestId every few seconds while operationStatus is running.
  3. On waiting, show the questions to the person and send the answer with POST /projects/:id/messages.
  4. On done, read currentProjectPreviewUrl, the files with GET /projects/:id/files, or open editorUrl.

The same loop is what the MCP connector runs for an AI assistant. There are no webhooks for build progress today — see Webhooks.

On this page

VULK Support

Online

Hi! How can I help you today?

Popular topics

AI support • support.vulk.dev