Operation

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/vulk-dev/json-schema/vulk-dev-operation-schema.json",
  "title": "Operation",
  "x-generated": "2026-10-30",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/vulk-dev-openapi.json#/components/schemas/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"
  ]
}