vulk-dev Operations API
Follow or stop one build or one instruction by its requestId. Reading is free and safe to repeat.
Follow or stop one build or one instruction by its requestId. Reading is free and safe to repeat.
Every API here is available over the APIs.io API and to AI agents over MCP.
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.curl "https://apis.io/api/v1/apis/vulk-dev:vulk-dev-operations-api"
curl "https://apis.io/api/v1/apis?limit=25"
Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. By signing up you are subscribing to the APIs.io and API Evangelist newsletters — you can unsubscribe from any issue. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
openapi: 3.2.0
info:
title: VULK REST Operations API
summary: Build, continue and read VULK projects from any program or AI agent.
description: 'The VULK REST API drives the VULK generation engine with the same plan and
credits as the editor: start a project from a brief, send it the next
instruction, follow the operation, read the delivered files, the models
your account may use and your usage.
The API is included in every VULK plan. Keys are created in Settings › API
keys at https://app.vulk.dev/settings?tab=ApiKeys and sent as
`Authorization: Bearer vk_sk_`. Each key belongs to one account, carries
the scopes chosen when it was created (projects.read, projects.write,
export.read, usage.read), may make 60 requests per minute and can be revoked
at any time.
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. Request bodies are JSON of at most 64 KB;
answers are JSON in camelCase with ISO 8601 dates in UTC. GET /api/v1 answers
without a key with the list of endpoints.
Reference: https://support.vulk.dev/docs/api. Quickstart and MCP setup:
https://vulk.dev/developers.'
version: 2.0.0
contact:
name: VULK Support
url: https://vulk.dev/contact
email: support@vulk.dev
termsOfService: https://vulk.dev/terms-conditions
license:
name: Proprietary
url: https://vulk.dev/terms-conditions
servers:
- url: https://app.vulk.dev/api/v1
description: Production
security:
- ApiKeyAuth: []
tags:
- name: Operations
description: Follow or stop one build or one instruction by its requestId. Reading is free and safe to repeat.
paths:
/operations/{requestId}:
parameters:
- name: requestId
in: path
required: true
description: The requestId of one build or one instruction, as returned in its admission receipt.
schema:
type: string
format: uuid
get:
tags:
- Operations
operationId: getOperation
summary: Read an operation
description: 'Scope `projects.read`. The persisted state of one build or instruction: status, VULK''s replies or clarification questions, preview and editor links. Reading never starts, retries or charges a generation.'
responses:
'200':
description: The operation.
headers:
X-RateLimit-Limit:
$ref: '#/components/headers/X-RateLimit-Limit'
X-RateLimit-Remaining:
$ref: '#/components/headers/X-RateLimit-Remaining'
X-RateLimit-Reset:
$ref: '#/components/headers/X-RateLimit-Reset'
content:
application/json:
schema:
$ref: '#/components/schemas/Operation'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
'429':
$ref: '#/components/responses/RateLimited'
/operations/{requestId}/stop:
parameters:
- name: requestId
in: path
required: true
description: The requestId of one build or one instruction, as returned in its admission receipt.
schema:
type: string
format: uuid
post:
tags:
- Operations
operationId: stopOperation
summary: Stop an operation
description: Scope `projects.write`. Asks the operation to stop and answers its state. Work a provider has already accepted may still finish and use credits (`pendingProvider`). Asking twice is safe.
responses:
'200':
description: The operation, with `stopStatus` advanced.
headers:
X-RateLimit-Limit:
$ref: '#/components/headers/X-RateLimit-Limit'
X-RateLimit-Remaining:
$ref: '#/components/headers/X-RateLimit-Remaining'
X-RateLimit-Reset:
$ref: '#/components/headers/X-RateLimit-Reset'
content:
application/json:
schema:
$ref: '#/components/schemas/Operation'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
'429':
$ref: '#/components/responses/RateLimited'
components:
headers:
X-RateLimit-Remaining:
description: Requests left in the current minute.
schema:
type: integer
example: 42
X-RateLimit-Reset:
description: When the window resets, in Unix seconds.
schema:
type: integer
example: 1760360400
WWW-Authenticate:
description: Always `Bearer realm="VULK API"`.
schema:
type: string
example: Bearer realm="VULK API"
Retry-After:
description: Seconds to wait before the next request.
schema:
type: integer
example: 23
X-RateLimit-Limit:
description: Requests the key may make per minute.
schema:
type: integer
example: 60
responses:
Unauthorized:
description: No key, a malformed key, or a revoked or expired one (code UNAUTHORIZED).
headers:
WWW-Authenticate:
$ref: '#/components/headers/WWW-Authenticate'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
RateLimited:
description: Over 60 requests in a minute; wait `retryAfter` seconds (code RATE_LIMITED).
headers:
Retry-After:
$ref: '#/components/headers/Retry-After'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
NotFound:
description: No such endpoint, project, operation or file on this account (code NOT_FOUND).
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
Forbidden:
description: The key lacks the scope the endpoint needs (code FORBIDDEN).
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
schemas:
Error:
type: object
description: Every error has the same three fields; `code` is the value to branch on. A 429 also carries `retryAfter`.
properties:
error:
type: string
description: A sentence for the developer reading a log.
code:
type: string
enum:
- VALIDATION_ERROR
- UNAUTHORIZED
- PAYMENT_REQUIRED
- FORBIDDEN
- NOT_FOUND
- METHOD_NOT_ALLOWED
- CONFLICT
- PAYLOAD_TOO_LARGE
- RATE_LIMITED
- SERVER_ERROR
- SERVICE_UNAVAILABLE
status:
type: integer
retryAfter:
type: integer
description: Seconds to wait; only on 429.
required:
- error
- code
- status
example:
error: 'Missing API key. Send it as "Authorization: Bearer vk_sk_…". Keys are created in Settings › API keys.'
code: UNAUTHORIZED
status: 401
Operation:
type: object
properties:
requestId:
type: string
format: uuid
projectId:
type:
- string
- 'null'
operationStatus:
type:
- string
- 'null'
enum:
- running
- waiting
- done
- failed
- orphan
- null
description: '`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:
type: string
enum:
- running
- stopping
- stopped
- already-delivered
description: '`stopping` after a stop request, `stopped` once honoured, `already-delivered` when the work finished first.'
pendingProvider:
type: boolean
description: True while an already accepted provider call may still finish and use credits.
decision:
type:
- string
- 'null'
enum:
- GENERATE
- RESPOND
- CLARIFY
- ERROR
- null
description: 'How VULK answered: GENERATE built, RESPOND answered in words, CLARIFY asked questions, ERROR failed; null while undecided.'
startedAt:
type:
- string
- 'null'
format: date-time
finishedAt:
type:
- string
- 'null'
format: date-time
editorUrl:
type:
- string
- 'null'
format: uri
currentProjectPreviewUrl:
type:
- string
- 'null'
format: uri
currentProjectLiveUrl:
type:
- string
- 'null'
format: uri
responses:
type: array
description: VULK's replies to this instruction, the latest ones, at most 12.
items:
type: object
properties:
text:
type: string
questions:
type: array
description: Present when VULK is waiting for a choice; answer with POST /projects/{id}/messages.
items:
type: object
properties:
question:
type: string
options:
type: array
items:
type: string
required:
- question
- options
required:
- text
responsesTruncated:
type: boolean
description: True when replies were left out or cut.
required:
- requestId
- operationStatus
- stopStatus
- pendingProvider
- responses
- responsesTruncated
securitySchemes:
ApiKeyAuth:
type: http
scheme: bearer
bearerFormat: vk_sk_*
description: 'Create a key in Settings › API keys (https://app.vulk.dev/settings?tab=ApiKeys) and send it as `Authorization: Bearer vk_sk_<key>`. Each endpoint names the scope the key needs; a key without it is answered 403.'
externalDocs:
description: API reference — every endpoint, scopes, errors and rate limits
url: https://support.vulk.dev/docs/api