vulk-dev Models API

openapi: 3.2.0
info:
  title: VULK REST Models 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: Models
  description: The models your account may generate with, as the editor's picker shows them.
paths:
  /models:
    get:
      tags:
      - Models
      operationId: listModels
      summary: List the models your account may use
      description: Scope `projects.read`. Sending a `locked` model to POST /projects answers 402.
      responses:
        '200':
          description: The models, as the editor's picker shows them.
          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/ModelList'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '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'
    Forbidden:
      description: The key lacks the scope the endpoint needs (code FORBIDDEN).
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  schemas:
    ModelList:
      type: object
      properties:
        models:
          type: array
          items:
            $ref: '#/components/schemas/Model'
        count:
          type: integer
      required:
      - models
      - count
    Model:
      type: object
      description: '`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.'
      properties:
        id:
          type: string
          description: The value for `model` in POST /projects.
          example: auto
        name:
          type: string
          example: Auto
        description:
          type: string
        provider:
          type: string
          example: VULK
        group:
          type: string
          example: recommended
        credits:
          type: number
        inputs:
          type: array
          items:
            type: string
            enum:
            - text
            - image
        locked:
          type: boolean
        lockReason:
          type:
          - string
          - 'null'
        requiredPlan:
          type:
          - string
          - 'null'
      required:
      - id
      - name
      - locked
    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
  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