vulk-dev Operations API

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