Vaquill AI · Schema

Operation

One long-running operation, whatever kind of work it is. Readable for `OPERATION_RETENTION_DAYS` after creation, per AIP-151.

LegalStatutesRegulationsLegal ResearchLawComplianceLegal TechGovernment DataMCPIndiaContracts

Properties

Name Type Description
id string Public identifier, `op_` followed by 32 hex characters. Poll `GET /v1/operations/{operationId}` with it.
type string What kind of work this is, for example `matrix.run` or `draft.generate`.
status object One of five values: `queued`, `running`, `succeeded`, `failed`, `cancelled`. There is no sixth and there are no synonyms. Stop polling once it is `succeeded`, `failed` or `cancelled`.
createdAt string When the operation was accepted (RFC 3339).
completedAt object When the operation reached a terminal status (RFC 3339). Present if and only if the status is terminal.
matterId object `mat_` identifier of the matter this work belongs to, when it belongs to one.
resource object What the operation produced. Absent until the underlying job row exists, which an idempotent replay can briefly observe, so treat absence as 'not yet' rather than 'never'.
error object Why the work failed. Present only when `status` is `failed`. Partial success is `succeeded` with `progress.done < progress.total`, never an error.
progress object How far along the work is, when the underlying job reports it. Absent does not mean no progress.
requestId object The `X-Request-ID` of the request that created this operation. Quote it in a support ticket.
View JSON Schema on GitHub

JSON Schema

vaquill-ai-operation-schema.json Raw ↑
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/vaquill-ai/json-schema/vaquill-ai-operation-schema.json",
  "title": "Operation",
  "description": "One long-running operation, whatever kind of work it is.\n\nReadable for `OPERATION_RETENTION_DAYS` after creation, per AIP-151.",
  "x-generated": "2026-11-10",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/vaquill-ai-comparisons-api-openapi.yml#/components/schemas/Operation",
  "properties": {
    "id": {
      "type": "string",
      "title": "Id",
      "description": "Public identifier, `op_` followed by 32 hex characters. Poll `GET /v1/operations/{operationId}` with it."
    },
    "type": {
      "type": "string",
      "title": "Type",
      "description": "What kind of work this is, for example `matrix.run` or `draft.generate`."
    },
    "status": {
      "$ref": "#/$defs/OperationStatus",
      "description": "One of five values: `queued`, `running`, `succeeded`, `failed`, `cancelled`. There is no sixth and there are no synonyms. Stop polling once it is `succeeded`, `failed` or `cancelled`."
    },
    "createdAt": {
      "type": "string",
      "format": "date-time",
      "title": "Createdat",
      "description": "When the operation was accepted (RFC 3339)."
    },
    "completedAt": {
      "anyOf": [
        {
          "type": "string",
          "format": "date-time"
        },
        {
          "type": "null"
        }
      ],
      "title": "Completedat",
      "description": "When the operation reached a terminal status (RFC 3339). Present if and only if the status is terminal."
    },
    "matterId": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Matterid",
      "description": "`mat_` identifier of the matter this work belongs to, when it belongs to one."
    },
    "resource": {
      "anyOf": [
        {
          "$ref": "#/$defs/OperationResource"
        },
        {
          "type": "null"
        }
      ],
      "description": "What the operation produced. Absent until the underlying job row exists, which an idempotent replay can briefly observe, so treat absence as 'not yet' rather than 'never'."
    },
    "error": {
      "anyOf": [
        {
          "$ref": "#/$defs/OperationError"
        },
        {
          "type": "null"
        }
      ],
      "description": "Why the work failed. Present only when `status` is `failed`. Partial success is `succeeded` with `progress.done < progress.total`, never an error."
    },
    "progress": {
      "anyOf": [
        {
          "$ref": "#/$defs/OperationProgress"
        },
        {
          "type": "null"
        }
      ],
      "description": "How far along the work is, when the underlying job reports it. Absent does not mean no progress."
    },
    "requestId": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Requestid",
      "description": "The `X-Request-ID` of the request that created this operation. Quote it in a support ticket."
    }
  },
  "additionalProperties": false,
  "type": "object",
  "required": [
    "id",
    "type",
    "status",
    "createdAt"
  ],
  "$defs": {
    "OperationError": {
      "properties": {
        "code": {
          "type": "string",
          "title": "Code",
          "description": "Stable, machine-readable failure code. Branch on this, never on `message`."
        },
        "message": {
          "type": "string",
          "title": "Message",
          "description": "Human-readable explanation, sanitized of internal paths and stack frames. Wording may change; do not parse it."
        }
      },
      "additionalProperties": false,
      "type": "object",
      "required": [
        "code",
        "message"
      ],
      "title": "OperationError",
      "description": "Why a failed operation failed, in terms a customer can act on.\n\n`code` is stable and machine-readable. `message` is sanitized: the internal\njob tables store stack traces and file paths in their `error_message`\ncolumns, and forwarding those verbatim leaks our internals into a customer's\nlogs."
    },
    "OperationProgress": {
      "properties": {
        "done": {
          "type": "integer",
          "minimum": 0.0,
          "title": "Done",
          "description": "How many units are finished."
        },
        "total": {
          "type": "integer",
          "minimum": 0.0,
          "title": "Total",
          "description": "How many units there are in total. Can legitimately be zero for an empty run."
        },
        "unit": {
          "type": "string",
          "enum": [
            "cells",
            "steps",
            "documents",
            "files",
            "rows",
            "percent"
          ],
          "title": "Unit",
          "description": "What `done` and `total` are counting. Always read it: a workflow run counts `percent` while a matrix run counts `cells`, so `{done: 43, total: 100}` alone is ambiguous."
        }
      },
      "additionalProperties": false,
      "type": "object",
      "required": [
        "done",
        "total",
        "unit"
      ],
      "title": "OperationProgress",
      "description": "How far along, and in what units.\n\nThe unit is not decoration. A workflow run stores only a percentage while a\nmatrix run stores cell counts, so `{done: 43, total: 100}` with no unit reads\nas 43 of 100 documents and a client builds a wrong estimate from it."
    },
    "OperationResource": {
      "properties": {
        "kind": {
          "type": "string",
          "title": "Kind",
          "description": "What sort of thing was produced, for example `matrix` or `document`."
        },
        "id": {
          "type": "string",
          "title": "Id",
          "description": "Public identifier of the produced resource, carrying its own type prefix, for example `mtx_` for a matrix."
        },
        "url": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Url",
          "description": "Path on this API where the resource can be read, RELATIVE to the API root and never absolute. Absent when the resource has no addressable path, which happens for work started outside a matter. Absent means the id is real and there is nowhere to GET it; it is not an error."
        }
      },
      "additionalProperties": false,
      "type": "object",
      "required": [
        "kind",
        "id"
      ],
      "title": "OperationResource",
      "description": "What the operation produced, or is producing.\n\n`url` is a path on this API rather than an absolute URL, because the service\nis mounted today and gets its own hostname later (docs 07.5). A relative\npath survives that move; a baked-in host does not."
    },
    "OperationStatus": {
      "type": "string",
      "enum": [
        "queued",
        "running",
        "succeeded",
        "failed",
        "cancelled"
      ],
      "title": "OperationStatus",
      "description": "The public five. There is no sixth, and there are no synonyms.\n\nInternal vocabularies spell terminal success `completed`, `ready`,\n`extracted`, `succeeded` and `fresh`; terminal failure `failed` and `error`;\nqueued `pending`, `queued` and `draft`. All of that is collapsed here by\n`app.workspace_api.adapters.status_map`, which refuses to guess."
    }
  }
}

Work with this as data

Every JSON Schema here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for schemas

4 MCP tools reach this
  • find_json_schemasBrowse and filter every JSON Schema in the catalog.
  • 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.
All 92 tools →

Call it yourself

curl for this page
This JSON Schema
curl "https://apis.io/api/v1/json-schemas/vaquill-ai-operation"
All schemas
curl "https://apis.io/api/v1/json-schemas?limit=25"

Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.

Get an API 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. See our Privacy Policy and Terms.

A second provider on the same verified email joins the account you already have.