{
  "openapi": "3.1.0",
  "info": {
    "title": "NullProtocol Agent Execution API",
    "version": "1.2.0",
    "description": "Run saved agents or named saved tasks. Public Space SDK-key endpoints cover operations, saved-task management and synchronous task invocation. This does not cover the broader cabinet administration API. Saved tasks require API 0.25.0. A task keeps an operation with its schema, criteria or actions; runs use the current revision and report which one ran. External side effects remain in your application. No outbound webhook delivery or revision pinning is provided.",
    "contact": {
      "url": "https://github.com/stuseek/nullprotocol/issues"
    }
  },
  "servers": [
    {
      "url": "https://api.nullprotocol.ai",
      "description": "Production"
    }
  ],
  "externalDocs": {
    "url": "https://nullprotocol.ai/docs/http",
    "description": "HTTP quickstart, retries and automation guides"
  },
  "security": [
    {
      "SpaceKey": []
    }
  ],
  "tags": [
    {
      "name": "Agents",
      "description": "Run a saved agent. Your application executes external side effects."
    },
    {
      "name": "Saved tasks",
      "description": "Agent-owned operation settings, current revisions and input-only invocation. The cabinet uses separate member-authenticated paths; Viewers read, Owners/Editors write."
    }
  ],
  "paths": {
    "/v1/agents/{agentId}/run": {
      "post": {
        "operationId": "runAgent",
        "summary": "Execute one operation on a saved agent",
        "tags": [
          "Agents"
        ],
        "description": "Requires an SDK-scoped Space key, enabled hosted model access and sufficient credit. Maximum JSON body size is 131072 bytes. Preserve the same key, agent, Idempotency-Key and parsed input when retrying. A completed attempt replays its stored response, including stored failures, without generation. After a known completed refusal, fix the cause and deliberately choose a new attempt ID. Preserve the same ID after a network timeout, in_progress, rate_limited or busy. Inspect History before a new attempt after unknown outcomes or internal errors; changed object property order is ignored, array order is significant. Key rotation changes caller identity. Stored responses expire after 30 days; retained tombstones prevent silent re-execution. HTTP decide checks supplied parameter schemas and can repair invalid replies before success. Your application runs handlers and checks business rules.",
        "parameters": [
          {
            "name": "agentId",
            "in": "path",
            "required": true,
            "description": "Saved agent ID in the Space identified by the key.",
            "schema": {
              "type": "string",
              "pattern": "^[a-z0-9][a-z0-9._-]{0,63}$"
            },
            "example": "order-reader"
          },
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": true,
            "description": "Stable ID per task; reuse after timeout or network failure. Scoped to Space, agent and SDK key.",
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 128,
              "pattern": "^[!-~]+$"
            },
            "example": "order-42-read-v1"
          }
        ],
        "requestBody": {
          "required": true,
          "description": "One operation. Additional fields are rejected. Arbitrary JSON is accepted as task content; output schema validity is checked by the operation.",
          "content": {
            "application/json": {
              "schema": {
                "oneOf": [
                  {
                    "$ref": "#/components/schemas/ExtractInput"
                  },
                  {
                    "$ref": "#/components/schemas/SummarizeInput"
                  },
                  {
                    "$ref": "#/components/schemas/ValidateInput"
                  },
                  {
                    "$ref": "#/components/schemas/DecideInput"
                  }
                ],
                "discriminator": {
                  "propertyName": "operation",
                  "mapping": {
                    "extract": "#/components/schemas/ExtractInput",
                    "summarize": "#/components/schemas/SummarizeInput",
                    "validate": "#/components/schemas/ValidateInput",
                    "decide": "#/components/schemas/DecideInput"
                  }
                }
              },
              "examples": {
                "extract": {
                  "summary": "Read order fields",
                  "value": {
                    "operation": "extract",
                    "data": "Order 42: two blue mugs.",
                    "schema": {
                      "type": "object",
                      "properties": {
                        "orderId": {
                          "type": "number"
                        },
                        "quantity": {
                          "type": "number"
                        }
                      },
                      "required": [
                        "orderId",
                        "quantity"
                      ],
                      "additionalProperties": false
                    }
                  }
                },
                "summarize": {
                  "summary": "Summarize an incoming request",
                  "value": {
                    "operation": "summarize",
                    "content": "The parcel arrived late. One mug is cracked. Please send a replacement.",
                    "maxLength": 300,
                    "focus": "problem and requested resolution"
                  }
                },
                "validate": {
                  "summary": "Check a claim against a reference",
                  "value": {
                    "operation": "validate",
                    "criteria": "Every claim must agree with the supplied policy.",
                    "subject": "Gift cards are refundable.",
                    "reference": "Gift cards are not refundable."
                  }
                },
                "decide": {
                  "summary": "Prepare a choice for the application to execute",
                  "value": {
                    "operation": "decide",
                    "context": "Damage reported without a photo.",
                    "actions": [
                      {
                        "action": "request_photo",
                        "description": "Ask for a damage photo."
                      },
                      {
                        "action": "human_review",
                        "description": "Escalate to a person."
                      }
                    ]
                  }
                },
                "knowledge": {
                  "summary": "Read a fact from connected Knowledge",
                  "value": {
                    "operation": "extract",
                    "data": "How many days is the return window?",
                    "schema": {
                      "days": "number"
                    },
                    "knowledge": {
                      "query": "Return window for unused goods"
                    },
                    "conversation": "order:42"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Operation result. Inspect result.success: an operation refusal or model failure can also return HTTP 200. usage may be present on failure. operationId is null when no history row could be saved.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RunResponse"
                },
                "examples": {
                  "extracted": {
                    "value": {
                      "result": {
                        "success": true,
                        "data": {
                          "orderId": 42,
                          "quantity": 2
                        },
                        "attempts": 1,
                        "repaired": false,
                        "usage": {
                          "inputTokens": 180,
                          "outputTokens": 18
                        }
                      },
                      "operationId": "9cc8c09b-93e1-4e7c-bb12-2b12cfef1c68"
                    }
                  },
                  "refused": {
                    "value": {
                      "result": {
                        "success": false,
                        "errorCode": "documents_too_large",
                        "error": "The documents of this Agent take 6200 characters and the operation's document budget is 6000. Shorten them or set a larger documentBudget."
                      },
                      "operationId": "9cc8c09b-93e1-4e7c-bb12-2b12cfef1c68"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Malformed JSON, invalid fields or missing/invalid idempotency header.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HttpError"
                },
                "examples": {
                  "invalid_body": {
                    "value": {
                      "error": "invalid_body"
                    }
                  },
                  "Invalid JSON": {
                    "value": {
                      "error": "Invalid JSON"
                    }
                  },
                  "idempotency_key_required": {
                    "value": {
                      "error": "idempotency_key_required"
                    }
                  },
                  "invalid_request_id": {
                    "value": {
                      "error": "invalid_request_id"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "The SDK key is missing, invalid or revoked.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HttpError"
                },
                "examples": {
                  "unauthorized": {
                    "value": {
                      "error": "unauthorized"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "The key lacks the required SDK scope or access.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HttpError"
                },
                "examples": {
                  "forbidden": {
                    "value": {
                      "error": "forbidden"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "No such agent in the key’s Space.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HttpError"
                },
                "examples": {
                  "agent_not_found": {
                    "value": {
                      "error": "agent_not_found"
                    }
                  }
                }
              }
            }
          },
          "409": {
            "description": "Idempotency state conflict or unsupported legacy agent setup. Do not change the ID automatically after an uncertain outcome.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HttpError"
                },
                "examples": {
                  "in_progress": {
                    "value": {
                      "error": "in_progress"
                    }
                  },
                  "idempotency_mismatch": {
                    "value": {
                      "error": "idempotency_mismatch"
                    }
                  },
                  "request_outcome_unknown": {
                    "value": {
                      "error": "request_outcome_unknown"
                    }
                  },
                  "run_expired": {
                    "value": {
                      "error": "run_expired"
                    }
                  },
                  "local_execution_required": {
                    "value": {
                      "error": "local_execution_required"
                    }
                  }
                }
              }
            }
          },
          "413": {
            "description": "Request body exceeds the byte limit.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HttpError"
                },
                "examples": {
                  "Body too large": {
                    "value": {
                      "error": "Body too large"
                    }
                  }
                }
              }
            }
          },
          "415": {
            "description": "Use application/json without a Content-Encoding header.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HttpError"
                },
                "examples": {
                  "JSON required": {
                    "value": {
                      "error": "JSON required"
                    }
                  },
                  "Unsupported content encoding": {
                    "value": {
                      "error": "Unsupported content encoding"
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "Request rate limit reached before the execution claim; wait and retry with the same ID and body.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HttpError"
                },
                "examples": {
                  "rate_limited": {
                    "value": {
                      "error": "rate_limited"
                    }
                  }
                }
              }
            },
            "headers": {
              "Retry-After": {
                "description": "Seconds to wait before retrying.",
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            }
          },
          "500": {
            "description": "Unexpected server failure. A completed attempt may retain this response; inspect History before starting another task.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HttpError"
                },
                "examples": {
                  "internal_error": {
                    "value": {
                      "error": "internal_error"
                    }
                  }
                }
              }
            }
          },
          "503": {
            "description": "Hosted inference unavailable or database temporarily busy. inference_unavailable can be stored and replayed; after restoring it, deliberately use a new attempt ID. busy before a claim may be retried with the same ID.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HttpError"
                },
                "examples": {
                  "inference_unavailable": {
                    "value": {
                      "error": "inference_unavailable"
                    }
                  },
                  "busy": {
                    "value": {
                      "error": "busy"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/v1/agents/{agentId}/tasks": {
      "parameters": [
        {
          "name": "agentId",
          "in": "path",
          "required": true,
          "description": "Saved agent ID in the Space identified by the key.",
          "schema": {
            "type": "string",
            "pattern": "^[a-z0-9][a-z0-9._-]{0,63}$"
          },
          "example": "order-reader"
        }
      ],
      "get": {
        "operationId": "listAgentTasks",
        "summary": "List an agent’s saved tasks",
        "tags": [
          "Saved tasks"
        ],
        "responses": {
          "200": {
            "description": "Saved task configurations and revisions, sorted by name.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TaskListResponse"
                }
              }
            }
          },
          "401": {
            "description": "The Space SDK key is missing, invalid or revoked.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HttpError"
                },
                "examples": {
                  "unauthorized": {
                    "value": {
                      "error": "unauthorized"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "The key lacks the required SDK scope.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HttpError"
                },
                "examples": {
                  "forbidden": {
                    "value": {
                      "error": "forbidden"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "No saved agent in this Space.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HttpError"
                },
                "examples": {
                  "agent_not_found": {
                    "value": {
                      "error": "agent_not_found"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/v1/agents/{agentId}/tasks/{name}": {
      "parameters": [
        {
          "name": "agentId",
          "in": "path",
          "required": true,
          "description": "Saved agent ID in the Space identified by the key.",
          "schema": {
            "type": "string",
            "pattern": "^[a-z0-9][a-z0-9._-]{0,63}$"
          },
          "example": "order-reader"
        },
        {
          "name": "name",
          "in": "path",
          "required": true,
          "description": "Saved task name on this agent.",
          "schema": {
            "type": "string",
            "pattern": "^[a-z][a-z0-9._-]{0,63}$",
            "maxLength": 64
          },
          "example": "read-request"
        }
      ],
      "get": {
        "operationId": "getAgentTask",
        "summary": "Read a task and its current revision",
        "tags": [
          "Saved tasks"
        ],
        "responses": {
          "200": {
            "description": "Current saved operation and settings.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TaskResponse"
                }
              }
            }
          },
          "401": {
            "description": "The Space SDK key is missing, invalid or revoked.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HttpError"
                },
                "examples": {
                  "unauthorized": {
                    "value": {
                      "error": "unauthorized"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "The key lacks the required SDK scope.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HttpError"
                },
                "examples": {
                  "forbidden": {
                    "value": {
                      "error": "forbidden"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "No task with this name on the agent.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HttpError"
                },
                "examples": {
                  "task_not_found": {
                    "value": {
                      "error": "task_not_found"
                    }
                  }
                }
              }
            }
          }
        }
      },
      "put": {
        "operationId": "setAgentTask",
        "summary": "Create or replace a complete saved task",
        "tags": [
          "Saved tasks"
        ],
        "description": "Tasks belong to the agent, not a conversation scope. Each agent can hold 32. Replaces the complete operation/settings and increments the revision; it is not a partial update. ifRevision null creates only; a number must match the current revision. Omitting it overwrites. Saved changes affect subsequent new runs without changing a caller. Removing an output field can break callers; revision pinning is not supported.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/TaskWrite"
              },
              "example": {
                "operation": "extract",
                "schema": {
                  "orderId": "number",
                  "problem": "string"
                },
                "ifRevision": null
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Replaced task with incremented revision.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TaskResponse"
                }
              }
            }
          },
          "201": {
            "description": "Created task, revision 1.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TaskResponse"
                }
              }
            }
          },
          "400": {
            "description": "Invalid task name or settings.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HttpError"
                },
                "examples": {
                  "invalid_task_name": {
                    "value": {
                      "error": "invalid_task_name"
                    }
                  },
                  "invalid_body": {
                    "value": {
                      "error": "invalid_body"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "The Space SDK key is missing, invalid or revoked.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HttpError"
                },
                "examples": {
                  "unauthorized": {
                    "value": {
                      "error": "unauthorized"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "The key lacks the required SDK scope.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HttpError"
                },
                "examples": {
                  "forbidden": {
                    "value": {
                      "error": "forbidden"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "No saved agent in this Space.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HttpError"
                },
                "examples": {
                  "agent_not_found": {
                    "value": {
                      "error": "agent_not_found"
                    }
                  }
                }
              }
            }
          },
          "409": {
            "description": "Revision conflict or the agent already holds 32 tasks. Preserve the draft and reconcile the edit.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HttpError"
                },
                "examples": {
                  "task_revision_conflict": {
                    "value": {
                      "error": "task_revision_conflict"
                    }
                  },
                  "task_limit_reached": {
                    "value": {
                      "error": "task_limit_reached"
                    }
                  }
                }
              }
            }
          },
          "413": {
            "description": "Task body exceeds 131072 bytes.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HttpError"
                },
                "examples": {
                  "Body too large": {
                    "value": {
                      "error": "Body too large"
                    }
                  }
                }
              }
            }
          },
          "415": {
            "description": "Use application/json without Content-Encoding.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HttpError"
                },
                "examples": {
                  "JSON required": {
                    "value": {
                      "error": "JSON required"
                    }
                  },
                  "Unsupported content encoding": {
                    "value": {
                      "error": "Unsupported content encoding"
                    }
                  }
                }
              }
            }
          }
        }
      },
      "delete": {
        "operationId": "deleteAgentTask",
        "summary": "Remove a saved task",
        "tags": [
          "Saved tasks"
        ],
        "description": "Unconditional removal. Subsequent new runs that name it return task_not_found. Existing retained operations are unchanged.",
        "responses": {
          "200": {
            "description": "Task removed.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "deleted": {
                      "type": "boolean",
                      "const": true
                    }
                  },
                  "required": [
                    "deleted"
                  ]
                }
              }
            }
          },
          "401": {
            "description": "The Space SDK key is missing, invalid or revoked.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HttpError"
                },
                "examples": {
                  "unauthorized": {
                    "value": {
                      "error": "unauthorized"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "The key lacks the required SDK scope.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HttpError"
                },
                "examples": {
                  "forbidden": {
                    "value": {
                      "error": "forbidden"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "No such saved task.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HttpError"
                },
                "examples": {
                  "task_not_found": {
                    "value": {
                      "error": "task_not_found"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/v1/agents/{agentId}/tasks/{name}/run": {
      "parameters": [
        {
          "name": "agentId",
          "in": "path",
          "required": true,
          "description": "Saved agent ID in the Space identified by the key.",
          "schema": {
            "type": "string",
            "pattern": "^[a-z0-9][a-z0-9._-]{0,63}$"
          },
          "example": "order-reader"
        },
        {
          "name": "name",
          "in": "path",
          "required": true,
          "description": "Saved task name on this agent.",
          "schema": {
            "type": "string",
            "pattern": "^[a-z][a-z0-9._-]{0,63}$",
            "maxLength": 64
          },
          "example": "read-request"
        }
      ],
      "post": {
        "operationId": "runAgentTask",
        "summary": "Run a saved task with its input",
        "tags": [
          "Saved tasks"
        ],
        "description": "Requires API 0.25.0, hosted model access and model credit. The request supplies input rather than operation, schema, criteria or actions. Optional reference is accepted only by validate tasks. No contextKeys field is accepted: selected keys come from the task. Maximum JSON body size is 131072 bytes. Idempotency scope remains Space/agent/key; the fingerprint includes task name and parsed run input, not the current task revision. Reusing a completed request ID after editing its task replays the original response and revision. Reusing the same ID for another task on the same agent is idempotency_mismatch. Use a new ID for a new run that should use changed settings. Follow the same timeout/unknown-outcome rules as runAgent. HTTP decides do not execute application handlers.",
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": true,
            "description": "Stable ID per task; reuse after timeout or network failure. Scoped to Space, agent and SDK key.",
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 128,
              "pattern": "^[!-~]+$"
            },
            "example": "order-42-read-v1"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/TaskRunInput"
              },
              "example": {
                "input": "Order 1042 arrived with a broken mug."
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Operation result plus the task name, revision and operation. A model-operation failure may still return HTTP 200; inspect result.success. Retained History records keep the settings that ran.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TaskRunResponse"
                }
              }
            }
          },
          "400": {
            "description": "Malformed JSON, invalid fields or missing/invalid idempotency header.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HttpError"
                },
                "examples": {
                  "invalid_body": {
                    "value": {
                      "error": "invalid_body"
                    }
                  },
                  "Invalid JSON": {
                    "value": {
                      "error": "Invalid JSON"
                    }
                  },
                  "idempotency_key_required": {
                    "value": {
                      "error": "idempotency_key_required"
                    }
                  },
                  "invalid_request_id": {
                    "value": {
                      "error": "invalid_request_id"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "The SDK key is missing, invalid or revoked.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HttpError"
                },
                "examples": {
                  "unauthorized": {
                    "value": {
                      "error": "unauthorized"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "The key lacks the required SDK scope or access.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HttpError"
                },
                "examples": {
                  "forbidden": {
                    "value": {
                      "error": "forbidden"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Task or saved agent not found in the key’s Space.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HttpError"
                },
                "examples": {
                  "task_not_found": {
                    "value": {
                      "error": "task_not_found"
                    }
                  },
                  "agent_not_found": {
                    "value": {
                      "error": "agent_not_found"
                    }
                  }
                }
              }
            }
          },
          "409": {
            "description": "Idempotency state conflict or unsupported legacy agent setup. Do not change the ID automatically after an uncertain outcome.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HttpError"
                },
                "examples": {
                  "in_progress": {
                    "value": {
                      "error": "in_progress"
                    }
                  },
                  "idempotency_mismatch": {
                    "value": {
                      "error": "idempotency_mismatch"
                    }
                  },
                  "request_outcome_unknown": {
                    "value": {
                      "error": "request_outcome_unknown"
                    }
                  },
                  "run_expired": {
                    "value": {
                      "error": "run_expired"
                    }
                  },
                  "local_execution_required": {
                    "value": {
                      "error": "local_execution_required"
                    }
                  }
                }
              }
            }
          },
          "413": {
            "description": "Request body exceeds the byte limit.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HttpError"
                },
                "examples": {
                  "Body too large": {
                    "value": {
                      "error": "Body too large"
                    }
                  }
                }
              }
            }
          },
          "415": {
            "description": "Use application/json without a Content-Encoding header.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HttpError"
                },
                "examples": {
                  "JSON required": {
                    "value": {
                      "error": "JSON required"
                    }
                  },
                  "Unsupported content encoding": {
                    "value": {
                      "error": "Unsupported content encoding"
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "Request rate limit reached before the execution claim; wait and retry with the same ID and body.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HttpError"
                },
                "examples": {
                  "rate_limited": {
                    "value": {
                      "error": "rate_limited"
                    }
                  }
                }
              }
            },
            "headers": {
              "Retry-After": {
                "description": "Seconds to wait before retrying.",
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            }
          },
          "500": {
            "description": "Unexpected server failure. A completed attempt may retain this response; inspect History before starting another task.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HttpError"
                },
                "examples": {
                  "internal_error": {
                    "value": {
                      "error": "internal_error"
                    }
                  }
                }
              }
            }
          },
          "503": {
            "description": "Hosted inference unavailable or database temporarily busy. inference_unavailable can be stored and replayed; after restoring it, deliberately use a new attempt ID. busy before a claim may be retried with the same ID.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HttpError"
                },
                "examples": {
                  "inference_unavailable": {
                    "value": {
                      "error": "inference_unavailable"
                    }
                  },
                  "busy": {
                    "value": {
                      "error": "busy"
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "SpaceKey": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "Space SDK key",
        "description": "SDK-scoped Space key. Keep it on your backend; it authorizes access to the Space, not just one end user."
      }
    },
    "schemas": {
      "ExtractInput": {
        "type": "object",
        "properties": {
          "operation": {
            "const": "extract",
            "type": "string"
          },
          "images": {
            "type": "array",
            "maxItems": 4,
            "items": {
              "type": "string",
              "format": "uri",
              "pattern": "^[Hh][Tt][Tt][Pp][Ss]://(?![^/]*@)",
              "maxLength": 2048,
              "x-max-utf16-code-units": 2048
            },
            "description": "Reachable HTTPS photo URLs without embedded credentials. Requires a Vision model. Text arguments may be empty for photo-only input. Inline base64 and file uploads are not supported."
          },
          "knowledge": {
            "oneOf": [
              {
                "type": "boolean"
              },
              {
                "type": "object",
                "properties": {
                  "query": {
                    "type": "string",
                    "description": "Non-empty after trimming. Maximum 2000 UTF-16 code units at request validation. The separate 6000 UTF-8 byte limit is checked during Knowledge search and can return HTTP 200 with result.errorCode knowledge_query_too_large.",
                    "minLength": 1,
                    "pattern": "^\\s*[\\s\\S]{0,1999}\\S\\s*$",
                    "x-max-utf16-code-units": 2000,
                    "x-max-utf8-bytes": 6000
                  }
                },
                "required": [
                  "query"
                ],
                "additionalProperties": false
              }
            ],
            "description": "Omitted or false performs no search. True derives a query from task input."
          },
          "conversation": {
            "type": "string",
            "description": "Application-chosen data scope, such as order:42. Flat ID, not an end-user authorization boundary. Knowledge sources are not filtered by this ID.",
            "minLength": 1,
            "maxLength": 128,
            "x-max-utf16-code-units": 128,
            "pattern": "^[^\\u0000-\\u001f\\u007f-\\u009f]+$"
          },
          "contextKeys": {
            "type": "array",
            "maxItems": 16,
            "items": {
              "type": "string",
              "pattern": "^[a-z][a-z0-9._-]{0,63}$"
            },
            "description": "Selected named Context entries to include."
          },
          "data": {
            "description": "Text or other JSON to read."
          },
          "schema": {
            "description": "Shorthand schema or JSON Schema. Model output is validated against it."
          }
        },
        "required": [
          "operation",
          "data",
          "schema"
        ],
        "additionalProperties": false
      },
      "SummarizeInput": {
        "type": "object",
        "properties": {
          "operation": {
            "const": "summarize",
            "type": "string"
          },
          "images": {
            "type": "array",
            "maxItems": 4,
            "items": {
              "type": "string",
              "format": "uri",
              "pattern": "^[Hh][Tt][Tt][Pp][Ss]://(?![^/]*@)",
              "maxLength": 2048,
              "x-max-utf16-code-units": 2048
            },
            "description": "Reachable HTTPS photo URLs without embedded credentials. Requires a Vision model. Text arguments may be empty for photo-only input. Inline base64 and file uploads are not supported."
          },
          "knowledge": {
            "oneOf": [
              {
                "type": "boolean"
              },
              {
                "type": "object",
                "properties": {
                  "query": {
                    "type": "string",
                    "description": "Non-empty after trimming. Maximum 2000 UTF-16 code units at request validation. The separate 6000 UTF-8 byte limit is checked during Knowledge search and can return HTTP 200 with result.errorCode knowledge_query_too_large.",
                    "minLength": 1,
                    "pattern": "^\\s*[\\s\\S]{0,1999}\\S\\s*$",
                    "x-max-utf16-code-units": 2000,
                    "x-max-utf8-bytes": 6000
                  }
                },
                "required": [
                  "query"
                ],
                "additionalProperties": false
              }
            ],
            "description": "Omitted or false performs no search. True derives a query from task input."
          },
          "conversation": {
            "type": "string",
            "description": "Application-chosen data scope, such as order:42. Flat ID, not an end-user authorization boundary. Knowledge sources are not filtered by this ID.",
            "minLength": 1,
            "maxLength": 128,
            "x-max-utf16-code-units": 128,
            "pattern": "^[^\\u0000-\\u001f\\u007f-\\u009f]+$"
          },
          "contextKeys": {
            "type": "array",
            "maxItems": 16,
            "items": {
              "type": "string",
              "pattern": "^[a-z][a-z0-9._-]{0,63}$"
            },
            "description": "Selected named Context entries to include."
          },
          "content": {
            "description": "Text or other JSON to summarize."
          },
          "maxLength": {
            "type": "integer",
            "minimum": 1,
            "maximum": 10000,
            "default": 1000,
            "description": "Maximum summary length in UTF-16 code units."
          },
          "focus": {
            "type": "string",
            "description": "What the summary should focus on.",
            "maxLength": 1000,
            "x-max-utf16-code-units": 1000
          }
        },
        "required": [
          "operation",
          "content"
        ],
        "additionalProperties": false
      },
      "ValidateInput": {
        "type": "object",
        "properties": {
          "operation": {
            "const": "validate",
            "type": "string"
          },
          "images": {
            "type": "array",
            "maxItems": 4,
            "items": {
              "type": "string",
              "format": "uri",
              "pattern": "^[Hh][Tt][Tt][Pp][Ss]://(?![^/]*@)",
              "maxLength": 2048,
              "x-max-utf16-code-units": 2048
            },
            "description": "Reachable HTTPS photo URLs without embedded credentials. Requires a Vision model. Text arguments may be empty for photo-only input. Inline base64 and file uploads are not supported."
          },
          "knowledge": {
            "oneOf": [
              {
                "type": "boolean"
              },
              {
                "type": "object",
                "properties": {
                  "query": {
                    "type": "string",
                    "description": "Non-empty after trimming. Maximum 2000 UTF-16 code units at request validation. The separate 6000 UTF-8 byte limit is checked during Knowledge search and can return HTTP 200 with result.errorCode knowledge_query_too_large.",
                    "minLength": 1,
                    "pattern": "^\\s*[\\s\\S]{0,1999}\\S\\s*$",
                    "x-max-utf16-code-units": 2000,
                    "x-max-utf8-bytes": 6000
                  }
                },
                "required": [
                  "query"
                ],
                "additionalProperties": false
              }
            ],
            "description": "Omitted or false performs no search. True derives a query from task input."
          },
          "conversation": {
            "type": "string",
            "description": "Application-chosen data scope, such as order:42. Flat ID, not an end-user authorization boundary. Knowledge sources are not filtered by this ID.",
            "minLength": 1,
            "maxLength": 128,
            "x-max-utf16-code-units": 128,
            "pattern": "^[^\\u0000-\\u001f\\u007f-\\u009f]+$"
          },
          "contextKeys": {
            "type": "array",
            "maxItems": 16,
            "items": {
              "type": "string",
              "pattern": "^[a-z][a-z0-9._-]{0,63}$"
            },
            "description": "Selected named Context entries to include."
          },
          "criteria": {
            "type": "string",
            "description": "Rules the subject must satisfy.",
            "minLength": 1,
            "maxLength": 16384,
            "x-max-utf16-code-units": 16384
          },
          "subject": {
            "description": "Claim, draft or other JSON to check."
          },
          "reference": {
            "description": "Optional explicit comparison reference. Included alongside requested Knowledge."
          }
        },
        "required": [
          "operation",
          "criteria",
          "subject"
        ],
        "additionalProperties": false
      },
      "DecideInput": {
        "type": "object",
        "properties": {
          "operation": {
            "const": "decide",
            "type": "string"
          },
          "images": {
            "type": "array",
            "maxItems": 4,
            "items": {
              "type": "string",
              "format": "uri",
              "pattern": "^[Hh][Tt][Tt][Pp][Ss]://(?![^/]*@)",
              "maxLength": 2048,
              "x-max-utf16-code-units": 2048
            },
            "description": "Reachable HTTPS photo URLs without embedded credentials. Requires a Vision model. Text arguments may be empty for photo-only input. Inline base64 and file uploads are not supported."
          },
          "knowledge": {
            "oneOf": [
              {
                "type": "boolean"
              },
              {
                "type": "object",
                "properties": {
                  "query": {
                    "type": "string",
                    "description": "Non-empty after trimming. Maximum 2000 UTF-16 code units at request validation. The separate 6000 UTF-8 byte limit is checked during Knowledge search and can return HTTP 200 with result.errorCode knowledge_query_too_large.",
                    "minLength": 1,
                    "pattern": "^\\s*[\\s\\S]{0,1999}\\S\\s*$",
                    "x-max-utf16-code-units": 2000,
                    "x-max-utf8-bytes": 6000
                  }
                },
                "required": [
                  "query"
                ],
                "additionalProperties": false
              }
            ],
            "description": "Omitted or false performs no search. True derives a query from task input."
          },
          "conversation": {
            "type": "string",
            "description": "Application-chosen data scope, such as order:42. Flat ID, not an end-user authorization boundary. Knowledge sources are not filtered by this ID.",
            "minLength": 1,
            "maxLength": 128,
            "x-max-utf16-code-units": 128,
            "pattern": "^[^\\u0000-\\u001f\\u007f-\\u009f]+$"
          },
          "contextKeys": {
            "type": "array",
            "maxItems": 16,
            "items": {
              "type": "string",
              "pattern": "^[a-z][a-z0-9._-]{0,63}$"
            },
            "description": "Selected named Context entries to include."
          },
          "context": {
            "description": "Task to decide about."
          },
          "actions": {
            "type": "array",
            "minItems": 1,
            "maxItems": 32,
            "items": {
              "type": "object",
              "properties": {
                "action": {
                  "type": "string",
                  "description": "Action name.",
                  "minLength": 1,
                  "maxLength": 64,
                  "x-max-utf16-code-units": 64
                },
                "description": {
                  "type": "string",
                  "description": "When to choose this action.",
                  "maxLength": 1000,
                  "x-max-utf16-code-units": 1000
                },
                "parameters": {
                  "type": "object",
                  "description": "Optional parameter schema, checked before a successful decision. Available with API0.24 and later."
                }
              },
              "required": [
                "action"
              ],
              "additionalProperties": false
            }
          }
        },
        "required": [
          "operation",
          "context",
          "actions"
        ],
        "additionalProperties": false
      },
      "Usage": {
        "type": "object",
        "properties": {
          "inputTokens": {
            "type": "integer",
            "minimum": 0
          },
          "outputTokens": {
            "type": "integer",
            "minimum": 0
          },
          "uncountedRequests": {
            "type": "integer",
            "minimum": 1
          }
        },
        "required": [
          "inputTokens",
          "outputTokens"
        ],
        "description": "Known generation totals. Missing usage is not zero; uncountedRequests indicates partial reporting."
      },
      "KnowledgeEvidence": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "query": {
            "type": "string"
          },
          "profile": {
            "type": "string"
          },
          "sources": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "sourceId": {
                  "type": "string"
                },
                "name": {
                  "type": "string"
                },
                "revision": {
                  "type": "integer",
                  "minimum": 1
                },
                "passages": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {
                      "start": {
                        "type": "integer",
                        "minimum": 0
                      },
                      "end": {
                        "type": "integer",
                        "minimum": 0
                      },
                      "heading": {
                        "type": "string"
                      },
                      "text": {
                        "type": "string"
                      }
                    },
                    "required": [
                      "start",
                      "end",
                      "heading",
                      "text"
                    ]
                  }
                }
              },
              "required": [
                "sourceId",
                "name",
                "revision",
                "passages"
              ]
            }
          }
        },
        "required": [
          "id",
          "query",
          "profile",
          "sources"
        ]
      },
      "ExtractSuccess": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "const": true
          },
          "attempts": {
            "type": "integer",
            "minimum": 0
          },
          "repaired": {
            "type": "boolean"
          },
          "usage": {
            "$ref": "#/components/schemas/Usage"
          },
          "historyError": {
            "type": "string",
            "description": "Present when the operation result could not be recorded; preserve the returned result."
          },
          "knowledgeUsage": {
            "type": "object",
            "properties": {
              "inputTokens": {
                "type": "integer",
                "minimum": 0
              },
              "uncountedRequests": {
                "type": "integer",
                "minimum": 1
              }
            },
            "description": "Search embedding usage, separate from generation."
          },
          "knowledge": {
            "$ref": "#/components/schemas/KnowledgeEvidence"
          },
          "data": {}
        },
        "required": [
          "success",
          "data"
        ]
      },
      "SummarizeSuccess": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "const": true
          },
          "attempts": {
            "type": "integer",
            "minimum": 0
          },
          "repaired": {
            "type": "boolean"
          },
          "usage": {
            "$ref": "#/components/schemas/Usage"
          },
          "historyError": {
            "type": "string",
            "description": "Present when the operation result could not be recorded; preserve the returned result."
          },
          "knowledgeUsage": {
            "type": "object",
            "properties": {
              "inputTokens": {
                "type": "integer",
                "minimum": 0
              },
              "uncountedRequests": {
                "type": "integer",
                "minimum": 1
              }
            },
            "description": "Search embedding usage, separate from generation."
          },
          "knowledge": {
            "$ref": "#/components/schemas/KnowledgeEvidence"
          },
          "summary": {
            "type": "string"
          },
          "keyPoints": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        },
        "required": [
          "success",
          "summary",
          "keyPoints"
        ]
      },
      "ValidateSuccess": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "const": true
          },
          "attempts": {
            "type": "integer",
            "minimum": 0
          },
          "repaired": {
            "type": "boolean"
          },
          "usage": {
            "$ref": "#/components/schemas/Usage"
          },
          "historyError": {
            "type": "string",
            "description": "Present when the operation result could not be recorded; preserve the returned result."
          },
          "knowledgeUsage": {
            "type": "object",
            "properties": {
              "inputTokens": {
                "type": "integer",
                "minimum": 0
              },
              "uncountedRequests": {
                "type": "integer",
                "minimum": 1
              }
            },
            "description": "Search embedding usage, separate from generation."
          },
          "knowledge": {
            "$ref": "#/components/schemas/KnowledgeEvidence"
          },
          "recommendation": {
            "enum": [
              "pass",
              "fail",
              "conditional"
            ],
            "type": "string"
          },
          "score": {
            "type": "number",
            "minimum": 0,
            "maximum": 1
          },
          "reasoning": {
            "type": "string"
          }
        },
        "required": [
          "success",
          "recommendation",
          "score",
          "reasoning"
        ]
      },
      "DecideSuccess": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "const": true
          },
          "attempts": {
            "type": "integer",
            "minimum": 0
          },
          "repaired": {
            "type": "boolean"
          },
          "usage": {
            "$ref": "#/components/schemas/Usage"
          },
          "historyError": {
            "type": "string",
            "description": "Present when the operation result could not be recorded; preserve the returned result."
          },
          "knowledgeUsage": {
            "type": "object",
            "properties": {
              "inputTokens": {
                "type": "integer",
                "minimum": 0
              },
              "uncountedRequests": {
                "type": "integer",
                "minimum": 1
              }
            },
            "description": "Search embedding usage, separate from generation."
          },
          "knowledge": {
            "$ref": "#/components/schemas/KnowledgeEvidence"
          },
          "action": {
            "type": "string"
          },
          "parameters": {
            "type": "object"
          },
          "reasoning": {
            "type": "string"
          }
        },
        "required": [
          "success",
          "action",
          "parameters",
          "reasoning"
        ]
      },
      "OperationFailure": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "const": false
          },
          "errorCode": {
            "type": "string",
            "description": "Machine-readable operation error; codes are extensible."
          },
          "error": {
            "type": "string",
            "description": "Human-readable explanation."
          },
          "attempts": {
            "type": "integer",
            "minimum": 0
          },
          "repaired": {
            "type": "boolean"
          },
          "usage": {
            "$ref": "#/components/schemas/Usage"
          },
          "historyError": {
            "type": "string",
            "description": "Present when the operation result could not be recorded; preserve the returned result."
          },
          "knowledgeUsage": {
            "type": "object",
            "properties": {
              "inputTokens": {
                "type": "integer",
                "minimum": 0
              },
              "uncountedRequests": {
                "type": "integer",
                "minimum": 1
              }
            },
            "description": "Search embedding usage, separate from generation."
          },
          "knowledge": {
            "$ref": "#/components/schemas/KnowledgeEvidence"
          }
        },
        "required": [
          "success",
          "errorCode",
          "error"
        ]
      },
      "RunResponse": {
        "type": "object",
        "properties": {
          "result": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/ExtractSuccess"
              },
              {
                "$ref": "#/components/schemas/SummarizeSuccess"
              },
              {
                "$ref": "#/components/schemas/ValidateSuccess"
              },
              {
                "$ref": "#/components/schemas/DecideSuccess"
              },
              {
                "$ref": "#/components/schemas/OperationFailure"
              }
            ]
          },
          "operationId": {
            "type": [
              "string",
              "null"
            ],
            "format": "uuid",
            "description": "Recorded History operation, or null if recording did not complete."
          }
        },
        "required": [
          "result",
          "operationId"
        ]
      },
      "HttpError": {
        "type": "object",
        "properties": {
          "error": {
            "type": "string"
          }
        },
        "required": [
          "error"
        ]
      },
      "ExtractTaskWrite": {
        "type": "object",
        "properties": {
          "operation": {
            "type": "string",
            "const": "extract"
          },
          "contextKeys": {
            "type": "array",
            "maxItems": 16,
            "items": {
              "type": "string",
              "pattern": "^[a-z][a-z0-9._-]{0,63}$"
            },
            "description": "Selected named Context entries to include."
          },
          "knowledge": {
            "type": "boolean",
            "description": "Search connected Knowledge with each run’s input. A run may override it."
          },
          "schema": {
            "type": "object",
            "description": "Shorthand field schema or JSON Schema object used for extraction."
          },
          "ifRevision": {
            "type": [
              "integer",
              "null"
            ],
            "minimum": 1,
            "description": "null creates only. A positive revision replaces only that revision, otherwise 409 task_revision_conflict. Omitted deliberately overwrites. PUT replaces the entire task."
          }
        },
        "required": [
          "operation",
          "schema"
        ],
        "additionalProperties": false
      },
      "ExtractSavedTask": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "pattern": "^[a-z][a-z0-9._-]{0,63}$",
            "maxLength": 64
          },
          "revision": {
            "type": "integer",
            "minimum": 1
          },
          "updatedAt": {
            "type": "string",
            "format": "date-time"
          },
          "operation": {
            "type": "string",
            "const": "extract"
          },
          "contextKeys": {
            "type": "array",
            "maxItems": 16,
            "items": {
              "type": "string",
              "pattern": "^[a-z][a-z0-9._-]{0,63}$"
            },
            "description": "Selected named Context entries to include."
          },
          "knowledge": {
            "type": "boolean",
            "description": "Search connected Knowledge with each run’s input. A run may override it."
          },
          "schema": {
            "type": "object",
            "description": "Shorthand field schema or JSON Schema object used for extraction."
          }
        },
        "required": [
          "name",
          "revision",
          "updatedAt",
          "operation",
          "schema"
        ],
        "additionalProperties": false
      },
      "SummarizeTaskWrite": {
        "type": "object",
        "properties": {
          "operation": {
            "type": "string",
            "const": "summarize"
          },
          "contextKeys": {
            "type": "array",
            "maxItems": 16,
            "items": {
              "type": "string",
              "pattern": "^[a-z][a-z0-9._-]{0,63}$"
            },
            "description": "Selected named Context entries to include."
          },
          "knowledge": {
            "type": "boolean",
            "description": "Search connected Knowledge with each run’s input. A run may override it."
          },
          "maxLength": {
            "type": "integer",
            "minimum": 1,
            "maximum": 10000,
            "default": 200
          },
          "focus": {
            "type": "string",
            "description": "Summary focus.",
            "minLength": 1,
            "maxLength": 1000
          },
          "ifRevision": {
            "type": [
              "integer",
              "null"
            ],
            "minimum": 1,
            "description": "null creates only. A positive revision replaces only that revision, otherwise 409 task_revision_conflict. Omitted deliberately overwrites. PUT replaces the entire task."
          }
        },
        "required": [
          "operation"
        ],
        "additionalProperties": false
      },
      "SummarizeSavedTask": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "pattern": "^[a-z][a-z0-9._-]{0,63}$",
            "maxLength": 64
          },
          "revision": {
            "type": "integer",
            "minimum": 1
          },
          "updatedAt": {
            "type": "string",
            "format": "date-time"
          },
          "operation": {
            "type": "string",
            "const": "summarize"
          },
          "contextKeys": {
            "type": "array",
            "maxItems": 16,
            "items": {
              "type": "string",
              "pattern": "^[a-z][a-z0-9._-]{0,63}$"
            },
            "description": "Selected named Context entries to include."
          },
          "knowledge": {
            "type": "boolean",
            "description": "Search connected Knowledge with each run’s input. A run may override it."
          },
          "maxLength": {
            "type": "integer",
            "minimum": 1,
            "maximum": 10000,
            "default": 200
          },
          "focus": {
            "type": "string",
            "description": "Summary focus.",
            "minLength": 1,
            "maxLength": 1000
          }
        },
        "required": [
          "name",
          "revision",
          "updatedAt",
          "operation"
        ],
        "additionalProperties": false
      },
      "ValidateTaskWrite": {
        "type": "object",
        "properties": {
          "operation": {
            "type": "string",
            "const": "validate"
          },
          "contextKeys": {
            "type": "array",
            "maxItems": 16,
            "items": {
              "type": "string",
              "pattern": "^[a-z][a-z0-9._-]{0,63}$"
            },
            "description": "Selected named Context entries to include."
          },
          "knowledge": {
            "type": "boolean",
            "description": "Search connected Knowledge with each run’s input. A run may override it."
          },
          "criteria": {
            "type": "string",
            "description": "Rules the subject must satisfy.",
            "minLength": 1,
            "maxLength": 16384
          },
          "ifRevision": {
            "type": [
              "integer",
              "null"
            ],
            "minimum": 1,
            "description": "null creates only. A positive revision replaces only that revision, otherwise 409 task_revision_conflict. Omitted deliberately overwrites. PUT replaces the entire task."
          }
        },
        "required": [
          "operation",
          "criteria"
        ],
        "additionalProperties": false
      },
      "ValidateSavedTask": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "pattern": "^[a-z][a-z0-9._-]{0,63}$",
            "maxLength": 64
          },
          "revision": {
            "type": "integer",
            "minimum": 1
          },
          "updatedAt": {
            "type": "string",
            "format": "date-time"
          },
          "operation": {
            "type": "string",
            "const": "validate"
          },
          "contextKeys": {
            "type": "array",
            "maxItems": 16,
            "items": {
              "type": "string",
              "pattern": "^[a-z][a-z0-9._-]{0,63}$"
            },
            "description": "Selected named Context entries to include."
          },
          "knowledge": {
            "type": "boolean",
            "description": "Search connected Knowledge with each run’s input. A run may override it."
          },
          "criteria": {
            "type": "string",
            "description": "Rules the subject must satisfy.",
            "minLength": 1,
            "maxLength": 16384
          }
        },
        "required": [
          "name",
          "revision",
          "updatedAt",
          "operation",
          "criteria"
        ],
        "additionalProperties": false
      },
      "DecideTaskWrite": {
        "type": "object",
        "properties": {
          "operation": {
            "type": "string",
            "const": "decide"
          },
          "contextKeys": {
            "type": "array",
            "maxItems": 16,
            "items": {
              "type": "string",
              "pattern": "^[a-z][a-z0-9._-]{0,63}$"
            },
            "description": "Selected named Context entries to include."
          },
          "knowledge": {
            "type": "boolean",
            "description": "Search connected Knowledge with each run’s input. A run may override it."
          },
          "actions": {
            "type": "array",
            "minItems": 1,
            "maxItems": 32,
            "items": {
              "type": "object",
              "properties": {
                "action": {
                  "type": "string",
                  "description": "Action name.",
                  "minLength": 1,
                  "maxLength": 64,
                  "x-max-utf16-code-units": 64
                },
                "description": {
                  "type": "string",
                  "description": "When to choose this action.",
                  "maxLength": 1000,
                  "x-max-utf16-code-units": 1000
                },
                "parameters": {
                  "type": "object",
                  "description": "Optional parameter schema, checked before a successful decision. Available with API0.24 and later."
                }
              },
              "required": [
                "action"
              ],
              "additionalProperties": false
            }
          },
          "ifRevision": {
            "type": [
              "integer",
              "null"
            ],
            "minimum": 1,
            "description": "null creates only. A positive revision replaces only that revision, otherwise 409 task_revision_conflict. Omitted deliberately overwrites. PUT replaces the entire task."
          }
        },
        "required": [
          "operation",
          "actions"
        ],
        "additionalProperties": false
      },
      "DecideSavedTask": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "pattern": "^[a-z][a-z0-9._-]{0,63}$",
            "maxLength": 64
          },
          "revision": {
            "type": "integer",
            "minimum": 1
          },
          "updatedAt": {
            "type": "string",
            "format": "date-time"
          },
          "operation": {
            "type": "string",
            "const": "decide"
          },
          "contextKeys": {
            "type": "array",
            "maxItems": 16,
            "items": {
              "type": "string",
              "pattern": "^[a-z][a-z0-9._-]{0,63}$"
            },
            "description": "Selected named Context entries to include."
          },
          "knowledge": {
            "type": "boolean",
            "description": "Search connected Knowledge with each run’s input. A run may override it."
          },
          "actions": {
            "type": "array",
            "minItems": 1,
            "maxItems": 32,
            "items": {
              "type": "object",
              "properties": {
                "action": {
                  "type": "string",
                  "description": "Action name.",
                  "minLength": 1,
                  "maxLength": 64,
                  "x-max-utf16-code-units": 64
                },
                "description": {
                  "type": "string",
                  "description": "When to choose this action.",
                  "maxLength": 1000,
                  "x-max-utf16-code-units": 1000
                },
                "parameters": {
                  "type": "object",
                  "description": "Optional parameter schema, checked before a successful decision. Available with API0.24 and later."
                }
              },
              "required": [
                "action"
              ],
              "additionalProperties": false
            }
          }
        },
        "required": [
          "name",
          "revision",
          "updatedAt",
          "operation",
          "actions"
        ],
        "additionalProperties": false
      },
      "TaskWrite": {
        "oneOf": [
          {
            "$ref": "#/components/schemas/ExtractTaskWrite"
          },
          {
            "$ref": "#/components/schemas/SummarizeTaskWrite"
          },
          {
            "$ref": "#/components/schemas/ValidateTaskWrite"
          },
          {
            "$ref": "#/components/schemas/DecideTaskWrite"
          }
        ],
        "discriminator": {
          "propertyName": "operation"
        }
      },
      "SavedTask": {
        "oneOf": [
          {
            "$ref": "#/components/schemas/ExtractSavedTask"
          },
          {
            "$ref": "#/components/schemas/SummarizeSavedTask"
          },
          {
            "$ref": "#/components/schemas/ValidateSavedTask"
          },
          {
            "$ref": "#/components/schemas/DecideSavedTask"
          }
        ],
        "discriminator": {
          "propertyName": "operation"
        }
      },
      "TaskMetadata": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "pattern": "^[a-z][a-z0-9._-]{0,63}$",
            "maxLength": 64
          },
          "revision": {
            "type": "integer",
            "minimum": 1
          },
          "operation": {
            "type": "string",
            "enum": [
              "extract",
              "summarize",
              "validate",
              "decide"
            ]
          }
        },
        "required": [
          "name",
          "revision",
          "operation"
        ],
        "additionalProperties": false
      },
      "TaskResponse": {
        "type": "object",
        "properties": {
          "task": {
            "$ref": "#/components/schemas/SavedTask"
          }
        },
        "required": [
          "task"
        ]
      },
      "TaskListResponse": {
        "type": "object",
        "properties": {
          "tasks": {
            "type": "array",
            "maxItems": 32,
            "items": {
              "$ref": "#/components/schemas/SavedTask"
            }
          }
        },
        "required": [
          "tasks"
        ]
      },
      "TaskRunInput": {
        "type": "object",
        "properties": {
          "input": {
            "description": "The task input: text or arbitrary JSON. Operation and settings come from the saved task."
          },
          "reference": {
            "description": "Comparison reference for validate tasks only; other task operations reject it."
          },
          "images": {
            "type": "array",
            "maxItems": 4,
            "items": {
              "type": "string",
              "format": "uri",
              "pattern": "^[Hh][Tt][Tt][Pp][Ss]://(?![^/]*@)",
              "maxLength": 2048,
              "x-max-utf16-code-units": 2048
            },
            "description": "Reachable HTTPS photo URLs without embedded credentials. Requires a Vision model. Text arguments may be empty for photo-only input. Inline base64 and file uploads are not supported."
          },
          "conversation": {
            "type": "string",
            "description": "Application-chosen data scope, such as order:42. Flat ID, not an end-user authorization boundary. Knowledge sources are not filtered by this ID.",
            "minLength": 1,
            "maxLength": 128,
            "x-max-utf16-code-units": 128,
            "pattern": "^[^\\u0000-\\u001f\\u007f-\\u009f]+$"
          },
          "knowledge": {
            "oneOf": [
              {
                "type": "boolean"
              },
              {
                "type": "object",
                "properties": {
                  "query": {
                    "type": "string",
                    "description": "Non-empty after trimming. Maximum 2000 UTF-16 code units at request validation. The separate 6000 UTF-8 byte limit is checked during Knowledge search and can return HTTP 200 with result.errorCode knowledge_query_too_large.",
                    "minLength": 1,
                    "pattern": "^\\s*[\\s\\S]{0,1999}\\S\\s*$",
                    "x-max-utf16-code-units": 2000,
                    "x-max-utf8-bytes": 6000
                  }
                },
                "required": [
                  "query"
                ],
                "additionalProperties": false
              }
            ],
            "description": "Omitted or false performs no search. True derives a query from task input."
          }
        },
        "required": [
          "input"
        ],
        "additionalProperties": false
      },
      "TaskRunResponse": {
        "type": "object",
        "properties": {
          "result": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/ExtractSuccess"
              },
              {
                "$ref": "#/components/schemas/SummarizeSuccess"
              },
              {
                "$ref": "#/components/schemas/ValidateSuccess"
              },
              {
                "$ref": "#/components/schemas/DecideSuccess"
              },
              {
                "$ref": "#/components/schemas/OperationFailure"
              }
            ]
          },
          "operationId": {
            "type": [
              "string",
              "null"
            ],
            "format": "uuid",
            "description": "Recorded History operation, or null if recording did not complete."
          },
          "task": {
            "$ref": "#/components/schemas/TaskMetadata"
          }
        },
        "required": [
          "result",
          "operationId",
          "task"
        ]
      }
    }
  }
}
