vulk-dev Usage API

openapi: 3.2.0
info:
  title: VULK REST Usage 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: Usage
  description: Plan, credit balance and the last 30 days.
paths:
  /usage:
    get:
      tags:
      - Usage
      operationId: getUsage
      summary: Plan, credits and the last 30 days
      description: Scope `usage.read`.
      responses:
        '200':
          description: The account's plan and usage.
          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/Usage'
        '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:
    Usage:
      type: object
      description: '`plan`, `billingInterval`, `monthlyCredits` and `renewsAt` are null without a subscription.'
      properties:
        plan:
          type:
          - string
          - 'null'
          example: Pro
        status:
          type: string
          enum:
          - active
          - trialing
          - past_due
          - none
        billingInterval:
          type:
          - string
          - 'null'
          enum:
          - month
          - year
        monthlyCredits:
          type:
          - number
          - 'null'
        renewsAt:
          type:
          - string
          - 'null'
          format: date-time
        creditBalance:
          type: number
        creditsUsedLast30Days:
          type: number
        generationsLast30Days:
          type: integer
        failedGenerationsLast30Days:
          type: integer
        modelsUsedLast30Days:
          type: array
          items:
            type: string
      required:
      - status
      - creditBalance
      - creditsUsedLast30Days
      - generationsLast30Days
      - failedGenerationsLast30Days
      - modelsUsedLast30Days
    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