CapabilityRunRequest

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/beatapi/json-schema/beatapi-capability-run-request-schema.json",
  "title": "CapabilityRunRequest",
  "x-generated": "2026-10-30",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/beatapi-openapi.json#/components/schemas/CapabilityRunRequest",
  "type": "object",
  "required": [
    "reference"
  ],
  "properties": {
    "reference": {
      "type": "string",
      "pattern": "^(model|data|workflow):.+$",
      "description": "The inspected reference",
      "copied exactly.": null
    },
    "operation": {
      "type": "string",
      "enum": [
        "start",
        "status",
        "result"
      ],
      "default": "start",
      "description": "`start`: run it. `status`: poll an async task (needs `task_id`; takes `view`, `max_items` and `fields` like start). `result`: fetch a finished result again, free within one hour (needs `request_id`)."
    },
    "input": {
      "type": "object",
      "additionalProperties": true,
      "description": "For start: the input, following the inspected `input_schema`. Text models: `{\"input\": \"<prompt or messages>\"}` with optional `instructions`, `max_output_tokens`, `temperature`. JEV: `{\"state\": …, \"questions\": …}`."
    },
    "task_id": {
      "type": "string",
      "description": "For status: the task id an async start returned."
    },
    "request_id": {
      "type": "string",
      "description": "For result: the `request_id` a sync start returned."
    },
    "view": {
      "type": "string",
      "enum": [
        "full",
        "preview"
      ],
      "description": "`full` (REST default): the whole result. `preview`: the result's main list lifted to `items` (the first `max_items` elements, each trimmed inside) with `items_path` and `items_total`, long strings shortened, `truncated` and `result_ref` reported."
    },
    "max_items": {
      "type": "integer",
      "minimum": 1,
      "maximum": 50,
      "description": "With `preview`: elements kept in `items` (default 10)."
    },
    "fields": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Keep only these paths. Paths starting `items[]` are read from each element of the result's list and returned as `items`, such as `items[].title`; other paths are dotted from the root, `[]` walks an array."
    },
    "idempotency_key": {
      "type": "string",
      "maxLength": 255,
      "description": "Unique per task, a top-level field next to `reference` and `input` (or the `Idempotency-Key` header); reuse only to retry the same start."
    }
  }
}