{ "openapi": "3.1.0", "info": { "title": "Eigenpal API", "version": "1.0.0", "description": "Public REST API for inspecting automations, starting and monitoring runs, managing files, collecting human reviews, and running evaluations.", "contact": { "name": "Eigenpal", "url": "https://eigenpal.com" }, "license": { "name": "Apache-2.0", "url": "https://www.apache.org/licenses/LICENSE-2.0" } }, "servers": [ { "url": "https://api.eigenpal.com", "description": "Production (canonical API hostname)" } ], "security": [ { "bearerAuth": [] } ], "tags": [ { "name": "Metadata", "description": "Authenticate and inspect the current API context." }, { "name": "Models", "description": "List text, vision, and OCR models configured for the current tenant environment. This is a catalog inventory, not a live provider health probe." }, { "name": "Automations", "description": "Inspect runnable workflow and agent automations, their versions, triggers, and source sync state. Move YAML workflows between folders and delete automations." }, { "name": "Folders", "description": "Create and organize workflow and template folders. Deleting a folder unfiles contained workflows or templates and does not delete them." }, { "name": "Runs", "description": "Start, monitor, retry, review, and debug automation runs, including artifacts." }, { "name": "Reviews", "description": "Record human review verdicts, manage corrected outputs, and monitor review health." }, { "name": "Files", "description": "Upload reusable files for later run or dataset use." }, { "name": "Templates", "description": "Upload, inspect, version, download, and delete tenant-scoped DOCX and XLSX templates." }, { "name": "Email servers", "description": "Create and manage outbound email servers for workflow mail. Secrets are encrypted at rest and never returned." }, { "name": "Evaluation", "description": "Manage datasets, examples, evaluators, experiment batches, evaluator scores, and run promotion workflows." } ], "paths": { "/v1/auth/check": { "get": { "operationId": "auth.check", "summary": "Check API key identity", "description": "Return the tenant, user, API key, and scope represented by the current API key.", "tags": [ "Metadata" ], "responses": { "200": { "description": "Authenticated identity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthCheckResponse" } } } }, "400": { "description": "Validation error. Request shape did not match the spec.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "API key lacks required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Payload too large. Upload exceeded the per-request size cap.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded", "headers": { "Retry-After": { "description": "Seconds until the next request may succeed", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Rate-limit accounting is temporarily unavailable. The request was not processed; retry.", "headers": { "Retry-After": { "description": "Seconds until the next request may succeed", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } } } }, "/v1/automations": { "get": { "operationId": "automations.list", "summary": "List automations", "description": "Returns workflows and agents through one runnable automation collection. Use `type` to narrow to workflows or agents, `search` to find automations by slug, name, or description, and `folderId` to list YAML workflows in a folder (`null` for root).", "tags": [ "Automations" ], "parameters": [ { "in": "query", "name": "search", "schema": { "description": "Substring match against slug, name, or description", "type": "string" }, "description": "Substring match against slug, name, or description" }, { "in": "query", "name": "type", "schema": { "description": "Filter by implementation type", "type": "string", "enum": [ "workflow", "agent" ] }, "description": "Filter by implementation type" }, { "in": "query", "name": "folderId", "schema": { "description": "Filter YAML workflows by folder. A folder id matches that folder; `null` matches unfiled workflows at root. Agent automations have no folders, so this filter excludes them. Cannot be combined with `type=agent`.", "type": "string" }, "description": "Filter YAML workflows by folder. A folder id matches that folder; `null` matches unfiled workflows at root. Agent automations have no folders, so this filter excludes them. Cannot be combined with `type=agent`." }, { "in": "query", "name": "limit", "schema": { "description": "Maximum number of automations to return.", "type": "integer", "minimum": 1, "maximum": 100 }, "description": "Maximum number of automations to return." }, { "in": "query", "name": "offset", "schema": { "description": "Zero-based offset for paging through automations.", "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "description": "Zero-based offset for paging through automations." } ], "responses": { "200": { "description": "Page of runnable workflow and agent automations.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListAutomationsResponse" } } } }, "400": { "description": "Validation error. Request shape did not match the spec.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "API key lacks required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Payload too large. Upload exceeded the per-request size cap.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded", "headers": { "Retry-After": { "description": "Seconds until the next request may succeed", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Rate-limit accounting is temporarily unavailable. The request was not processed; retry.", "headers": { "Retry-After": { "description": "Seconds until the next request may succeed", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } } } }, "/v1/automations/{id}": { "get": { "operationId": "automations.get", "summary": "Get automation", "description": "Get one runnable workflow or agent automation by id or typed alias.", "tags": [ "Automations" ], "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string", "description": "Workflow id, agent id, or typed alias like workflows.slug / agents.slug" }, "required": true, "description": "Workflow id, agent id, or typed alias like workflows.slug / agents.slug" } ], "responses": { "200": { "description": "Automation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AutomationDetail" } } } }, "400": { "description": "Validation error. Request shape did not match the spec.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "API key lacks required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Payload too large. Upload exceeded the per-request size cap.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded", "headers": { "Retry-After": { "description": "Seconds until the next request may succeed", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Rate-limit accounting is temporarily unavailable. The request was not processed; retry.", "headers": { "Retry-After": { "description": "Seconds until the next request may succeed", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } } }, "patch": { "operationId": "automations.update", "summary": "Move workflow automation", "description": "Move a YAML workflow between organizing folders. `folderPath` auto-creates missing workflow folders; empty or `/` files the workflow at root. Agent automations have no database folder model and are rejected. Identifiers match GET (workflow id, automation id, or `workflows.`).", "tags": [ "Automations" ], "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string", "description": "Workflow id, agent id, or typed alias like workflows.slug / agents.slug" }, "required": true, "description": "Workflow id, agent id, or typed alias like workflows.slug / agents.slug" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateAutomationRequest" } } } }, "responses": { "200": { "description": "Updated automation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AutomationDetail" } } } }, "400": { "description": "Validation error. Request shape did not match the spec.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "API key lacks required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Payload too large. Upload exceeded the per-request size cap.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded", "headers": { "Retry-After": { "description": "Seconds until the next request may succeed", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Rate-limit accounting is temporarily unavailable. The request was not processed; retry.", "headers": { "Retry-After": { "description": "Seconds until the next request may succeed", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } } }, "delete": { "operationId": "automations.delete", "summary": "Delete automation", "description": "Delete a workflow or agent automation using the same cleanup as the dashboard. Workflows archive the automations registry parent and keep execution history. Agents delete the agent row, archive the registry parent, and best-effort-delete agent storage. Identifiers match GET.", "tags": [ "Automations" ], "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string", "description": "Workflow id, agent id, or typed alias like workflows.slug / agents.slug" }, "required": true, "description": "Workflow id, agent id, or typed alias like workflows.slug / agents.slug" } ], "responses": { "200": { "description": "Automation deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteAutomationResponse" } } } }, "400": { "description": "Validation error. Request shape did not match the spec.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "API key lacks required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Payload too large. Upload exceeded the per-request size cap.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded", "headers": { "Retry-After": { "description": "Seconds until the next request may succeed", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Rate-limit accounting is temporarily unavailable. The request was not processed; retry.", "headers": { "Retry-After": { "description": "Seconds until the next request may succeed", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } } } }, "/v1/automations/{id}/dataset-review-requests": { "get": { "operationId": "automations.datasetReviewRequests.list", "summary": "List dataset review requests", "description": "List dataset review requests for one automation, including per-request progress.", "tags": [ "Evaluation" ], "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string", "description": "Automation id or typed alias, such as `workflows.slug` or `agents.slug`." }, "required": true, "description": "Automation id or typed alias, such as `workflows.slug` or `agents.slug`." }, { "in": "query", "name": "status", "schema": { "description": "Optional comma-separated review statuses to filter by.", "type": "string" }, "description": "Optional comma-separated review statuses to filter by." }, { "in": "query", "name": "limit", "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "in": "query", "name": "offset", "schema": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } } ], "responses": { "200": { "description": "Page of dataset review requests.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DatasetReviewRequestList" } } } }, "400": { "description": "Validation error. Request shape did not match the spec.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "API key lacks required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Payload too large. Upload exceeded the per-request size cap.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded", "headers": { "Retry-After": { "description": "Seconds until the next request may succeed", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Rate-limit accounting is temporarily unavailable. The request was not processed; retry.", "headers": { "Retry-After": { "description": "Seconds until the next request may succeed", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } } }, "post": { "operationId": "automations.datasetReviewRequests.create", "summary": "Create dataset review request", "description": "Snapshot selected dataset examples into a review request. Include instructions, focusFields to highlight, and ignoredFields for paths reviewers can skip. Optional itemNotes become commented events on those examples.", "tags": [ "Evaluation" ], "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string", "description": "Automation id or typed alias, such as `workflows.slug` or `agents.slug`." }, "required": true, "description": "Automation id or typed alias, such as `workflows.slug` or `agents.slug`." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateDatasetReviewRequest" } } } }, "responses": { "201": { "description": "Created dataset review request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DatasetReviewDetail" } } } }, "400": { "description": "Validation error. Request shape did not match the spec.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "API key lacks required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Payload too large. Upload exceeded the per-request size cap.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded", "headers": { "Retry-After": { "description": "Seconds until the next request may succeed", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Rate-limit accounting is temporarily unavailable. The request was not processed; retry.", "headers": { "Retry-After": { "description": "Seconds until the next request may succeed", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } } } }, "/v1/automations/{id}/dataset-review-requests/{reviewId}": { "get": { "operationId": "automations.datasetReviewRequests.get", "summary": "Get dataset review request", "description": "Fetch one dataset review request with snapshotted items, progress, focus fields, ignored fields, and events.", "tags": [ "Evaluation" ], "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string", "description": "Automation id or typed alias." }, "required": true, "description": "Automation id or typed alias." }, { "in": "path", "name": "reviewId", "schema": { "type": "string", "description": "Dataset review request id." }, "required": true, "description": "Dataset review request id." } ], "responses": { "200": { "description": "Dataset review request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DatasetReviewDetail" } } } }, "400": { "description": "Validation error. Request shape did not match the spec.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "API key lacks required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Payload too large. Upload exceeded the per-request size cap.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded", "headers": { "Retry-After": { "description": "Seconds until the next request may succeed", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Rate-limit accounting is temporarily unavailable. The request was not processed; retry.", "headers": { "Retry-After": { "description": "Seconds until the next request may succeed", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } } }, "patch": { "operationId": "automations.datasetReviewRequests.update", "summary": "Update dataset review request", "description": "Update review metadata or lifecycle status. Set status to `closed` when review is finished; a closed review accepts only a bare reopen back to `open`. Dataset reconciliation stays manual.", "tags": [ "Evaluation" ], "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string", "description": "Automation id or typed alias." }, "required": true, "description": "Automation id or typed alias." }, { "in": "path", "name": "reviewId", "schema": { "type": "string", "description": "Dataset review request id." }, "required": true, "description": "Dataset review request id." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateDatasetReviewRequest" } } } }, "responses": { "200": { "description": "Updated dataset review request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DatasetReviewDetail" } } } }, "400": { "description": "Validation error. Request shape did not match the spec.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "API key lacks required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Payload too large. Upload exceeded the per-request size cap.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded", "headers": { "Retry-After": { "description": "Seconds until the next request may succeed", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Rate-limit accounting is temporarily unavailable. The request was not processed; retry.", "headers": { "Retry-After": { "description": "Seconds until the next request may succeed", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } } } }, "/v1/automations/{id}/dataset-review-requests/{reviewId}/events": { "get": { "operationId": "automations.datasetReviewRequests.listEvents", "summary": "List dataset review events", "description": "List audit events for one dataset review request.", "tags": [ "Evaluation" ], "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string", "description": "Automation id or typed alias." }, "required": true, "description": "Automation id or typed alias." }, { "in": "path", "name": "reviewId", "schema": { "type": "string", "description": "Dataset review request id." }, "required": true, "description": "Dataset review request id." } ], "responses": { "200": { "description": "Review events.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DatasetReviewEventList" } } } }, "400": { "description": "Validation error. Request shape did not match the spec.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "API key lacks required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Payload too large. Upload exceeded the per-request size cap.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded", "headers": { "Retry-After": { "description": "Seconds until the next request may succeed", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Rate-limit accounting is temporarily unavailable. The request was not processed; retry.", "headers": { "Retry-After": { "description": "Seconds until the next request may succeed", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } } } }, "/v1/automations/{id}/dataset-review-requests/{reviewId}/items": { "get": { "operationId": "automations.datasetReviewRequests.listItems", "summary": "List dataset review items", "description": "List items for one dataset review request, optionally filtered by item status.", "tags": [ "Evaluation" ], "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string", "description": "Automation id or typed alias." }, "required": true, "description": "Automation id or typed alias." }, { "in": "path", "name": "reviewId", "schema": { "type": "string", "description": "Dataset review request id." }, "required": true, "description": "Dataset review request id." }, { "in": "query", "name": "status", "schema": { "description": "Optional comma-separated item statuses to filter by.", "type": "string" }, "description": "Optional comma-separated item statuses to filter by." } ], "responses": { "200": { "description": "Review items.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DatasetReviewItemList" } } } }, "400": { "description": "Validation error. Request shape did not match the spec.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "API key lacks required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Payload too large. Upload exceeded the per-request size cap.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded", "headers": { "Retry-After": { "description": "Seconds until the next request may succeed", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Rate-limit accounting is temporarily unavailable. The request was not processed; retry.", "headers": { "Retry-After": { "description": "Seconds until the next request may succeed", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } } } }, "/v1/automations/{id}/dataset-review-requests/{reviewId}/items/{itemId}": { "patch": { "operationId": "automations.datasetReviewRequests.updateItem", "summary": "Update dataset review item", "description": "Approve, edit, remove, reopen, comment, or record a field-decision or file-decision on one review item while the parent request is draft, open, or paused. Pass `expectedUpdatedAt` from the item the client last observed. Pass `fieldPath` with `action: comment` or `action: field-decision`, `filePath` with `action: file-decision`. `action: edit-file` is multipart-only: send `file` bytes with `filePath` (correct an existing expected file) or `newPath` (upload a brand-new expected file) plus `expectedUpdatedAt`.", "tags": [ "Evaluation" ], "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string", "description": "Automation id or typed alias." }, "required": true, "description": "Automation id or typed alias." }, { "in": "path", "name": "reviewId", "schema": { "type": "string", "description": "Dataset review request id." }, "required": true, "description": "Dataset review request id." }, { "in": "path", "name": "itemId", "schema": { "type": "string", "description": "Dataset review item id." }, "required": true, "description": "Dataset review item id." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateDatasetReviewItem" } }, "multipart/form-data": { "schema": { "$ref": "#/components/schemas/EditDatasetReviewItemFile" } } } }, "responses": { "200": { "description": "Updated review item.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DatasetReviewItemResponse" } } } }, "400": { "description": "Validation error. Request shape did not match the spec.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "API key lacks required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Payload too large. Upload exceeded the per-request size cap.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded", "headers": { "Retry-After": { "description": "Seconds until the next request may succeed", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Rate-limit accounting is temporarily unavailable. The request was not processed; retry.", "headers": { "Retry-After": { "description": "Seconds until the next request may succeed", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } } } }, "/v1/automations/{id}/dataset-review-requests/{reviewId}/items/{itemId}/files/{path}": { "get": { "operationId": "automations.datasetReviewRequests.itemFile.get", "summary": "Download dataset review item file", "description": "Download one input file (default) or expected-output file (`?kind=expected`) belonging to a review item. Authorized by `dataset_review:read` and scoped to files referenced in the item snapshot, so reviewers without workflow read can still preview documents. Expected files resolve to reviewer-corrected bytes when the item has a file overlay.", "tags": [ "Evaluation" ], "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string", "description": "Automation id or typed alias." }, "required": true, "description": "Automation id or typed alias." }, { "in": "path", "name": "reviewId", "schema": { "type": "string", "description": "Dataset review request id." }, "required": true, "description": "Dataset review request id." }, { "in": "path", "name": "itemId", "schema": { "type": "string", "description": "Dataset review item id." }, "required": true, "description": "Dataset review item id." }, { "in": "path", "name": "path", "schema": { "type": "string", "description": "Slash-delimited path under the example input folder (default) or expected folder (?kind=expected) referenced by the item snapshot." }, "required": true, "description": "Slash-delimited path under the example input folder (default) or expected folder (?kind=expected) referenced by the item snapshot." }, { "in": "query", "name": "kind", "schema": { "description": "Which file tree to serve. `expected` resolves to reviewer-corrected bytes when the item has a file overlay, else the snapshot bytes.", "type": "string", "enum": [ "input", "expected" ] }, "description": "Which file tree to serve. `expected` resolves to reviewer-corrected bytes when the item has a file overlay, else the snapshot bytes." } ], "responses": { "200": { "description": "File bytes.", "content": { "application/octet-stream": { "schema": { "type": "string", "description": "Review item file bytes (input or expected).", "format": "binary" } } } }, "400": { "description": "Validation error. Request shape did not match the spec.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "API key lacks required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Payload too large. Upload exceeded the per-request size cap.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded", "headers": { "Retry-After": { "description": "Seconds until the next request may succeed", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Rate-limit accounting is temporarily unavailable. The request was not processed; retry.", "headers": { "Retry-After": { "description": "Seconds until the next request may succeed", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } } } }, "/v1/automations/{id}/dataset/export": { "get": { "operationId": "automations.dataset.export", "summary": "Export automation dataset", "description": "Download the automation dataset as a ZIP archive. The archive uses the examples//input and examples//expected folder convention, so it can be re-imported into another automation or environment. Cloud deployments may redirect large archives to a short-lived storage URL.", "tags": [ "Evaluation" ], "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string", "description": "Automation id or typed alias." }, "required": true, "description": "Automation id or typed alias." }, { "in": "query", "name": "exampleIds", "schema": { "description": "Optional comma-separated dataset example ids to export. Omit to export the full dataset.", "type": "string" }, "description": "Optional comma-separated dataset example ids to export. Omit to export the full dataset." } ], "responses": { "200": { "description": "Dataset ZIP archive.", "content": { "application/octet-stream": { "schema": { "type": "string", "description": "ZIP archive", "format": "binary" } } } }, "302": { "description": "Redirect to a short-lived signed storage download" }, "400": { "description": "Validation error. Request shape did not match the spec.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "API key lacks required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Payload too large. Upload exceeded the per-request size cap.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded", "headers": { "Retry-After": { "description": "Seconds until the next request may succeed", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Rate-limit accounting is temporarily unavailable. The request was not processed; retry.", "headers": { "Retry-After": { "description": "Seconds until the next request may succeed", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } } } }, "/v1/automations/{id}/dataset/import": { "post": { "operationId": "automations.dataset.import", "summary": "Import automation dataset", "description": "Import a dataset ZIP archive using the examples//input and examples//expected folder convention. Use `mode=append` for additive imports or `mode=replace` to replace the dataset.", "tags": [ "Evaluation" ], "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string", "description": "Automation id or typed alias." }, "required": true, "description": "Automation id or typed alias." } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/AutomationDatasetImportMultipartRequest" } } } }, "responses": { "200": { "description": "Import result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DatasetImportResponse" } } } }, "400": { "description": "Validation error. Request shape did not match the spec.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "API key lacks required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Payload too large. Upload exceeded the per-request size cap.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded", "headers": { "Retry-After": { "description": "Seconds until the next request may succeed", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Rate-limit accounting is temporarily unavailable. The request was not processed; retry.", "headers": { "Retry-After": { "description": "Seconds until the next request may succeed", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } } } }, "/v1/automations/{id}/evaluators": { "get": { "operationId": "automations.evaluators.get", "summary": "Get evaluators", "description": "Fetch workflow evaluator YAML or agent evaluator metadata compiled from the requested sourceRef (latest release by default). Agent evaluations are defined in agent.ts and captured with each run. Automated scores are separate from human review verdicts.", "tags": [ "Evaluation" ], "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string", "description": "Automation id or typed alias." }, "required": true, "description": "Automation id or typed alias." }, { "in": "query", "name": "sourceRef", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Evaluator YAML and parsed configuration.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EvaluatorConfigResponse" } } } }, "400": { "description": "Validation error. Request shape did not match the spec.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "API key lacks required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Payload too large. Upload exceeded the per-request size cap.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded", "headers": { "Retry-After": { "description": "Seconds until the next request may succeed", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Rate-limit accounting is temporarily unavailable. The request was not processed; retry.", "headers": { "Retry-After": { "description": "Seconds until the next request may succeed", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } } }, "put": { "operationId": "automations.evaluators.update", "summary": "Replace evaluators", "description": "Replace evaluator YAML for a workflow. Agents reject YAML updates: define evaluators and a pass rule in agent.ts, then release.", "tags": [ "Evaluation" ], "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string", "description": "Automation id or typed alias." }, "required": true, "description": "Automation id or typed alias." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EvaluatorConfigUpdate" } } } }, "responses": { "200": { "description": "Updated evaluator YAML and parsed configuration.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EvaluatorConfigResponse" } } } }, "400": { "description": "Validation error. Request shape did not match the spec.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "API key lacks required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Payload too large. Upload exceeded the per-request size cap.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded", "headers": { "Retry-After": { "description": "Seconds until the next request may succeed", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Rate-limit accounting is temporarily unavailable. The request was not processed; retry.", "headers": { "Retry-After": { "description": "Seconds until the next request may succeed", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } } } }, "/v1/automations/{id}/examples": { "get": { "operationId": "automations.examples.list", "summary": "List dataset examples", "description": "List dataset examples for one automation. Examples contain input, expected output, expected files, metadata, and optional overrides used by evaluation runs. Pass `include=metadata` to return ids, names, metadata, and expected file refs without loading input or expected JSON.", "tags": [ "Evaluation" ], "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string", "description": "Automation id or typed alias, such as `workflows.slug` or `agents.slug`." }, "required": true, "description": "Automation id or typed alias, such as `workflows.slug` or `agents.slug`." }, { "in": "query", "name": "limit", "schema": { "description": "Maximum number of examples to return.", "type": "integer", "minimum": 1, "maximum": 100 }, "description": "Maximum number of examples to return." }, { "in": "query", "name": "offset", "schema": { "description": "Zero-based offset for paging through examples.", "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "description": "Zero-based offset for paging through examples." }, { "in": "query", "name": "include", "schema": { "description": "Response payload scope. `metadata` returns ids, names, metadata, and expected file refs without loading input or expected JSON.", "type": "string", "enum": [ "full", "metadata" ] }, "description": "Response payload scope. `metadata` returns ids, names, metadata, and expected file refs without loading input or expected JSON." } ], "responses": { "200": { "description": "Page of dataset examples.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DatasetExampleList" } } } }, "400": { "description": "Validation error. Request shape did not match the spec.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "API key lacks required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Payload too large. Upload exceeded the per-request size cap.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded", "headers": { "Retry-After": { "description": "Seconds until the next request may succeed", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Rate-limit accounting is temporarily unavailable. The request was not processed; retry.", "headers": { "Retry-After": { "description": "Seconds until the next request may succeed", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } } }, "post": { "operationId": "automations.examples.create", "summary": "Create dataset example", "description": "Create one dataset example from JSON fields. Use dataset import for archive-based uploads and file-bearing examples.", "tags": [ "Evaluation" ], "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string", "description": "Automation id or typed alias, such as `workflows.slug` or `agents.slug`." }, "required": true, "description": "Automation id or typed alias, such as `workflows.slug` or `agents.slug`." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DatasetExampleMutation" } } } }, "responses": { "201": { "description": "Created dataset example.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DatasetExample" } } } }, "400": { "description": "Validation error. Request shape did not match the spec.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "API key lacks required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Payload too large. Upload exceeded the per-request size cap.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded", "headers": { "Retry-After": { "description": "Seconds until the next request may succeed", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Rate-limit accounting is temporarily unavailable. The request was not processed; retry.", "headers": { "Retry-After": { "description": "Seconds until the next request may succeed", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } } } }, "/v1/automations/{id}/examples/{exampleId}": { "get": { "operationId": "automations.examples.get", "summary": "Get dataset example", "description": "Fetch one dataset example, including input, expected output, expected files, metadata, and overrides.", "tags": [ "Evaluation" ], "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string", "description": "Automation id or typed alias." }, "required": true, "description": "Automation id or typed alias." }, { "in": "path", "name": "exampleId", "schema": { "type": "string", "description": "Dataset example id. Agent examples may use deterministic name-derived ids returned by list/create responses." }, "required": true, "description": "Dataset example id. Agent examples may use deterministic name-derived ids returned by list/create responses." } ], "responses": { "200": { "description": "Dataset example.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DatasetExample" } } } }, "400": { "description": "Validation error. Request shape did not match the spec.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "API key lacks required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Payload too large. Upload exceeded the per-request size cap.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded", "headers": { "Retry-After": { "description": "Seconds until the next request may succeed", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Rate-limit accounting is temporarily unavailable. The request was not processed; retry.", "headers": { "Retry-After": { "description": "Seconds until the next request may succeed", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } } }, "patch": { "operationId": "automations.examples.update", "summary": "Update dataset example", "description": "Partially update a dataset example. Omitted fields are preserved; pass null for nullable fields to clear them.", "tags": [ "Evaluation" ], "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string", "description": "Automation id or typed alias." }, "required": true, "description": "Automation id or typed alias." }, { "in": "path", "name": "exampleId", "schema": { "type": "string", "description": "Dataset example id. Agent examples may use deterministic name-derived ids returned by list/create responses." }, "required": true, "description": "Dataset example id. Agent examples may use deterministic name-derived ids returned by list/create responses." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DatasetExampleUpdate" } } } }, "responses": { "200": { "description": "Updated dataset example.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DatasetExample" } } } }, "400": { "description": "Validation error. Request shape did not match the spec.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "API key lacks required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Payload too large. Upload exceeded the per-request size cap.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded", "headers": { "Retry-After": { "description": "Seconds until the next request may succeed", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Rate-limit accounting is temporarily unavailable. The request was not processed; retry.", "headers": { "Retry-After": { "description": "Seconds until the next request may succeed", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } } }, "delete": { "operationId": "automations.examples.delete", "summary": "Delete dataset example", "description": "Delete one dataset example from the automation dataset. This removes the example from future experiments.", "tags": [ "Evaluation" ], "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string", "description": "Automation id or typed alias." }, "required": true, "description": "Automation id or typed alias." }, { "in": "path", "name": "exampleId", "schema": { "type": "string", "description": "Dataset example id. Agent examples may use deterministic name-derived ids returned by list/create responses." }, "required": true, "description": "Dataset example id. Agent examples may use deterministic name-derived ids returned by list/create responses." } ], "responses": { "200": { "description": "Deleted dataset example.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DatasetExample" } } } }, "400": { "description": "Validation error. Request shape did not match the spec.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "API key lacks required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Payload too large. Upload exceeded the per-request size cap.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded", "headers": { "Retry-After": { "description": "Seconds until the next request may succeed", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Rate-limit accounting is temporarily unavailable. The request was not processed; retry.", "headers": { "Retry-After": { "description": "Seconds until the next request may succeed", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } } } }, "/v1/automations/{id}/examples/{exampleId}/expected": { "get": { "operationId": "automations.examples.expected.files.list", "summary": "List expected files", "description": "List files stored under the expected folder for one automation dataset example.", "tags": [ "Evaluation" ], "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string", "description": "Automation id or typed alias." }, "required": true, "description": "Automation id or typed alias." }, { "in": "path", "name": "exampleId", "schema": { "type": "string", "description": "Dataset example id." }, "required": true, "description": "Dataset example id." } ], "responses": { "200": { "description": "Expected file paths.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DatasetExampleExpectedFileList" } } } }, "400": { "description": "Validation error. Request shape did not match the spec.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "API key lacks required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Payload too large. Upload exceeded the per-request size cap.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded", "headers": { "Retry-After": { "description": "Seconds until the next request may succeed", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Rate-limit accounting is temporarily unavailable. The request was not processed; retry.", "headers": { "Retry-After": { "description": "Seconds until the next request may succeed", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } } }, "post": { "operationId": "automations.examples.expected.files.create", "summary": "Upload expected files", "description": "Upload one or more files into the expected folder for an automation dataset example. Use `$file` references such as `expected/result.pdf` from expected JSON to compare file outputs.", "tags": [ "Evaluation" ], "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string", "description": "Automation id or typed alias." }, "required": true, "description": "Automation id or typed alias." }, { "in": "path", "name": "exampleId", "schema": { "type": "string", "description": "Dataset example id." }, "required": true, "description": "Dataset example id." } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/DatasetExampleExpectedFileUploadRequest" } } } }, "responses": { "201": { "description": "Uploaded expected files.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DatasetExampleExpectedFileUploadResponse" } } } }, "400": { "description": "Validation error. Request shape did not match the spec.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "API key lacks required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Payload too large. Upload exceeded the per-request size cap.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded", "headers": { "Retry-After": { "description": "Seconds until the next request may succeed", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Rate-limit accounting is temporarily unavailable. The request was not processed; retry.", "headers": { "Retry-After": { "description": "Seconds until the next request may succeed", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } } } }, "/v1/automations/{id}/examples/{exampleId}/expected/{path}": { "get": { "operationId": "automations.examples.expected.file.get", "summary": "Download expected dataset file", "description": "Download one expected file attached to an automation dataset example.", "tags": [ "Evaluation" ], "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string", "description": "Automation id or typed alias." }, "required": true, "description": "Automation id or typed alias." }, { "in": "path", "name": "exampleId", "schema": { "type": "string", "description": "Dataset example id." }, "required": true, "description": "Dataset example id." }, { "in": "path", "name": "path", "schema": { "type": "string", "description": "Path under the example expected folder." }, "required": true, "description": "Path under the example expected folder." } ], "responses": { "200": { "description": "Expected dataset file.", "content": { "application/octet-stream": { "schema": { "type": "string", "description": "Expected file bytes.", "format": "binary" } } } }, "400": { "description": "Validation error. Request shape did not match the spec.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "API key lacks required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Payload too large. Upload exceeded the per-request size cap.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded", "headers": { "Retry-After": { "description": "Seconds until the next request may succeed", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Rate-limit accounting is temporarily unavailable. The request was not processed; retry.", "headers": { "Retry-After": { "description": "Seconds until the next request may succeed", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } } }, "patch": { "operationId": "automations.examples.expected.file.update", "summary": "Rename expected file", "description": "Rename one expected file attached to an automation dataset example. The parent folder is preserved.", "tags": [ "Evaluation" ], "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string", "description": "Automation id or typed alias." }, "required": true, "description": "Automation id or typed alias." }, { "in": "path", "name": "exampleId", "schema": { "type": "string", "description": "Dataset example id." }, "required": true, "description": "Dataset example id." }, { "in": "path", "name": "path", "schema": { "type": "string", "description": "Path under the example expected folder." }, "required": true, "description": "Path under the example expected folder." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DatasetExampleExpectedFileRenameRequest" } } } }, "responses": { "200": { "description": "Renamed expected file.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DatasetExampleExpectedFileRenameResponse" } } } }, "400": { "description": "Validation error. Request shape did not match the spec.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "API key lacks required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Payload too large. Upload exceeded the per-request size cap.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded", "headers": { "Retry-After": { "description": "Seconds until the next request may succeed", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Rate-limit accounting is temporarily unavailable. The request was not processed; retry.", "headers": { "Retry-After": { "description": "Seconds until the next request may succeed", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } } }, "delete": { "operationId": "automations.examples.expected.file.delete", "summary": "Delete expected file", "description": "Delete one file from an automation dataset example expected folder.", "tags": [ "Evaluation" ], "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string", "description": "Automation id or typed alias." }, "required": true, "description": "Automation id or typed alias." }, { "in": "path", "name": "exampleId", "schema": { "type": "string", "description": "Dataset example id." }, "required": true, "description": "Dataset example id." }, { "in": "path", "name": "path", "schema": { "type": "string", "description": "Path under the example expected folder." }, "required": true, "description": "Path under the example expected folder." } ], "responses": { "200": { "description": "Expected file deleted." }, "400": { "description": "Validation error. Request shape did not match the spec.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "API key lacks required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Payload too large. Upload exceeded the per-request size cap.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded", "headers": { "Retry-After": { "description": "Seconds until the next request may succeed", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Rate-limit accounting is temporarily unavailable. The request was not processed; retry.", "headers": { "Retry-After": { "description": "Seconds until the next request may succeed", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } } } }, "/v1/automations/{id}/examples/{exampleId}/input": { "get": { "operationId": "automations.examples.input.files.list", "summary": "List input files", "description": "List files stored under the input folder for one automation dataset example.", "tags": [ "Evaluation" ], "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string", "description": "Automation id or typed alias." }, "required": true, "description": "Automation id or typed alias." }, { "in": "path", "name": "exampleId", "schema": { "type": "string", "description": "Dataset example id." }, "required": true, "description": "Dataset example id." } ], "responses": { "200": { "description": "Input file paths.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DatasetExampleInputFileList" } } } }, "400": { "description": "Validation error. Request shape did not match the spec.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "API key lacks required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Payload too large. Upload exceeded the per-request size cap.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded", "headers": { "Retry-After": { "description": "Seconds until the next request may succeed", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Rate-limit accounting is temporarily unavailable. The request was not processed; retry.", "headers": { "Retry-After": { "description": "Seconds until the next request may succeed", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } } }, "post": { "operationId": "automations.examples.input.files.create", "summary": "Upload input files", "description": "Upload one or more files into the input folder for an automation dataset example. Use `$file` references such as `input/invoice.pdf` from the example input JSON to consume them.", "tags": [ "Evaluation" ], "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string", "description": "Automation id or typed alias." }, "required": true, "description": "Automation id or typed alias." }, { "in": "path", "name": "exampleId", "schema": { "type": "string", "description": "Dataset example id." }, "required": true, "description": "Dataset example id." } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/DatasetExampleInputFileUploadRequest" } } } }, "responses": { "201": { "description": "Uploaded input files.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DatasetExampleInputFileUploadResponse" } } } }, "400": { "description": "Validation error. Request shape did not match the spec.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "API key lacks required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Payload too large. Upload exceeded the per-request size cap.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded", "headers": { "Retry-After": { "description": "Seconds until the next request may succeed", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Rate-limit accounting is temporarily unavailable. The request was not processed; retry.", "headers": { "Retry-After": { "description": "Seconds until the next request may succeed", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } } } }, "/v1/automations/{id}/examples/{exampleId}/input/{path}": { "get": { "operationId": "automations.examples.input.file.get", "summary": "Download input file", "description": "Download one file from an automation dataset example input folder.", "tags": [ "Evaluation" ], "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string", "description": "Automation id or typed alias." }, "required": true, "description": "Automation id or typed alias." }, { "in": "path", "name": "exampleId", "schema": { "type": "string", "description": "Dataset example id." }, "required": true, "description": "Dataset example id." }, { "in": "path", "name": "path", "schema": { "type": "string", "description": "Slash-delimited path under the example input folder." }, "required": true, "description": "Slash-delimited path under the example input folder." } ], "responses": { "200": { "description": "Input file bytes.", "content": { "application/octet-stream": { "schema": { "type": "string", "description": "Input file bytes.", "format": "binary" } } } }, "400": { "description": "Validation error. Request shape did not match the spec.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "API key lacks required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Payload too large. Upload exceeded the per-request size cap.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded", "headers": { "Retry-After": { "description": "Seconds until the next request may succeed", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Rate-limit accounting is temporarily unavailable. The request was not processed; retry.", "headers": { "Retry-After": { "description": "Seconds until the next request may succeed", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } } }, "patch": { "operationId": "automations.examples.input.file.update", "summary": "Rename input file", "description": "Rename one input file attached to an automation dataset example. The parent folder is preserved.", "tags": [ "Evaluation" ], "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string", "description": "Automation id or typed alias." }, "required": true, "description": "Automation id or typed alias." }, { "in": "path", "name": "exampleId", "schema": { "type": "string", "description": "Dataset example id." }, "required": true, "description": "Dataset example id." }, { "in": "path", "name": "path", "schema": { "type": "string", "description": "Slash-delimited path under the example input folder." }, "required": true, "description": "Slash-delimited path under the example input folder." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DatasetExampleInputFileRenameRequest" } } } }, "responses": { "200": { "description": "Renamed input file.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DatasetExampleInputFileRenameResponse" } } } }, "400": { "description": "Validation error. Request shape did not match the spec.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "API key lacks required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Payload too large. Upload exceeded the per-request size cap.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded", "headers": { "Retry-After": { "description": "Seconds until the next request may succeed", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Rate-limit accounting is temporarily unavailable. The request was not processed; retry.", "headers": { "Retry-After": { "description": "Seconds until the next request may succeed", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } } }, "delete": { "operationId": "automations.examples.input.file.delete", "summary": "Delete input file", "description": "Delete one file from an automation dataset example input folder.", "tags": [ "Evaluation" ], "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string", "description": "Automation id or typed alias." }, "required": true, "description": "Automation id or typed alias." }, { "in": "path", "name": "exampleId", "schema": { "type": "string", "description": "Dataset example id." }, "required": true, "description": "Dataset example id." }, { "in": "path", "name": "path", "schema": { "type": "string", "description": "Slash-delimited path under the example input folder." }, "required": true, "description": "Slash-delimited path under the example input folder." } ], "responses": { "200": { "description": "Input file deleted." }, "400": { "description": "Validation error. Request shape did not match the spec.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "API key lacks required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Payload too large. Upload exceeded the per-request size cap.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded", "headers": { "Retry-After": { "description": "Seconds until the next request may succeed", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Rate-limit accounting is temporarily unavailable. The request was not processed; retry.", "headers": { "Retry-After": { "description": "Seconds until the next request may succeed", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } } } }, "/v1/automations/{id}/examples/{exampleId}/run": { "post": { "operationId": "automations.examples.run", "summary": "Run dataset example", "description": "Start an asynchronous run using the input from one dataset example. Poll `GET /api/v1/runs/{id}` for completion and use run scores or review endpoints to review the result.", "tags": [ "Evaluation" ], "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string", "description": "Automation id or typed alias." }, "required": true, "description": "Automation id or typed alias." }, { "in": "path", "name": "exampleId", "schema": { "type": "string", "description": "Dataset example id to run." }, "required": true, "description": "Dataset example id to run." } ], "responses": { "201": { "description": "Example run accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExampleRunResponse" } } } }, "400": { "description": "Validation error. Request shape did not match the spec.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "API key lacks required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Payload too large. Upload exceeded the per-request size cap.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded", "headers": { "Retry-After": { "description": "Seconds until the next request may succeed", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Rate-limit accounting is temporarily unavailable. The request was not processed; retry.", "headers": { "Retry-After": { "description": "Seconds until the next request may succeed", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } } } }, "/v1/automations/{id}/experiments": { "get": { "operationId": "automations.experiments.list", "summary": "List experiments", "description": "List experiment batches for one automation. Each experiment runs selected dataset examples and records automated evaluator scores.", "tags": [ "Evaluation" ], "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string", "description": "Automation id or typed alias." }, "required": true, "description": "Automation id or typed alias." }, { "in": "query", "name": "limit", "schema": { "description": "Maximum number of experiment batches to return.", "type": "integer", "minimum": 1, "maximum": 500 }, "description": "Maximum number of experiment batches to return." }, { "in": "query", "name": "offset", "schema": { "description": "Zero-based offset for paging through experiment batches.", "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "description": "Zero-based offset for paging through experiment batches." }, { "in": "query", "name": "fromDate", "schema": { "description": "Filter to experiment batches created at or after this date or relative date.", "type": "string" }, "description": "Filter to experiment batches created at or after this date or relative date." }, { "in": "query", "name": "toDate", "schema": { "description": "Filter to experiment batches created at or before this date or relative date.", "type": "string" }, "description": "Filter to experiment batches created at or before this date or relative date." } ], "responses": { "200": { "description": "Page of experiment batches.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Experiment" } }, "total": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "limit": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "offset": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "data", "total", "limit", "offset" ], "additionalProperties": false } } } }, "400": { "description": "Validation error. Request shape did not match the spec.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "API key lacks required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Payload too large. Upload exceeded the per-request size cap.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded", "headers": { "Retry-After": { "description": "Seconds until the next request may succeed", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Rate-limit accounting is temporarily unavailable. The request was not processed; retry.", "headers": { "Retry-After": { "description": "Seconds until the next request may succeed", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } } }, "post": { "operationId": "automations.experiments.create", "summary": "Create experiment", "description": "Start an asynchronous experiment batch for one automation. Omit `examples` to run the full dataset, or pass specific example ids to run a subset.", "tags": [ "Evaluation" ], "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string", "description": "Automation id or typed alias." }, "required": true, "description": "Automation id or typed alias." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExperimentCreate" } } } }, "responses": { "202": { "description": "Experiment accepted and runs enqueued.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExperimentCreateResponse" } } } }, "400": { "description": "Validation error. Request shape did not match the spec.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "API key lacks required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Payload too large. Upload exceeded the per-request size cap.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded", "headers": { "Retry-After": { "description": "Seconds until the next request may succeed", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Rate-limit accounting is temporarily unavailable. The request was not processed; retry.", "headers": { "Retry-After": { "description": "Seconds until the next request may succeed", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } } } }, "/v1/automations/{id}/experiments/{experimentId}": { "get": { "operationId": "automations.experiments.get", "summary": "Get experiment", "description": "Fetch one experiment batch with its run summaries and evaluator results grouped by run id.", "tags": [ "Evaluation" ], "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string", "description": "Automation id or typed alias." }, "required": true, "description": "Automation id or typed alias." }, { "in": "path", "name": "experimentId", "schema": { "type": "string", "description": "Experiment batch id." }, "required": true, "description": "Experiment batch id." } ], "responses": { "200": { "description": "Experiment detail with runs and results.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExperimentDetail" } } } }, "400": { "description": "Validation error. Request shape did not match the spec.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "API key lacks required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Payload too large. Upload exceeded the per-request size cap.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded", "headers": { "Retry-After": { "description": "Seconds until the next request may succeed", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Rate-limit accounting is temporarily unavailable. The request was not processed; retry.", "headers": { "Retry-After": { "description": "Seconds until the next request may succeed", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } } } }, "/v1/automations/{id}/experiments/{experimentId}/cancel": { "post": { "operationId": "automations.experiments.cancel", "summary": "Cancel experiment", "description": "Request cancellation for an experiment batch. Already-completed runs remain recorded; queued or running work is cancelled when possible.", "tags": [ "Evaluation" ], "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string", "description": "Automation id or typed alias." }, "required": true, "description": "Automation id or typed alias." }, { "in": "path", "name": "experimentId", "schema": { "type": "string", "description": "Experiment batch id." }, "required": true, "description": "Experiment batch id." } ], "responses": { "200": { "description": "Experiment detail after the cancellation request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExperimentDetail" } } } }, "400": { "description": "Validation error. Request shape did not match the spec.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "API key lacks required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Payload too large. Upload exceeded the per-request size cap.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded", "headers": { "Retry-After": { "description": "Seconds until the next request may succeed", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Rate-limit accounting is temporarily unavailable. The request was not processed; retry.", "headers": { "Retry-After": { "description": "Seconds until the next request may succeed", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } } } }, "/v1/automations/{id}/experiments/{experimentId}/export": { "get": { "operationId": "automations.experiments.export", "summary": "Export experiment eval results", "description": "Download eval result rows for a single experiment batch as CSV or JSON.", "tags": [ "Evaluation" ], "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string" }, "required": true }, { "in": "path", "name": "experimentId", "schema": { "type": "string" }, "required": true }, { "in": "query", "name": "format", "schema": { "type": "string", "enum": [ "csv", "json" ] }, "required": true }, { "in": "query", "name": "includeTrace", "schema": { "type": "string", "enum": [ "0", "1", "true", "false" ] } } ], "responses": { "200": { "description": "Eval results export", "content": { "text/csv": { "schema": { "type": "string", "description": "CSV or JSON document" } } } }, "400": { "description": "Validation error. Request shape did not match the spec.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "API key lacks required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Payload too large. Upload exceeded the per-request size cap.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded", "headers": { "Retry-After": { "description": "Seconds until the next request may succeed", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Rate-limit accounting is temporarily unavailable. The request was not processed; retry.", "headers": { "Retry-After": { "description": "Seconds until the next request may succeed", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } } } }, "/v1/automations/{id}/experiments/export": { "get": { "operationId": "automations.experiments.exportAll", "summary": "Export all experiment eval results", "description": "Download every eval result row for an automation as CSV or JSON.", "tags": [ "Evaluation" ], "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string" }, "required": true }, { "in": "query", "name": "format", "schema": { "type": "string", "enum": [ "csv", "json" ] }, "required": true } ], "responses": { "200": { "description": "Eval results export", "content": { "text/csv": { "schema": { "type": "string", "description": "CSV or JSON document" } } } }, "400": { "description": "Validation error. Request shape did not match the spec.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "API key lacks required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Payload too large. Upload exceeded the per-request size cap.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded", "headers": { "Retry-After": { "description": "Seconds until the next request may succeed", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Rate-limit accounting is temporarily unavailable. The request was not processed; retry.", "headers": { "Retry-After": { "description": "Seconds until the next request may succeed", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } } } }, "/v1/automations/{id}/experiments/stream": { "post": { "operationId": "automations.experiments.createStream", "summary": "Create automation experiment with NDJSON progress", "description": "Starts a batch eval experiment for workflow or agent automations and streams per-run completion events as NDJSON.", "tags": [ "Evaluation" ], "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string" }, "required": true } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExperimentCreate" } } } }, "responses": { "200": { "description": "NDJSON experiment progress stream", "content": { "text/plain": { "schema": { "type": "string", "description": "application/x-ndjson event stream" } } } }, "400": { "description": "Validation error. Request shape did not match the spec.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "API key lacks required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Payload too large. Upload exceeded the per-request size cap.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded", "headers": { "Retry-After": { "description": "Seconds until the next request may succeed", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Rate-limit accounting is temporarily unavailable. The request was not processed; retry.", "headers": { "Retry-After": { "description": "Seconds until the next request may succeed", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } } } }, "/v1/automations/{id}/reviews/health": { "get": { "operationId": "automations.reviews.health", "summary": "Get automation review health", "description": "Aggregates reviewed correctness, review coverage, bucketed counts, and rolling-window confidence for one automation. Prefer this endpoint for single-automation monitoring dashboards.", "tags": [ "Reviews" ], "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string", "description": "Workflow id, agent id, or typed alias like workflows.slug / agents.slug." }, "required": true, "description": "Workflow id, agent id, or typed alias like workflows.slug / agents.slug." }, { "in": "query", "name": "type", "schema": { "description": "Comma-separated: workflow,agent.", "type": "string" }, "description": "Comma-separated: workflow,agent." }, { "in": "query", "name": "status", "schema": { "description": "Comma-separated execution statuses.", "type": "string" }, "description": "Comma-separated execution statuses." }, { "in": "query", "name": "trigger", "schema": { "description": "Comma-separated trigger types.", "type": "string" }, "description": "Comma-separated trigger types." }, { "in": "query", "name": "triggeredBy", "schema": { "description": "Comma-separated user ids, or __system__ for system-triggered runs.", "type": "string" }, "description": "Comma-separated user ids, or __system__ for system-triggered runs." }, { "in": "query", "name": "sourceRef", "schema": { "type": "string" } }, { "in": "query", "name": "batchId", "schema": { "type": "string" } }, { "in": "query", "name": "exampleId", "schema": { "type": "string" } }, { "in": "query", "name": "exampleIdContains", "schema": { "type": "string" } }, { "in": "query", "name": "from", "schema": { "description": "Start of the run-created time range. Defaults to now-30d.", "type": "string" }, "description": "Start of the run-created time range. Defaults to now-30d." }, { "in": "query", "name": "to", "schema": { "description": "End of the run-created time range.", "type": "string" }, "description": "End of the run-created time range." }, { "in": "query", "name": "completedAfter", "schema": { "type": "string" } }, { "in": "query", "name": "completedBefore", "schema": { "type": "string" } }, { "in": "query", "name": "experiments", "schema": { "description": "Set to false to exclude experiment batch runs.", "type": "string" }, "description": "Set to false to exclude experiment batch runs." }, { "in": "query", "name": "bucket", "schema": { "description": "Calendar bucket size for the bar chart series. Defaults to day.", "type": "string", "enum": [ "day", "week", "month" ] }, "description": "Calendar bucket size for the bar chart series. Defaults to day." }, { "in": "query", "name": "rollingWindow", "schema": { "description": "Number of reviewed runs per rolling correctness point. Defaults to 100.", "type": "integer", "minimum": 1, "maximum": 1000 }, "description": "Number of reviewed runs per rolling correctness point. Defaults to 100." }, { "in": "query", "name": "minRollingReviews", "schema": { "description": "Minimum reviewed runs required before emitting rolling points. Defaults to 1.", "type": "integer", "minimum": 1, "maximum": 1000 }, "description": "Minimum reviewed runs required before emitting rolling points. Defaults to 1." } ], "responses": { "200": { "description": "Automation review health metrics.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RunReviewHealthResponse" } } } }, "400": { "description": "Validation error. Request shape did not match the spec.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "API key lacks required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Payload too large. Upload exceeded the per-request size cap.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded", "headers": { "Retry-After": { "description": "Seconds until the next request may succeed", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Rate-limit accounting is temporarily unavailable. The request was not processed; retry.", "headers": { "Retry-After": { "description": "Seconds until the next request may succeed", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } } } }, "/v1/automations/{id}/sync": { "post": { "operationId": "automations.sync", "summary": "Sync automation from latest Git release", "description": "Reconciles automation registry metadata and trigger projections from the latest Git source release. This operation is idempotent for unchanged source state: repeated calls against the same latest release leave the same automation registry state and may repeat the same warnings. Requires a Bearer API token for the organization and a user-backed API key. It does not publish source; it reads the already-published latest release manifest. Versioned targets are rejected with 400, missing organization/source/release/manifest state returns 404, invalid manifests return 400, and provider or persistence failures return 5xx.", "tags": [ "Automations" ], "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string", "description": "Automation target to sync, such as agents.invoice-agent or workflows.extract. Do not include a version; sync always uses the latest Git release." }, "required": true, "description": "Automation target to sync, such as agents.invoice-agent or workflows.extract. Do not include a version; sync always uses the latest Git release." } ], "responses": { "200": { "description": "Automation metadata, latest release information, and non-fatal sync warnings.", "content": { "application/json": { "schema": { "type": "object", "properties": { "automation": { "type": "object", "properties": { "id": { "type": "string", "description": "Automation id after reconciliation." }, "type": { "type": "string", "enum": [ "agent", "workflow" ], "description": "Automation kind inferred from the source package path." }, "slug": { "type": "string", "description": "Source package slug within agents/ or workflows/." }, "status": { "type": "string", "enum": [ "active", "archived" ], "description": "Current automation registry status." }, "updatedAt": { "type": "string", "description": "ISO timestamp for the reconciled automation row." } }, "required": [ "id", "type", "slug", "status", "updatedAt" ], "additionalProperties": false }, "release": { "type": "object", "properties": { "version": { "type": "string", "description": "Latest released source package version that was synced." }, "tag": { "type": "string", "description": "Git release tag read during sync." }, "commit": { "type": "string", "description": "Git commit for the release tag." } }, "required": [ "version", "tag", "commit" ], "additionalProperties": false }, "warnings": { "type": "array", "items": { "type": "string" }, "description": "Non-fatal source-state warnings, such as unsupported email alias domains." } }, "required": [ "automation", "release", "warnings" ], "additionalProperties": false } } } }, "400": { "description": "Validation error. Request shape did not match the spec.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "API key lacks required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Payload too large. Upload exceeded the per-request size cap.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded", "headers": { "Retry-After": { "description": "Seconds until the next request may succeed", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Rate-limit accounting is temporarily unavailable. The request was not processed; retry.", "headers": { "Retry-After": { "description": "Seconds until the next request may succeed", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } } } }, "/v1/automations/{id}/triggers": { "get": { "operationId": "automations.triggers.get", "summary": "Get automation triggers", "description": "Read trigger state for a workflow or agent automation. Trigger mutation is not public v1.", "tags": [ "Automations" ], "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string", "description": "Workflow id, agent id, or typed alias like workflows.slug / agents.slug" }, "required": true, "description": "Workflow id, agent id, or typed alias like workflows.slug / agents.slug" } ], "responses": { "200": { "description": "Automation trigger state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AutomationTriggersResponse" } } } }, "400": { "description": "Validation error. Request shape did not match the spec.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "API key lacks required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Payload too large. Upload exceeded the per-request size cap.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded", "headers": { "Retry-After": { "description": "Seconds until the next request may succeed", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Rate-limit accounting is temporarily unavailable. The request was not processed; retry.", "headers": { "Retry-After": { "description": "Seconds until the next request may succeed", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } } } }, "/v1/automations/{id}/versions": { "get": { "operationId": "automations.versions.list", "summary": "List automation versions", "description": "List versions for a workflow or agent automation. YAML workflow lists include tagged releases plus the current untagged snapshot when HEAD is untagged (for example after restore), so the current version is always present. Agent lists remain Git release tags.", "tags": [ "Automations" ], "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string", "description": "Workflow id, agent id, or typed alias like workflows.slug / agents.slug" }, "required": true, "description": "Workflow id, agent id, or typed alias like workflows.slug / agents.slug" } ], "responses": { "200": { "description": "Automation versions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListAutomationVersionsResponse" } } } }, "400": { "description": "Validation error. Request shape did not match the spec.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "API key lacks required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Payload too large. Upload exceeded the per-request size cap.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded", "headers": { "Retry-After": { "description": "Seconds until the next request may succeed", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Rate-limit accounting is temporarily unavailable. The request was not processed; retry.", "headers": { "Retry-After": { "description": "Seconds until the next request may succeed", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } } }, "post": { "operationId": "automations.versions.create", "summary": "Create a workflow version", "description": "Create a tagged YAML workflow candidate from validated YAML or by copying an existing snapshot (`historyId`). Provide exactly one of `yaml` or `historyId`. Copy creates a new tagged row and leaves the source tag unchanged; it does not retag the original. Defaults to making the new version current. Set `activate: false` to keep it off live traffic until promote — that path requires an existing current workflow version and returns 400 if HEAD is empty. Agent automations are Git-backed and return 400. Requires a Bearer API key or a dashboard session.", "tags": [ "Automations" ], "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string", "description": "Workflow id, agent id, or typed alias like workflows.slug / agents.slug" }, "required": true, "description": "Workflow id, agent id, or typed alias like workflows.slug / agents.slug" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateAutomationVersionRequest" } } } }, "responses": { "201": { "description": "Created workflow version.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AutomationVersion" } } } }, "400": { "description": "Validation error. Request shape did not match the spec.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "API key lacks required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "Conflict. The resource is in a state that forbids the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Payload too large. Upload exceeded the per-request size cap.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded", "headers": { "Retry-After": { "description": "Seconds until the next request may succeed", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Rate-limit accounting is temporarily unavailable. The request was not processed; retry.", "headers": { "Retry-After": { "description": "Seconds until the next request may succeed", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } } } }, "/v1/automations/{id}/versions/{versionId}/promote": { "post": { "operationId": "automations.versions.promote", "summary": "Promote a workflow version", "description": "Make an existing tagged YAML workflow candidate current without creating another history row. Only tagged version rows can be promoted; untagged snapshots (including restore HEAD) and missing ids return 404. Agent automations return 400. Requires a Bearer API key or a dashboard session.", "tags": [ "Automations" ], "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string", "description": "Workflow id, agent id, or typed alias like workflows.slug / agents.slug" }, "required": true, "description": "Workflow id, agent id, or typed alias like workflows.slug / agents.slug" }, { "in": "path", "name": "versionId", "schema": { "type": "string", "description": "Tagged version id from GET /automations/{id}/versions. Untagged snapshots (for example after restore) and unknown ids return 404." }, "required": true, "description": "Tagged version id from GET /automations/{id}/versions. Untagged snapshots (for example after restore) and unknown ids return 404." } ], "responses": { "200": { "description": "Existing tagged workflow version promoted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AutomationVersion" } } } }, "400": { "description": "Validation error. Request shape did not match the spec.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "API key lacks required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "Conflict. The resource is in a state that forbids the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Payload too large. Upload exceeded the per-request size cap.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded", "headers": { "Retry-After": { "description": "Seconds until the next request may succeed", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Rate-limit accounting is temporarily unavailable. The request was not processed; retry.", "headers": { "Retry-After": { "description": "Seconds until the next request may succeed", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } } } }, "/v1/automations/{id}/versions/{versionId}/restore": { "post": { "operationId": "automations.versions.restore", "summary": "Restore a workflow version", "description": "Restore a YAML workflow automation by copying a previous snapshot into a new untagged current version. The source tag is left unchanged; the new HEAD appears in subsequent version lists as the untagged current row and cannot be promoted until you create a tagged copy. The JSON body may be `{}`; `message` is optional and defaults to a timestamped restore note. Agent automations return 400. Requires a Bearer API key or a dashboard session.", "tags": [ "Automations" ], "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string", "description": "Workflow id, agent id, or typed alias like workflows.slug / agents.slug" }, "required": true, "description": "Workflow id, agent id, or typed alias like workflows.slug / agents.slug" }, { "in": "path", "name": "versionId", "schema": { "type": "string", "description": "Version id from GET /automations/{id}/versions (a workflow history id)." }, "required": true, "description": "Version id from GET /automations/{id}/versions (a workflow history id)." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestoreAutomationVersionRequest" } } } }, "responses": { "201": { "description": "New current version created from the restored snapshot.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AutomationVersion" } } } }, "400": { "description": "Validation error. Request shape did not match the spec.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "API key lacks required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "Conflict. The resource is in a state that forbids the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Payload too large. Upload exceeded the per-request size cap.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded", "headers": { "Retry-After": { "description": "Seconds until the next request may succeed", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Rate-limit accounting is temporarily unavailable. The request was not processed; retry.", "headers": { "Retry-After": { "description": "Seconds until the next request may succeed", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } } } }, "/v1/dataset-review-requests": { "get": { "operationId": "datasetReviewRequests.list", "summary": "List dataset review requests across the tenant", "description": "Tenant-wide inbox of dataset review requests with progress and automation display names. Gated by `dataset_review:read` (reviewers allowed; does not require `workflow:read`).", "tags": [ "Evaluation" ], "parameters": [ { "in": "query", "name": "status", "schema": { "description": "Optional comma-separated review statuses to filter by.", "type": "string" }, "description": "Optional comma-separated review statuses to filter by." }, { "in": "query", "name": "limit", "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "in": "query", "name": "offset", "schema": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } } ], "responses": { "200": { "description": "Page of dataset review requests across automations.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DatasetReviewInboxList" } } } }, "400": { "description": "Validation error. Request shape did not match the spec.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "API key lacks required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Payload too large. Upload exceeded the per-request size cap.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded", "headers": { "Retry-After": { "description": "Seconds until the next request may succeed", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Rate-limit accounting is temporarily unavailable. The request was not processed; retry.", "headers": { "Retry-After": { "description": "Seconds until the next request may succeed", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } } } }, "/v1/email-servers": { "get": { "operationId": "emailServers.list", "summary": "List email servers", "description": "List outbound email servers for the current workspace. Secrets are never returned; each server includes configuration flags instead of credentials.", "tags": [ "Email servers" ], "parameters": [ { "in": "query", "name": "limit", "schema": { "description": "Maximum number of email servers to return (1–100).", "type": "integer", "minimum": 1, "maximum": 100 }, "description": "Maximum number of email servers to return (1–100)." }, { "in": "query", "name": "offset", "schema": { "description": "Zero-based offset for paging through email servers.", "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "description": "Zero-based offset for paging through email servers." } ], "responses": { "200": { "description": "Page of email servers", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListEmailServersResponse" } } } }, "400": { "description": "Validation error. Request shape did not match the spec.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "API key lacks required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Payload too large. Upload exceeded the per-request size cap.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded", "headers": { "Retry-After": { "description": "Seconds until the next request may succeed", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Rate-limit accounting is temporarily unavailable. The request was not processed; retry.", "headers": { "Retry-After": { "description": "Seconds until the next request may succeed", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } } }, "post": { "operationId": "emailServers.create", "summary": "Create email server", "description": "Create an outbound email server. Secrets are encrypted at rest and never returned. Names must be unique among live servers in the workspace.", "tags": [ "Email servers" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateEmailServerRequest" } } } }, "responses": { "201": { "description": "Created email server", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailServer" } } } }, "400": { "description": "Validation error. Request shape did not match the spec.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "API key lacks required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "Conflict. The resource is in a state that forbids the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Payload too large. Upload exceeded the per-request size cap.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded", "headers": { "Retry-After": { "description": "Seconds until the next request may succeed", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Rate-limit accounting is temporarily unavailable. The request was not processed; retry.", "headers": { "Retry-After": { "description": "Seconds until the next request may succeed", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } } } }, "/v1/email-servers/{id}": { "get": { "operationId": "emailServers.get", "summary": "Get email server", "description": "Inspect a stored outbound email server. Cross-tenant and deleted ids are indistinguishable from missing. Secrets are never returned.", "tags": [ "Email servers" ], "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string", "maxLength": 128, "pattern": "^ems_[A-Za-z0-9_-]+$", "description": "Email server id (`ems_…`)." }, "required": true, "description": "Email server id (`ems_…`)." } ], "responses": { "200": { "description": "Email server", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailServer" } } } }, "400": { "description": "Validation error. Request shape did not match the spec.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "API key lacks required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Payload too large. Upload exceeded the per-request size cap.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded", "headers": { "Retry-After": { "description": "Seconds until the next request may succeed", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Rate-limit accounting is temporarily unavailable. The request was not processed; retry.", "headers": { "Retry-After": { "description": "Seconds until the next request may succeed", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } } }, "patch": { "operationId": "emailServers.update", "summary": "Update email server", "description": "Rename, enable/disable, or replace transport configuration. Omitted secrets are retained only when the existing transport is compatible and, for SMTP, the host and username are unchanged. Changing transport or SMTP destination requires a complete valid target; a new password or explicit auth clearing is required when host or username changes.", "tags": [ "Email servers" ], "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string", "maxLength": 128, "pattern": "^ems_[A-Za-z0-9_-]+$", "description": "Email server id (`ems_…`)." }, "required": true, "description": "Email server id (`ems_…`)." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateEmailServerRequest" } } } }, "responses": { "200": { "description": "Updated email server", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailServer" } } } }, "400": { "description": "Validation error. Request shape did not match the spec.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "API key lacks required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "Conflict. The resource is in a state that forbids the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Payload too large. Upload exceeded the per-request size cap.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded", "headers": { "Retry-After": { "description": "Seconds until the next request may succeed", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Rate-limit accounting is temporarily unavailable. The request was not processed; retry.", "headers": { "Retry-After": { "description": "Seconds until the next request may succeed", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } } }, "delete": { "operationId": "emailServers.delete", "summary": "Delete email server", "description": "Soft-delete an outbound email server. Deleted ids are indistinguishable from missing.", "tags": [ "Email servers" ], "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string", "maxLength": 128, "pattern": "^ems_[A-Za-z0-9_-]+$", "description": "Email server id (`ems_…`)." }, "required": true, "description": "Email server id (`ems_…`)." } ], "responses": { "200": { "description": "Email server deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteEmailServerResponse" } } } }, "400": { "description": "Validation error. Request shape did not match the spec.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "API key lacks required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Payload too large. Upload exceeded the per-request size cap.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded", "headers": { "Retry-After": { "description": "Seconds until the next request may succeed", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Rate-limit accounting is temporarily unavailable. The request was not processed; retry.", "headers": { "Retry-After": { "description": "Seconds until the next request may succeed", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } } } }, "/v1/email-servers/{id}/test": { "post": { "operationId": "emailServers.test", "summary": "Test email server", "description": "Send a concise connectivity email through the selected stored server. Disabled servers conflict. Provider failures are returned as a generic outcome and never include credentials or the test recipient.", "tags": [ "Email servers" ], "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string", "maxLength": 128, "pattern": "^ems_[A-Za-z0-9_-]+$", "description": "Email server id (`ems_…`)." }, "required": true, "description": "Email server id (`ems_…`)." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TestEmailServerRequest" } } } }, "responses": { "200": { "description": "Test send result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TestEmailServerResponse" } } } }, "400": { "description": "Validation error. Request shape did not match the spec.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "API key lacks required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "Conflict. The resource is in a state that forbids the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Payload too large. Upload exceeded the per-request size cap.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded", "headers": { "Retry-After": { "description": "Seconds until the next request may succeed", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Rate-limit accounting is temporarily unavailable. The request was not processed; retry.", "headers": { "Retry-After": { "description": "Seconds until the next request may succeed", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } } } }, "/v1/experiments/{experimentId}": { "get": { "operationId": "experiments.resolve", "summary": "Resolve experiment by id", "description": "Returns the owning automation for an experiment batch id. Used when callers only know the experiment id.", "tags": [ "Evaluation" ], "parameters": [ { "in": "path", "name": "experimentId", "schema": { "type": "string" }, "required": true } ], "responses": { "200": { "description": "Experiment reference", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExperimentRef" } } } }, "400": { "description": "Validation error. Request shape did not match the spec.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "API key lacks required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Payload too large. Upload exceeded the per-request size cap.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded", "headers": { "Retry-After": { "description": "Seconds until the next request may succeed", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Rate-limit accounting is temporarily unavailable. The request was not processed; retry.", "headers": { "Retry-After": { "description": "Seconds until the next request may succeed", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } } } }, "/v1/files": { "post": { "operationId": "files.create", "summary": "Upload file", "description": "Upload a reusable file that can later be referenced by run inputs or dataset examples.", "tags": [ "Files" ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/CreateFileMultipartRequest" } } } }, "responses": { "200": { "description": "Uploaded file", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/File" } } } }, "400": { "description": "Validation error. Request shape did not match the spec.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "Credit quota exceeded. The organization has spent its allowance; nothing was processed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "API key lacks required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "The organization is being deleted. Its stored files are being removed, so new work that would write to its storage is refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Payload too large. Upload exceeded the per-request size cap.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded", "headers": { "Retry-After": { "description": "Seconds until the next request may succeed", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Rate-limit accounting is temporarily unavailable. The request was not processed; retry.", "headers": { "Retry-After": { "description": "Seconds until the next request may succeed", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } } } }, "/v1/files/{id}": { "get": { "operationId": "files.get", "summary": "Get file metadata", "description": "Get metadata for a reusable uploaded file.", "tags": [ "Files" ], "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string", "description": "File id" }, "required": true, "description": "File id" } ], "responses": { "200": { "description": "File metadata", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/File" } } } }, "400": { "description": "Validation error. Request shape did not match the spec.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "API key lacks required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Payload too large. Upload exceeded the per-request size cap.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded", "headers": { "Retry-After": { "description": "Seconds until the next request may succeed", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Rate-limit accounting is temporarily unavailable. The request was not processed; retry.", "headers": { "Retry-After": { "description": "Seconds until the next request may succeed", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } } }, "delete": { "operationId": "files.delete", "summary": "Delete file", "description": "Delete a reusable uploaded file. Past runs that referenced it stay readable until those runs are deleted.", "tags": [ "Files" ], "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string", "description": "File id" }, "required": true, "description": "File id" } ], "responses": { "200": { "description": "File deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteFileResponse" } } } }, "400": { "description": "Validation error. Request shape did not match the spec.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "API key lacks required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Payload too large. Upload exceeded the per-request size cap.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded", "headers": { "Retry-After": { "description": "Seconds until the next request may succeed", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Rate-limit accounting is temporarily unavailable. The request was not processed; retry.", "headers": { "Retry-After": { "description": "Seconds until the next request may succeed", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } } } }, "/v1/files/{id}/content": { "get": { "operationId": "files.content.get", "summary": "Download file content", "description": "Download bytes for a reusable uploaded file. Direct-enabled deployments redirect responses above their configured body limit to a short-lived signed storage URL; multipart-only/on-prem deployments stream through the API.", "tags": [ "Files" ], "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string", "description": "File id" }, "required": true, "description": "File id" } ], "responses": { "200": { "description": "File content" }, "302": { "description": "Redirect to a short-lived signed storage download" }, "400": { "description": "Validation error. Request shape did not match the spec.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "API key lacks required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Payload too large. Upload exceeded the per-request size cap.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded", "headers": { "Retry-After": { "description": "Seconds until the next request may succeed", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Rate-limit accounting is temporarily unavailable. The request was not processed; retry.", "headers": { "Retry-After": { "description": "Seconds until the next request may succeed", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } } } }, "/v1/files/uploads": { "post": { "operationId": "files.uploads.create", "summary": "Prepare file upload", "description": "Negotiate HTTP multipart for small bodies, a short-lived signed PUT under the single-object ceiling, storage-direct multipart (presigned-multipart) for larger files when storage supports MPU, or app-server http-chunked PUTs when direct uploads are disabled. The response transport is authoritative; clients must not guess from file size alone.", "tags": [ "Files" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateFileUploadSessionRequest" } } } }, "responses": { "200": { "description": "Negotiated upload transport", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/PresignedFileUploadSession" }, { "$ref": "#/components/schemas/PresignedMultipartFileUploadSession" }, { "$ref": "#/components/schemas/HttpChunkedFileUploadSession" }, { "$ref": "#/components/schemas/MultipartFileUploadFallback" } ] } } } }, "400": { "description": "Validation error. Request shape did not match the spec.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "Credit quota exceeded. The organization has spent its allowance; nothing was processed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "API key lacks required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "The organization is being deleted. Its stored files are being removed, so new work that would write to its storage is refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Payload too large. Upload exceeded the per-request size cap.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded", "headers": { "Retry-After": { "description": "Seconds until the next request may succeed", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Rate-limit accounting is temporarily unavailable. The request was not processed; retry.", "headers": { "Retry-After": { "description": "Seconds until the next request may succeed", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } } } }, "/v1/files/uploads/{uploadId}": { "get": { "operationId": "files.uploads.get", "summary": "Get file upload session", "description": "Return session status for resume. Multipart sessions include authoritative uploaded parts from storage, not client-reported ETags.", "tags": [ "Files" ], "parameters": [ { "in": "path", "name": "uploadId", "schema": { "type": "string" }, "required": true } ], "responses": { "200": { "description": "Upload session", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FileUploadSession" } } } }, "400": { "description": "Validation error. Request shape did not match the spec.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "API key lacks required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Payload too large. Upload exceeded the per-request size cap.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded", "headers": { "Retry-After": { "description": "Seconds until the next request may succeed", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Rate-limit accounting is temporarily unavailable. The request was not processed; retry.", "headers": { "Retry-After": { "description": "Seconds until the next request may succeed", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } } }, "delete": { "operationId": "files.uploads.abort", "summary": "Abort file upload", "description": "Abort a pending storage-direct or http-chunked upload. Multipart sessions call AbortMultipartUpload; pending PUT objects and staged chunks are deleted. Completed canonical files are never deleted.", "tags": [ "Files" ], "parameters": [ { "in": "path", "name": "uploadId", "schema": { "type": "string" }, "required": true } ], "responses": { "200": { "description": "Upload aborted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AbortFileUploadResponse" } } } }, "400": { "description": "Validation error. Request shape did not match the spec.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "API key lacks required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Payload too large. Upload exceeded the per-request size cap.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded", "headers": { "Retry-After": { "description": "Seconds until the next request may succeed", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Rate-limit accounting is temporarily unavailable. The request was not processed; retry.", "headers": { "Retry-After": { "description": "Seconds until the next request may succeed", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } } } }, "/v1/files/uploads/{uploadId}/chunks/{chunkIndex}": { "put": { "operationId": "files.uploads.chunks.put", "summary": "Upload one file chunk", "description": "Accept one raw body for an http-chunked session. Each chunk must match the negotiated size; chunks are accepted in order. Idempotent overwrite of the current index is allowed.", "tags": [ "Files" ], "parameters": [ { "in": "path", "name": "uploadId", "schema": { "type": "string" }, "required": true }, { "in": "path", "name": "chunkIndex", "schema": { "type": "string" }, "required": true } ], "requestBody": { "required": true, "content": { "application/octet-stream": { "schema": { "type": "string", "description": "Raw chunk bytes", "format": "binary" } } } }, "responses": { "200": { "description": "Chunk accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AcceptHttpChunkedUploadChunkResponse" } } } }, "400": { "description": "Validation error. Request shape did not match the spec.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "API key lacks required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "The organization is being deleted. Its stored files are being removed, so new work that would write to its storage is refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Payload too large. Upload exceeded the per-request size cap.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded", "headers": { "Retry-After": { "description": "Seconds until the next request may succeed", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Rate-limit accounting is temporarily unavailable. The request was not processed; retry.", "headers": { "Retry-After": { "description": "Seconds until the next request may succeed", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } } } }, "/v1/files/uploads/{uploadId}/complete": { "post": { "operationId": "files.uploads.complete", "summary": "Complete file upload", "description": "Verify a storage-direct pending object or assemble an http-chunked session into a reusable file. Safe to retry.", "tags": [ "Files" ], "parameters": [ { "in": "path", "name": "uploadId", "schema": { "type": "string" }, "required": true } ], "responses": { "200": { "description": "Completed reusable file", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/File" } } } }, "400": { "description": "Validation error. Request shape did not match the spec.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "API key lacks required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "The organization is being deleted. Its stored files are being removed, so new work that would write to its storage is refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Payload too large. Upload exceeded the per-request size cap.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded", "headers": { "Retry-After": { "description": "Seconds until the next request may succeed", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Rate-limit accounting is temporarily unavailable. The request was not processed; retry.", "headers": { "Retry-After": { "description": "Seconds until the next request may succeed", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } } } }, "/v1/files/uploads/{uploadId}/parts": { "get": { "operationId": "files.uploads.parts.list", "summary": "List uploaded multipart parts", "description": "List authoritative uploaded parts from storage for resume. Do not trust client-only ETags.", "tags": [ "Files" ], "parameters": [ { "in": "path", "name": "uploadId", "schema": { "type": "string" }, "required": true } ], "responses": { "200": { "description": "Uploaded parts", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListFileUploadPartsResponse" } } } }, "400": { "description": "Validation error. Request shape did not match the spec.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "API key lacks required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Payload too large. Upload exceeded the per-request size cap.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded", "headers": { "Retry-After": { "description": "Seconds until the next request may succeed", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Rate-limit accounting is temporarily unavailable. The request was not processed; retry.", "headers": { "Retry-After": { "description": "Seconds until the next request may succeed", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } } }, "post": { "operationId": "files.uploads.parts.presign", "summary": "Presign one multipart upload part", "description": "Mint a short-lived signed UploadPart URL for one validated part. Part URLs are not issued at session create.", "tags": [ "Files" ], "parameters": [ { "in": "path", "name": "uploadId", "schema": { "type": "string" }, "required": true } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PresignFileUploadPartRequest" } } } }, "responses": { "200": { "description": "Signed part upload", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PresignFileUploadPartResponse" } } } }, "400": { "description": "Validation error. Request shape did not match the spec.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "API key lacks required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "The organization is being deleted. Its stored files are being removed, so new work that would write to its storage is refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Payload too large. Upload exceeded the per-request size cap.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded", "headers": { "Retry-After": { "description": "Seconds until the next request may succeed", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Rate-limit accounting is temporarily unavailable. The request was not processed; retry.", "headers": { "Retry-After": { "description": "Seconds until the next request may succeed", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } } } }, "/v1/folders": { "get": { "operationId": "folders.list", "summary": "List folders", "description": "List folders in one tree. `type` is required (`workflow` or `template`). Pass `tree=true` for the full nested tree with counts; otherwise list direct children of `parentId` (`null` for root). Deleting a folder later unfiles contained workflows or templates and does not delete them.", "tags": [ "Folders" ], "parameters": [ { "in": "query", "name": "type", "schema": { "description": "Folder tree to list. Required; there is no default.", "$ref": "#/components/schemas/FolderType" }, "required": true, "description": "Folder tree to list. Required; there is no default." }, { "in": "query", "name": "parentId", "schema": { "description": "Limit to direct children of this folder. Pass `null` for root folders only. Ignored when `tree=true`.", "type": "string" }, "description": "Limit to direct children of this folder. Pass `null` for root folders only. Ignored when `tree=true`." }, { "in": "query", "name": "tree", "schema": { "description": "When `true`, return the full tree for `type` with child counts (and workflow previews for workflow trees).", "type": "string" }, "description": "When `true`, return the full tree for `type` with child counts (and workflow previews for workflow trees)." } ], "responses": { "200": { "description": "Folders in the requested tree", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListFoldersResponse" } } } }, "400": { "description": "Validation error. Request shape did not match the spec.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "API key lacks required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Payload too large. Upload exceeded the per-request size cap.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded", "headers": { "Retry-After": { "description": "Seconds until the next request may succeed", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Rate-limit accounting is temporarily unavailable. The request was not processed; retry.", "headers": { "Retry-After": { "description": "Seconds until the next request may succeed", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } } }, "post": { "operationId": "folders.create", "summary": "Create folder", "description": "Create a folder in the workflow or template tree. `type` is required. Missing parents 404; a same-named sibling at that location returns 409. Nested agent directories in Git are source organization only and are not folders.", "tags": [ "Folders" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateFolderRequest" } } } }, "responses": { "201": { "description": "Created folder", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Folder" } } } }, "400": { "description": "Validation error. Request shape did not match the spec.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "API key lacks required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "Conflict. The resource is in a state that forbids the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Payload too large. Upload exceeded the per-request size cap.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded", "headers": { "Retry-After": { "description": "Seconds until the next request may succeed", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Rate-limit accounting is temporarily unavailable. The request was not processed; retry.", "headers": { "Retry-After": { "description": "Seconds until the next request may succeed", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } } } }, "/v1/folders/{id}": { "get": { "operationId": "folders.get", "summary": "Get folder", "description": "Get one workflow or template folder by id.", "tags": [ "Folders" ], "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string", "description": "Folder id (`fldr_…`)." }, "required": true, "description": "Folder id (`fldr_…`)." } ], "responses": { "200": { "description": "Folder", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Folder" } } } }, "400": { "description": "Validation error. Request shape did not match the spec.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "API key lacks required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Payload too large. Upload exceeded the per-request size cap.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded", "headers": { "Retry-After": { "description": "Seconds until the next request may succeed", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Rate-limit accounting is temporarily unavailable. The request was not processed; retry.", "headers": { "Retry-After": { "description": "Seconds until the next request may succeed", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } } }, "patch": { "operationId": "folders.update", "summary": "Update folder", "description": "Rename or reparent a folder. Moving a folder onto itself, into a descendant, or into the other tree is rejected. A same-named sibling at the destination returns 409.", "tags": [ "Folders" ], "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string", "description": "Folder id (`fldr_…`)." }, "required": true, "description": "Folder id (`fldr_…`)." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateFolderRequest" } } } }, "responses": { "200": { "description": "Updated folder", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Folder" } } } }, "400": { "description": "Validation error. Request shape did not match the spec.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "API key lacks required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "Conflict. The resource is in a state that forbids the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Payload too large. Upload exceeded the per-request size cap.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded", "headers": { "Retry-After": { "description": "Seconds until the next request may succeed", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Rate-limit accounting is temporarily unavailable. The request was not processed; retry.", "headers": { "Retry-After": { "description": "Seconds until the next request may succeed", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } } }, "delete": { "operationId": "folders.delete", "summary": "Delete folder", "description": "Delete a folder and cascade-delete child folders. Workflows and templates in the tree are unfiled, not deleted.", "tags": [ "Folders" ], "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string", "description": "Folder id (`fldr_…`)." }, "required": true, "description": "Folder id (`fldr_…`)." } ], "responses": { "200": { "description": "Folder deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteFolderResponse" } } } }, "400": { "description": "Validation error. Request shape did not match the spec.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "API key lacks required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Payload too large. Upload exceeded the per-request size cap.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded", "headers": { "Retry-After": { "description": "Seconds until the next request may succeed", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Rate-limit accounting is temporarily unavailable. The request was not processed; retry.", "headers": { "Retry-After": { "description": "Seconds until the next request may succeed", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } } } }, "/v1/human-reviews": { "get": { "operationId": "humanReviews.list", "summary": "List pending human review tasks", "description": "Cursor-paginated queue of pending human-review tasks for the tenant, oldest first.", "tags": [ "Human reviews" ], "parameters": [ { "in": "query", "name": "automationId", "schema": { "type": "string" } }, { "in": "query", "name": "waitingBefore", "schema": { "type": "string" } }, { "in": "query", "name": "cursor", "schema": { "type": "string" } }, { "in": "query", "name": "limit", "schema": { "type": "integer", "minimum": 1, "maximum": 100 } } ], "responses": { "200": { "description": "Pending review tasks", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HumanReviewListResponse" } } } }, "400": { "description": "Validation error. Request shape did not match the spec.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "API key lacks required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Payload too large. Upload exceeded the per-request size cap.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded", "headers": { "Retry-After": { "description": "Seconds until the next request may succeed", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Rate-limit accounting is temporarily unavailable. The request was not processed; retry.", "headers": { "Retry-After": { "description": "Seconds until the next request may succeed", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } } } }, "/v1/human-reviews/{taskId}": { "get": { "operationId": "humanReviews.get", "summary": "Get human review task", "description": "Fetch one authorized human-review task with draft data, derived non-file input, files, and decisions.", "tags": [ "Human reviews" ], "parameters": [ { "in": "path", "name": "taskId", "schema": { "type": "string", "description": "Human review task id" }, "required": true, "description": "Human review task id" } ], "responses": { "200": { "description": "Human review task detail", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HumanReviewTaskResponse" } } } }, "400": { "description": "Validation error. Request shape did not match the spec.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "API key lacks required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Payload too large. Upload exceeded the per-request size cap.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded", "headers": { "Retry-After": { "description": "Seconds until the next request may succeed", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Rate-limit accounting is temporarily unavailable. The request was not processed; retry.", "headers": { "Retry-After": { "description": "Seconds until the next request may succeed", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } } } }, "/v1/human-reviews/{taskId}/approve": { "post": { "operationId": "humanReviews.approve", "summary": "Approve human review task", "description": "Approve a complete review task and resume the paused run. Requires every required field to be confirmed.", "tags": [ "Human reviews" ], "parameters": [ { "in": "path", "name": "taskId", "schema": { "type": "string", "description": "Human review task id" }, "required": true, "description": "Human review task id" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "expectedVersion": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "required": [ "expectedVersion" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Approved task", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HumanReviewApproveResponse" } } } }, "400": { "description": "Validation error. Request shape did not match the spec.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "API key lacks required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Payload too large. Upload exceeded the per-request size cap.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded", "headers": { "Retry-After": { "description": "Seconds until the next request may succeed", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Rate-limit accounting is temporarily unavailable. The request was not processed; retry.", "headers": { "Retry-After": { "description": "Seconds until the next request may succeed", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } } } }, "/v1/human-reviews/{taskId}/fields": { "put": { "operationId": "humanReviews.confirmField", "summary": "Confirm or edit a review field", "description": "Confirm or edit a scalar field using optimistic concurrency and a durable idempotency key.", "tags": [ "Human reviews" ], "parameters": [ { "in": "path", "name": "taskId", "schema": { "type": "string", "description": "Human review task id" }, "required": true, "description": "Human review task id" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "expectedVersion": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "idempotencyKey": { "type": "string", "minLength": 1, "maxLength": 200 }, "path": { "type": "string" }, "value": { "type": [ "string", "number", "boolean", "null" ] }, "confirmed": { "default": true, "type": "boolean" } }, "required": [ "expectedVersion", "idempotencyKey", "path", "value" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Updated task after field confirmation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HumanReviewFieldResponse" } } } }, "400": { "description": "Validation error. Request shape did not match the spec.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "API key lacks required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Payload too large. Upload exceeded the per-request size cap.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded", "headers": { "Retry-After": { "description": "Seconds until the next request may succeed", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Rate-limit accounting is temporarily unavailable. The request was not processed; retry.", "headers": { "Retry-After": { "description": "Seconds until the next request may succeed", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } } } }, "/v1/human-reviews/{taskId}/files/{fileId}/content": { "get": { "operationId": "humanReviews.files.content.get", "summary": "Download human review task file", "description": "Download one file attached to a human-review task after strict tenant, task, and run ownership checks. Large cloud deployments may redirect to a short-lived signed storage URL.", "tags": [ "Human reviews" ], "parameters": [ { "in": "path", "name": "taskId", "schema": { "type": "string", "description": "Human review task id" }, "required": true, "description": "Human review task id" }, { "in": "path", "name": "fileId", "schema": { "type": "string", "description": "File id listed on the review task" }, "required": true, "description": "File id listed on the review task" } ], "responses": { "200": { "description": "Task file content" }, "302": { "description": "Redirect to a short-lived signed storage download" }, "400": { "description": "Validation error. Request shape did not match the spec.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "API key lacks required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Payload too large. Upload exceeded the per-request size cap.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded", "headers": { "Retry-After": { "description": "Seconds until the next request may succeed", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Rate-limit accounting is temporarily unavailable. The request was not processed; retry.", "headers": { "Retry-After": { "description": "Seconds until the next request may succeed", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } } } }, "/v1/human-reviews/{taskId}/reject": { "post": { "operationId": "humanReviews.reject", "summary": "Reject human review task", "description": "Reject a review task and fail the paused run with the supplied reason.", "tags": [ "Human reviews" ], "parameters": [ { "in": "path", "name": "taskId", "schema": { "type": "string", "description": "Human review task id" }, "required": true, "description": "Human review task id" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "expectedVersion": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "idempotencyKey": { "type": "string", "minLength": 1, "maxLength": 200 }, "reason": { "type": "string", "minLength": 1, "maxLength": 5000 } }, "required": [ "expectedVersion", "idempotencyKey", "reason" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Rejected task", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HumanReviewRejectResponse" } } } }, "400": { "description": "Validation error. Request shape did not match the spec.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "API key lacks required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Payload too large. Upload exceeded the per-request size cap.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded", "headers": { "Retry-After": { "description": "Seconds until the next request may succeed", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Rate-limit accounting is temporarily unavailable. The request was not processed; retry.", "headers": { "Retry-After": { "description": "Seconds until the next request may succeed", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } } } }, "/v1/models": { "get": { "operationId": "models.list", "summary": "List configured models", "description": "List text, vision, and OCR models configured for this tenant's environment from the workspace model catalog. This is a cheap read-only inventory: it does not call providers. `health` is `configured` or `unconfigured` from local credentials, never a live probe. Secrets and provider endpoints are never returned.", "tags": [ "Models" ], "parameters": [ { "in": "query", "name": "capability", "schema": { "description": "Return only models that support this capability (`text`, `vision`, or `ocr`).", "type": "string", "enum": [ "text", "vision", "ocr" ] }, "description": "Return only models that support this capability (`text`, `vision`, or `ocr`)." } ], "responses": { "200": { "description": "Configured models", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListModelsResponse" } } } }, "400": { "description": "Validation error. Request shape did not match the spec.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "API key lacks required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Payload too large. Upload exceeded the per-request size cap.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded", "headers": { "Retry-After": { "description": "Seconds until the next request may succeed", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Rate-limit accounting is temporarily unavailable. The request was not processed; retry.", "headers": { "Retry-After": { "description": "Seconds until the next request may succeed", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } } } }, "/v1/parsing/readiness": { "get": { "operationId": "models.parserReadiness", "summary": "Inspect document parsing configuration", "description": "Read deployment-approved OCR/vision defaults and configuration readiness for ai.parse-v2. Does not probe live providers or worker native binaries. Run document smoke tests to verify live readiness.", "tags": [ "Models" ], "responses": { "200": { "description": "Parsing configuration readiness", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ParsingReadiness" } } } }, "400": { "description": "Validation error. Request shape did not match the spec.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "API key lacks required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Payload too large. Upload exceeded the per-request size cap.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded", "headers": { "Retry-After": { "description": "Seconds until the next request may succeed", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Rate-limit accounting is temporarily unavailable. The request was not processed; retry.", "headers": { "Retry-After": { "description": "Seconds until the next request may succeed", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } } } }, "/v1/runs": { "get": { "operationId": "runs.list", "summary": "List runs", "description": "List workflow and agent runs with cursor pagination.", "tags": [ "Runs" ], "parameters": [ { "in": "query", "name": "tag", "schema": { "description": "Exact, case-sensitive execution tag", "type": "string", "minLength": 1, "maxLength": 256 }, "description": "Exact, case-sensitive execution tag" }, { "in": "query", "name": "type", "schema": { "type": "string" } }, { "in": "query", "name": "source", "schema": { "type": "string" } }, { "in": "query", "name": "status", "schema": { "type": "string" } }, { "in": "query", "name": "trigger", "schema": { "type": "string" } }, { "in": "query", "name": "triggeredBy", "schema": { "type": "string" } }, { "in": "query", "name": "sourceRef", "schema": { "type": "string" } }, { "in": "query", "name": "batchId", "schema": { "type": "string" } }, { "in": "query", "name": "exampleId", "schema": { "type": "string" } }, { "in": "query", "name": "exampleIdContains", "schema": { "type": "string" } }, { "in": "query", "name": "hasExample", "schema": { "description": "Only runs linked to a dataset example (eval and example runs).", "type": "string", "enum": [ "true" ] }, "description": "Only runs linked to a dataset example (eval and example runs)." }, { "in": "query", "name": "from", "schema": { "type": "string" } }, { "in": "query", "name": "to", "schema": { "type": "string" } }, { "in": "query", "name": "createdAfter", "schema": { "type": "string" } }, { "in": "query", "name": "createdBefore", "schema": { "type": "string" } }, { "in": "query", "name": "completedAfter", "schema": { "type": "string" } }, { "in": "query", "name": "completedBefore", "schema": { "type": "string" } }, { "in": "query", "name": "cursor", "schema": { "type": "string" } }, { "in": "query", "name": "offset", "schema": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, { "in": "query", "name": "limit", "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "in": "query", "name": "ids", "schema": { "type": "string" } }, { "in": "query", "name": "experiments", "schema": { "type": "string" } }, { "in": "query", "name": "sort", "schema": { "type": "string" } }, { "in": "query", "name": "order", "schema": { "type": "string" } }, { "in": "query", "name": "reviewStatus", "schema": { "type": "string" } }, { "in": "query", "name": "reviewVerdict", "schema": { "type": "string" } }, { "in": "query", "name": "hasReview", "schema": { "type": "string" } }, { "in": "query", "name": "noReview", "schema": { "type": "string" } }, { "in": "query", "name": "hasCorrections", "schema": { "type": "string" } }, { "in": "query", "name": "reviewNoteContains", "schema": { "type": "string" } }, { "in": "query", "name": "reviewCreatedAfter", "schema": { "type": "string" } }, { "in": "query", "name": "reviewCreatedBefore", "schema": { "type": "string" } }, { "in": "query", "name": "reviewUpdatedAfter", "schema": { "type": "string" } }, { "in": "query", "name": "reviewUpdatedBefore", "schema": { "type": "string" } }, { "in": "query", "name": "reviewClosedAfter", "schema": { "type": "string" } }, { "in": "query", "name": "reviewClosedBefore", "schema": { "type": "string" } }, { "in": "query", "name": "sinceLastClosed", "schema": { "type": "string" } }, { "in": "query", "name": "sampleRate", "schema": { "description": "Keep runs whose `sampleRank` is below this threshold (0–1). Pages may return fewer than `limit` rows when filtered.", "type": "string" }, "description": "Keep runs whose `sampleRank` is below this threshold (0–1). Pages may return fewer than `limit` rows when filtered." } ], "responses": { "200": { "description": "Runs page", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RunsListResponse" } } } }, "400": { "description": "Validation error. Request shape did not match the spec.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "API key lacks required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Payload too large. Upload exceeded the per-request size cap.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded", "headers": { "Retry-After": { "description": "Seconds until the next request may succeed", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Rate-limit accounting is temporarily unavailable. The request was not processed; retry.", "headers": { "Retry-After": { "description": "Seconds until the next request may succeed", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } } }, "post": { "operationId": "runs.start", "summary": "Start a run", "description": "Start a run. Send JSON or multipart/form-data.\n\nHow to read a run: the envelope is at the root. The automation business result is in `output` (per-automation, not this generic schema). HTTP 200 can report a failed run. Inspect `execution.status` and the structured `error` (`code`, `message`, `retryable`, and optional business `statusCode` and `step`). Status is `execution.status` (`execution.retry.nextRun.status` is a later retry). `input`, `usage`, and `debug` appear only with `?expand=`. `eval` is present only on eval-scoped runs.", "tags": [ "Runs" ], "parameters": [ { "in": "query", "name": "version", "schema": { "description": "Release or git ref. Defaults to latest.", "type": "string", "minLength": 1 }, "description": "Release or git ref. Defaults to latest." }, { "in": "query", "name": "wait_for_completion", "schema": { "description": "Seconds to wait before returning (max 600). Omit for async.", "type": "integer", "minimum": 0, "maximum": 600 }, "description": "Seconds to wait before returning (max 600). Omit for async." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RunStartBody" } }, "multipart/form-data": { "schema": { "$ref": "#/components/schemas/RunStartMultipartRequest" } } } }, "responses": { "200": { "description": "Run reached a terminal status while waiting, including failure. Inspect execution.status. Same body as GET /api/v1/runs/:id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Run" } } } }, "201": { "description": "Run accepted (async)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RunAccepted" } } } }, "202": { "description": "Wait expired with a non-terminal status — poll GET /api/v1/runs/:id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RunAccepted" } } } }, "400": { "description": "Validation error. Request shape did not match the spec.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "Credit quota exceeded (insufficient_credits). The organization has spent its allowance; nothing is started.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "Trigger disabled or insufficient scope. Run start may return api_trigger_disabled when the API trigger is off, or manual_trigger_disabled for dashboard runs on API-only workflows.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "Organization deletion is in progress (organization_deleting), or an inline subworkflow target is unavailable (inline_invoke_target_unavailable). No run was started.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Payload too large. Upload exceeded the per-request size cap.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded", "headers": { "Retry-After": { "description": "Seconds until the next request may succeed", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Rate-limit accounting is temporarily unavailable. The request was not processed; retry.", "headers": { "Retry-After": { "description": "Seconds until the next request may succeed", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } } } }, "/v1/runs/{id}": { "get": { "operationId": "runs.get", "summary": "Get a run", "description": "Fetch one run by id. By default this returns core metadata plus terminal output/error fields. Pass `?expand=input,usage,execution,debug` to include detailed sub-objects; `expand=execution` is also where embedded review and expected artifacts appear.\n\nHow to read a run: the envelope is at the root. The automation business result is in `output` (per-automation, not this generic schema). HTTP 200 can report a failed run. Inspect `execution.status` and the structured `error` (`code`, `message`, `retryable`, and optional business `statusCode` and `step`). Status is `execution.status` (`execution.retry.nextRun.status` is a later retry). `input`, `usage`, and `debug` appear only with `?expand=`. `eval` is present only on eval-scoped runs.", "tags": [ "Runs" ], "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string", "description": "Run id" }, "required": true, "description": "Run id" }, { "in": "query", "name": "expand", "schema": { "description": "Optional sections: `input`, `usage`, `execution`, `debug`. Terminal runs always include top-level output, files, and error.", "type": "string" }, "description": "Optional sections: `input`, `usage`, `execution`, `debug`. Terminal runs always include top-level output, files, and error." } ], "responses": { "200": { "description": "Run detail. Expanded sections appear only when requested.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Run" } } } }, "400": { "description": "Validation error. Request shape did not match the spec.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "API key lacks required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Payload too large. Upload exceeded the per-request size cap.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded", "headers": { "Retry-After": { "description": "Seconds until the next request may succeed", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Rate-limit accounting is temporarily unavailable. The request was not processed; retry.", "headers": { "Retry-After": { "description": "Seconds until the next request may succeed", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } } } }, "/v1/runs/{id}/artifacts": { "get": { "operationId": "runs.artifacts.list", "summary": "List run artifacts", "description": "Returns a JSON list of downloadable artifact paths for a run. Pass `zip=1` to switch the response to a ZIP download containing output files.", "tags": [ "Runs" ], "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string", "description": "Run id" }, "required": true, "description": "Run id" }, { "in": "query", "name": "zip", "schema": { "description": "When `1`, download output files as a ZIP instead of listing paths. Does not include trace, scores, or input — use `GET /runs/{id}/scores` and `GET /runs/{id}/trace` for those. Cloud deployments reject archives whose uncompressed inputs exceed 32 MiB (`413 artifacts_zip_too_large`); download files individually or pass a smaller `files=` subset.", "type": "string", "enum": [ "1" ] }, "description": "When `1`, download output files as a ZIP instead of listing paths. Does not include trace, scores, or input — use `GET /runs/{id}/scores` and `GET /runs/{id}/trace` for those. Cloud deployments reject archives whose uncompressed inputs exceed 32 MiB (`413 artifacts_zip_too_large`); download files individually or pass a smaller `files=` subset." }, { "in": "query", "name": "bundle", "schema": { "description": "With `zip=1`, use `review` to download a ZIP with `output/` and `expected/` folders (corrected review artifacts).", "type": "string", "enum": [ "review" ] }, "description": "With `zip=1`, use `review` to download a ZIP with `output/` and `expected/` folders (corrected review artifacts)." }, { "in": "query", "name": "token", "schema": { "description": "Signed email download token (zip only; no Bearer required).", "type": "string" }, "description": "Signed email download token (zip only; no Bearer required)." } ], "responses": { "200": { "description": "JSON artifact list, or ZIP bytes when `zip=1`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RunArtifactsResponse" } }, "application/octet-stream": { "schema": { "type": "string", "description": "ZIP archive", "format": "binary" } } } }, "400": { "description": "Validation error. Request shape did not match the spec.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "API key lacks required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Payload too large. Upload exceeded the per-request size cap.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded", "headers": { "Retry-After": { "description": "Seconds until the next request may succeed", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Rate-limit accounting is temporarily unavailable. The request was not processed; retry.", "headers": { "Retry-After": { "description": "Seconds until the next request may succeed", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } } } }, "/v1/runs/{id}/artifacts/{path}": { "get": { "operationId": "runs.artifacts.get", "summary": "Download run artifact", "description": "Download one artifact by path. Cloud deployments may redirect to a short-lived storage URL for large files.", "tags": [ "Runs" ], "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string" }, "required": true }, { "in": "path", "name": "path", "schema": { "type": "string" }, "required": true } ], "responses": { "200": { "description": "Run artifact" }, "302": { "description": "Redirect to a short-lived signed storage download" }, "400": { "description": "Validation error. Request shape did not match the spec.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "API key lacks required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Payload too large. Upload exceeded the per-request size cap.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded", "headers": { "Retry-After": { "description": "Seconds until the next request may succeed", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Rate-limit accounting is temporarily unavailable. The request was not processed; retry.", "headers": { "Retry-After": { "description": "Seconds until the next request may succeed", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } } } }, "/v1/runs/{id}/cancel": { "post": { "operationId": "runs.cancel", "summary": "Cancel run", "description": "Cancel a queued run or request cancellation of an in-flight run.", "tags": [ "Runs" ], "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string" }, "required": true } ], "responses": { "200": { "description": "Cancellation result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RunCancelResponse" } } } }, "400": { "description": "Validation error. Request shape did not match the spec.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "API key lacks required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Payload too large. Upload exceeded the per-request size cap.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded", "headers": { "Retry-After": { "description": "Seconds until the next request may succeed", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Rate-limit accounting is temporarily unavailable. The request was not processed; retry.", "headers": { "Retry-After": { "description": "Seconds until the next request may succeed", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } } } }, "/v1/runs/{id}/events": { "get": { "operationId": "runs.events.list", "summary": "List run events", "description": "List a stable chronological lifecycle timeline for a run.", "tags": [ "Runs" ], "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string", "description": "Run id" }, "required": true, "description": "Run id" } ], "responses": { "200": { "description": "Run events", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RunEventsResponse" } } } }, "400": { "description": "Validation error. Request shape did not match the spec.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "API key lacks required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Payload too large. Upload exceeded the per-request size cap.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded", "headers": { "Retry-After": { "description": "Seconds until the next request may succeed", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Rate-limit accounting is temporarily unavailable. The request was not processed; retry.", "headers": { "Retry-After": { "description": "Seconds until the next request may succeed", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } } } }, "/v1/runs/{id}/promote": { "post": { "operationId": "runs.promote", "summary": "Promote run to example", "description": "Turn a reviewed run into a dataset example. The new example uses the run input and any corrected output/files stored through the review endpoints.", "tags": [ "Reviews" ], "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string", "description": "Run id." }, "required": true, "description": "Run id." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PromoteRunRequest" } } } }, "responses": { "200": { "description": "Created or updated a dataset example from the run", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PromoteRunResponse" } } } }, "400": { "description": "Validation error. Request shape did not match the spec.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "API key lacks required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "The organization is being deleted. Its stored files are being removed, so new work that would write to its storage is refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Payload too large. Upload exceeded the per-request size cap.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded", "headers": { "Retry-After": { "description": "Seconds until the next request may succeed", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Rate-limit accounting is temporarily unavailable. The request was not processed; retry.", "headers": { "Retry-After": { "description": "Seconds until the next request may succeed", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } } } }, "/v1/runs/{id}/rerun": { "post": { "operationId": "runs.rerun", "summary": "Retry run", "description": "Start a new run using the source run input. By default the retry uses the latest automation version; pass `version=original` to pin the same source version as the original run.", "tags": [ "Runs" ], "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string", "description": "Source run id to retry." }, "required": true, "description": "Source run id to retry." }, { "in": "query", "name": "version", "schema": { "description": "Version for the new run. `original` pins the source run. Defaults to latest.", "type": "string" }, "description": "Version for the new run. `original` pins the source run. Defaults to latest." }, { "in": "query", "name": "wait_for_completion", "schema": { "description": "Seconds to wait before returning (max 600). Omit for async.", "type": "integer", "minimum": 0, "maximum": 600 }, "description": "Seconds to wait before returning (max 600). Omit for async." } ], "responses": { "200": { "description": "Rerun reached a terminal status while waiting, including failure. Inspect execution.status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Run" } } } }, "201": { "description": "Rerun accepted (async)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RunAccepted" } } } }, "202": { "description": "Wait expired with a non-terminal status — poll GET /api/v1/runs/:id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RunAccepted" } } } }, "400": { "description": "Validation error. Request shape did not match the spec.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "402": { "description": "Credit quota exceeded. The organization has spent its allowance; nothing was processed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "API key lacks required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "Conflict. The resource is in a state that forbids the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Payload too large. Upload exceeded the per-request size cap.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded", "headers": { "Retry-After": { "description": "Seconds until the next request may succeed", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Rate-limit accounting is temporarily unavailable. The request was not processed; retry.", "headers": { "Retry-After": { "description": "Seconds until the next request may succeed", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } } } }, "/v1/runs/{id}/reviews": { "get": { "operationId": "runs.reviews.get", "summary": "Get run review", "description": "Returns review metadata and corrections for a run. Corrected files are listed at GET /runs/{id}/reviews/expected; embed review + expected artifacts with GET /runs/{id}?expand=execution.", "tags": [ "Reviews" ], "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string", "description": "Run id." }, "required": true, "description": "Run id." } ], "responses": { "200": { "description": "Run review metadata.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RunReviewDetail" } } } }, "400": { "description": "Validation error. Request shape did not match the spec.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "API key lacks required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Payload too large. Upload exceeded the per-request size cap.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded", "headers": { "Retry-After": { "description": "Seconds until the next request may succeed", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Rate-limit accounting is temporarily unavailable. The request was not processed; retry.", "headers": { "Retry-After": { "description": "Seconds until the next request may succeed", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } } }, "put": { "operationId": "runs.reviews.update", "summary": "Update run review", "description": "Create or replace review metadata for a run.", "tags": [ "Reviews" ], "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string", "description": "Run id." }, "required": true, "description": "Run id." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RunReviewRequest" } } } }, "responses": { "200": { "description": "Updated run review metadata.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RunReviewDetail" } } } }, "400": { "description": "Validation error. Request shape did not match the spec.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "API key lacks required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Payload too large. Upload exceeded the per-request size cap.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded", "headers": { "Retry-After": { "description": "Seconds until the next request may succeed", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Rate-limit accounting is temporarily unavailable. The request was not processed; retry.", "headers": { "Retry-After": { "description": "Seconds until the next request may succeed", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } } }, "delete": { "operationId": "runs.reviews.clear", "summary": "Clear run review", "description": "Deletes review metadata, corrections, and corrected files for the run.", "tags": [ "Reviews" ], "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string", "description": "Run id." }, "required": true, "description": "Run id." } ], "responses": { "200": { "description": "Empty run review state.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RunReviewDetail" } } } }, "400": { "description": "Validation error. Request shape did not match the spec.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "API key lacks required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Payload too large. Upload exceeded the per-request size cap.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded", "headers": { "Retry-After": { "description": "Seconds until the next request may succeed", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Rate-limit accounting is temporarily unavailable. The request was not processed; retry.", "headers": { "Retry-After": { "description": "Seconds until the next request may succeed", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } } } }, "/v1/runs/{id}/reviews/expected": { "get": { "operationId": "runs.reviews.expected.get", "summary": "List corrected files", "description": "Returns corrected artifact files attached to the run review. Review metadata and corrected JSON output live at GET /runs/{id}/reviews.", "tags": [ "Reviews" ], "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string", "description": "Run id." }, "required": true, "description": "Run id." } ], "responses": { "200": { "description": "Corrected artifact files.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RunReviewExpectedArtifacts" } } } }, "400": { "description": "Validation error. Request shape did not match the spec.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "API key lacks required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Payload too large. Upload exceeded the per-request size cap.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded", "headers": { "Retry-After": { "description": "Seconds until the next request may succeed", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Rate-limit accounting is temporarily unavailable. The request was not processed; retry.", "headers": { "Retry-After": { "description": "Seconds until the next request may succeed", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } } }, "post": { "operationId": "runs.reviews.expected.create", "summary": "Add corrected file", "description": "Attach one corrected file to a run review. Send multipart/form-data with `file` and optional `name` to upload a local file, or JSON with `outputFileName` and optional `expectedName` to copy an existing run output file.", "tags": [ "Reviews" ], "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string", "description": "Run id." }, "required": true, "description": "Run id." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RunReviewExpectedFileCopyRequest" } }, "multipart/form-data": { "schema": { "$ref": "#/components/schemas/RunReviewExpectedFileUploadRequest" } } } }, "responses": { "201": { "description": "Corrected file created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RunReviewExpectedFileMutationResponse" } } } }, "400": { "description": "Validation error. Request shape did not match the spec.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "API key lacks required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Payload too large. Upload exceeded the per-request size cap.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded", "headers": { "Retry-After": { "description": "Seconds until the next request may succeed", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Rate-limit accounting is temporarily unavailable. The request was not processed; retry.", "headers": { "Retry-After": { "description": "Seconds until the next request may succeed", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } } } }, "/v1/runs/{id}/reviews/expected/{filename}": { "get": { "operationId": "runs.reviews.expected.file.get", "summary": "Download corrected artifact file", "description": "Downloads one corrected artifact file attached to the run review. Use the `filename` returned by the corrected-output collection endpoint.", "tags": [ "Reviews" ], "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string", "description": "Run id." }, "required": true, "description": "Run id." }, { "in": "path", "name": "filename", "schema": { "type": "string", "description": "Corrected artifact file name or slash-delimited path, as returned by `GET /runs/{id}/reviews/expected`." }, "required": true, "description": "Corrected artifact file name or slash-delimited path, as returned by `GET /runs/{id}/reviews/expected`." } ], "responses": { "200": { "description": "Corrected file bytes.", "content": { "application/octet-stream": { "schema": { "type": "string", "description": "Corrected file bytes.", "format": "binary" } } } }, "400": { "description": "Validation error. Request shape did not match the spec.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "API key lacks required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Payload too large. Upload exceeded the per-request size cap.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded", "headers": { "Retry-After": { "description": "Seconds until the next request may succeed", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Rate-limit accounting is temporarily unavailable. The request was not processed; retry.", "headers": { "Retry-After": { "description": "Seconds until the next request may succeed", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } } }, "patch": { "operationId": "runs.reviews.expected.file.update", "summary": "Rename corrected artifact file", "description": "Renames one corrected artifact file attached to the run review.", "tags": [ "Reviews" ], "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string", "description": "Run id." }, "required": true, "description": "Run id." }, { "in": "path", "name": "filename", "schema": { "type": "string", "description": "Corrected artifact file name or slash-delimited path, as returned by `GET /runs/{id}/reviews/expected`." }, "required": true, "description": "Corrected artifact file name or slash-delimited path, as returned by `GET /runs/{id}/reviews/expected`." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RunReviewExpectedFileUpdateRequest" } } } }, "responses": { "200": { "description": "Renamed corrected file.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RunReviewExpectedFileUpdateResponse" } } } }, "400": { "description": "Validation error. Request shape did not match the spec.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "API key lacks required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Payload too large. Upload exceeded the per-request size cap.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded", "headers": { "Retry-After": { "description": "Seconds until the next request may succeed", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Rate-limit accounting is temporarily unavailable. The request was not processed; retry.", "headers": { "Retry-After": { "description": "Seconds until the next request may succeed", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } } }, "delete": { "operationId": "runs.reviews.expected.file.delete", "summary": "Delete corrected artifact file", "description": "Deletes one corrected artifact file attached to the run review.", "tags": [ "Reviews" ], "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string", "description": "Run id." }, "required": true, "description": "Run id." }, { "in": "path", "name": "filename", "schema": { "type": "string", "description": "Corrected artifact file name or slash-delimited path, as returned by `GET /runs/{id}/reviews/expected`." }, "required": true, "description": "Corrected artifact file name or slash-delimited path, as returned by `GET /runs/{id}/reviews/expected`." } ], "responses": { "204": { "description": "Corrected file deleted; no response body." }, "400": { "description": "Validation error. Request shape did not match the spec.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "API key lacks required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Payload too large. Upload exceeded the per-request size cap.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded", "headers": { "Retry-After": { "description": "Seconds until the next request may succeed", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Rate-limit accounting is temporarily unavailable. The request was not processed; retry.", "headers": { "Retry-After": { "description": "Seconds until the next request may succeed", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } } } }, "/v1/runs/{id}/scores": { "get": { "operationId": "runs.scores.list", "summary": "List run evaluator scores", "description": "List automated evaluator results for one run. Use `score` for evaluator output and run reviews for human verdicts.", "tags": [ "Evaluation" ], "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string", "description": "Run id." }, "required": true, "description": "Run id." } ], "responses": { "200": { "description": "Per-evaluator scores for the run", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RunScoresResponse" } } } }, "400": { "description": "Validation error. Request shape did not match the spec.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "API key lacks required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Payload too large. Upload exceeded the per-request size cap.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded", "headers": { "Retry-After": { "description": "Seconds until the next request may succeed", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Rate-limit accounting is temporarily unavailable. The request was not processed; retry.", "headers": { "Retry-After": { "description": "Seconds until the next request may succeed", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } } } }, "/v1/runs/{id}/steps": { "get": { "operationId": "runs.steps.list", "summary": "List run steps", "description": "List slim workflow step rows for a run (no input/output payloads) plus the total count. Fetch a single step for full payloads.", "tags": [ "Runs" ], "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string", "description": "Run id" }, "required": true, "description": "Run id" } ], "responses": { "200": { "description": "Run steps", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RunStepsResponse" } } } }, "400": { "description": "Validation error. Request shape did not match the spec.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "API key lacks required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Payload too large. Upload exceeded the per-request size cap.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded", "headers": { "Retry-After": { "description": "Seconds until the next request may succeed", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Rate-limit accounting is temporarily unavailable. The request was not processed; retry.", "headers": { "Retry-After": { "description": "Seconds until the next request may succeed", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } } } }, "/v1/runs/{id}/steps/{stepExecutionId}": { "get": { "operationId": "runs.steps.get", "summary": "Get a run step", "description": "Return the full single step execution (including input/output) for on-demand inspection. The step must belong to this run or a child invoke-workflow run.", "tags": [ "Runs" ], "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string", "description": "Run id" }, "required": true, "description": "Run id" }, { "in": "path", "name": "stepExecutionId", "schema": { "type": "string", "description": "Step execution id" }, "required": true, "description": "Step execution id" } ], "responses": { "200": { "description": "Full step execution", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RunStepDetailResponse" } } } }, "400": { "description": "Validation error. Request shape did not match the spec.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "API key lacks required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Payload too large. Upload exceeded the per-request size cap.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded", "headers": { "Retry-After": { "description": "Seconds until the next request may succeed", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Rate-limit accounting is temporarily unavailable. The request was not processed; retry.", "headers": { "Retry-After": { "description": "Seconds until the next request may succeed", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } } } }, "/v1/runs/{id}/trace": { "get": { "operationId": "runs.trace.get", "summary": "Get run trace", "description": "Return low-level execution trace events for debugging one run. Workflow runs expose observability phases or step records; agent runs expose parsed trace.jsonl events. The shape is intentionally extensible, but common fields are documented.", "tags": [ "Runs" ], "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string", "description": "Run id." }, "required": true, "description": "Run id." } ], "responses": { "200": { "description": "Run trace events.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RunTraceResponse" } } } }, "400": { "description": "Validation error. Request shape did not match the spec.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "API key lacks required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Payload too large. Upload exceeded the per-request size cap.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded", "headers": { "Retry-After": { "description": "Seconds until the next request may succeed", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Rate-limit accounting is temporarily unavailable. The request was not processed; retry.", "headers": { "Retry-After": { "description": "Seconds until the next request may succeed", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } } } }, "/v1/runs/{id}/usage": { "get": { "operationId": "runs.usage.get", "summary": "Get run usage", "description": "Get token, credit, duration, and execution usage for a run.", "tags": [ "Runs" ], "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string", "description": "Run id" }, "required": true, "description": "Run id" } ], "responses": { "200": { "description": "Run usage", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RunUsageResponse" } } } }, "400": { "description": "Validation error. Request shape did not match the spec.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "API key lacks required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Payload too large. Upload exceeded the per-request size cap.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded", "headers": { "Retry-After": { "description": "Seconds until the next request may succeed", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Rate-limit accounting is temporarily unavailable. The request was not processed; retry.", "headers": { "Retry-After": { "description": "Seconds until the next request may succeed", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } } } }, "/v1/templates": { "get": { "operationId": "templates.list", "summary": "List templates", "description": "List tenant-scoped DOCX and XLSX template resources.", "tags": [ "Templates" ], "parameters": [ { "in": "query", "name": "limit", "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "in": "query", "name": "offset", "schema": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } } ], "responses": { "200": { "description": "Template resources", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListTemplatesResponse" } } } }, "400": { "description": "Validation error. Request shape did not match the spec.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "API key lacks required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Payload too large. Upload exceeded the per-request size cap.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded", "headers": { "Retry-After": { "description": "Seconds until the next request may succeed", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Rate-limit accounting is temporarily unavailable. The request was not processed; retry.", "headers": { "Retry-After": { "description": "Seconds until the next request may succeed", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } } }, "post": { "operationId": "templates.create", "summary": "Upload template", "description": "Create a stable `tmpl_…` resource and its first immutable content revision from a reusable `fileId`. Public SDK helpers `create(file)` and `createFromFileId(fileId)` upload through the Files API when needed, then send this JSON body. Generated clients send `{ fileId }` JSON only. The HTTP route still accepts a multipart `file` for CLI/internal use; that path is not generated into the public SDKs.", "tags": [ "Templates" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TemplateFileReferenceRequest" } } } }, "responses": { "201": { "description": "Created template", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatedTemplate" } } } }, "400": { "description": "Validation error. Request shape did not match the spec.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "API key lacks required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Payload too large. Upload exceeded the per-request size cap.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Validation error. Request shape did not match the spec.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded", "headers": { "Retry-After": { "description": "Seconds until the next request may succeed", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Rate-limit accounting is temporarily unavailable. The request was not processed; retry.", "headers": { "Retry-After": { "description": "Seconds until the next request may succeed", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } } } }, "/v1/templates/{id}": { "get": { "operationId": "templates.get", "summary": "Inspect template", "description": "Get template metadata, checksum, discovered tokens, grammar capabilities, and current immutable revision. Storage keys are never exposed.", "tags": [ "Templates" ], "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string", "pattern": "^tmpl_[A-Za-z0-9_-]{21}$", "description": "Logical template id (tmpl_…)." }, "required": true, "description": "Logical template id (tmpl_…)." } ], "responses": { "200": { "description": "Template inspection", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Template" } } } }, "400": { "description": "Validation error. Request shape did not match the spec.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "API key lacks required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Payload too large. Upload exceeded the per-request size cap.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded", "headers": { "Retry-After": { "description": "Seconds until the next request may succeed", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Rate-limit accounting is temporarily unavailable. The request was not processed; retry.", "headers": { "Retry-After": { "description": "Seconds until the next request may succeed", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } } }, "put": { "operationId": "templates.replace", "summary": "Create template revision", "description": "Append an immutable revision and advance the logical template pointer from a reusable `fileId`. Public SDK helpers `replace(file)` and `replaceFromFileId(fileId)` upload through the Files API when needed, then send this JSON body. Generated clients send `{ fileId }` JSON only. The HTTP route still accepts a multipart `file` for CLI/internal use; that path is not generated into the public SDKs.", "tags": [ "Templates" ], "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string", "pattern": "^tmpl_[A-Za-z0-9_-]{21}$", "description": "Logical template id (tmpl_…)." }, "required": true, "description": "Logical template id (tmpl_…)." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TemplateReplaceRequest" } } } }, "responses": { "200": { "description": "Updated template", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Template" } } } }, "400": { "description": "Validation error. Request shape did not match the spec.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "API key lacks required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Payload too large. Upload exceeded the per-request size cap.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "422": { "description": "Validation error. Request shape did not match the spec.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded", "headers": { "Retry-After": { "description": "Seconds until the next request may succeed", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Rate-limit accounting is temporarily unavailable. The request was not processed; retry.", "headers": { "Retry-After": { "description": "Seconds until the next request may succeed", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } } }, "delete": { "operationId": "templates.delete", "summary": "Delete template", "description": "Delete the mutable logical template. Immutable revisions are retained so workflows pinned with `templateRevisionId` continue to execute; unpinned workflows can no longer resolve the deleted `tmpl_…` id.", "tags": [ "Templates" ], "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string", "pattern": "^tmpl_[A-Za-z0-9_-]{21}$", "description": "Logical template id (tmpl_…)." }, "required": true, "description": "Logical template id (tmpl_…)." } ], "responses": { "200": { "description": "Template deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteTemplateResponse" } } } }, "400": { "description": "Validation error. Request shape did not match the spec.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "API key lacks required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Payload too large. Upload exceeded the per-request size cap.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded", "headers": { "Retry-After": { "description": "Seconds until the next request may succeed", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Rate-limit accounting is temporarily unavailable. The request was not processed; retry.", "headers": { "Retry-After": { "description": "Seconds until the next request may succeed", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } } } }, "/v1/templates/{id}/content": { "get": { "operationId": "templates.content.get", "summary": "Download template content", "description": "Download current bytes while the logical template exists, or a specific immutable revision using `revisionId`. Pinned revision downloads remain available after logical template deletion. Large objects may 302 to a short-lived signed storage URL.", "tags": [ "Templates" ], "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string", "pattern": "^tmpl_[A-Za-z0-9_-]{21}$", "description": "Logical template id (tmpl_…)." }, "required": true, "description": "Logical template id (tmpl_…)." }, { "in": "query", "name": "revisionId", "schema": { "description": "Immutable revision id (tmpr_…). Omit for the current content.", "type": "string", "pattern": "^tmpr_[A-Za-z0-9_-]{21}$" }, "description": "Immutable revision id (tmpr_…). Omit for the current content." } ], "responses": { "200": { "description": "Template binary content", "content": { "application/octet-stream": { "schema": { "type": "string", "description": "Template file bytes (DOCX or XLSX).", "format": "binary" } } } }, "302": { "description": "Redirect to a short-lived signed storage download" }, "400": { "description": "Validation error. Request shape did not match the spec.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "API key lacks required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Payload too large. Upload exceeded the per-request size cap.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded", "headers": { "Retry-After": { "description": "Seconds until the next request may succeed", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Rate-limit accounting is temporarily unavailable. The request was not processed; retry.", "headers": { "Retry-After": { "description": "Seconds until the next request may succeed", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } } } }, "/v1/templates/{id}/staging": { "post": { "operationId": "templates.staging", "summary": "Finalize or hard-clean a staged template", "description": "Consume the one-time cleanupProof issued on a staged create. `finalize` makes the template live so later deletion keeps pinned revisions. `cleanup` hard-removes only unpublished resources from that staging attempt. Normal DELETE is unchanged and never takes this path.", "tags": [ "Templates" ], "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string", "pattern": "^tmpl_[A-Za-z0-9_-]{21}$", "description": "Logical template id (tmpl_…)." }, "required": true, "description": "Logical template id (tmpl_…)." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TemplateStagingRequest" } } } }, "responses": { "200": { "description": "Staging action applied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TemplateStagingResponse" } } } }, "400": { "description": "Validation error. Request shape did not match the spec.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "403": { "description": "API key lacks required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "409": { "description": "Conflict. The resource is in a state that forbids the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "413": { "description": "Payload too large. Upload exceeded the per-request size cap.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded", "headers": { "Retry-After": { "description": "Seconds until the next request may succeed", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } }, "503": { "description": "Rate-limit accounting is temporarily unavailable. The request was not processed; retry.", "headers": { "Retry-After": { "description": "Seconds until the next request may succeed", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelope" } } } } } } } }, "components": { "schemas": { "UpdateAutomationRequest": { "type": "object", "properties": { "folderId": { "description": "Move a YAML workflow into this workflow folder. `null` files it at the tenant root. Ignored for the folder lookup when `folderPath` is also sent, but a string value is still validated before the path is applied.", "type": [ "string", "null" ] }, "folderPath": { "description": "Slash-separated workflow folder path. Missing folders are created. Empty or `/` means root. When both fields are sent, `folderPath` wins after `folderId` validation.", "type": "string" } } }, "CreateDatasetReviewRequest": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1 }, "instructions": { "description": "Note shown to the reviewer for the whole request.", "type": [ "string", "null" ] }, "focusFields": { "description": "Expected-output paths to highlight. Other fields stay normal unless listed in ignoredFields.", "type": "array", "items": { "$ref": "#/components/schemas/DatasetReviewFocusField" } }, "ignoredFields": { "description": "Expected-output paths reviewers can skip. Shown muted as not required. Prefixes apply to nested leaves.", "type": "array", "items": { "type": "string", "minLength": 1 } }, "itemNotes": { "description": "Optional per-example and per-field notes seeded as commented events at create time.", "type": "array", "items": { "$ref": "#/components/schemas/DatasetReviewCreateItemNote" } }, "exampleNames": { "minItems": 1, "type": "array", "items": { "type": "string", "minLength": 1 } }, "status": { "type": "string", "enum": [ "draft", "open", "paused" ] } }, "required": [ "title", "exampleNames" ] }, "DatasetReviewFocusField": { "type": "object", "properties": { "path": { "type": "string", "minLength": 1, "description": "Dotted expected-output path the reviewer should inspect, e.g. vendor.iban." }, "reason": { "description": "Optional reason this field needs attention.", "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] } }, "required": [ "path" ] }, "DatasetReviewCreateItemNote": { "type": "object", "properties": { "exampleName": { "type": "string", "minLength": 1 }, "comment": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "fields": { "type": "array", "items": { "$ref": "#/components/schemas/DatasetReviewItemFieldNote" } } }, "required": [ "exampleName" ] }, "DatasetReviewItemFieldNote": { "type": "object", "properties": { "path": { "type": "string", "minLength": 1 }, "comment": { "type": "string", "minLength": 1 } }, "required": [ "path", "comment" ] }, "UpdateDatasetReviewRequest": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1 }, "instructions": { "type": [ "string", "null" ] }, "focusFields": { "type": "array", "items": { "$ref": "#/components/schemas/DatasetReviewFocusField" } }, "ignoredFields": { "type": "array", "items": { "type": "string", "minLength": 1 } }, "status": { "type": "string", "enum": [ "draft", "open", "paused", "closed", "cancelled" ] } }, "additionalProperties": false }, "UpdateDatasetReviewItem": { "type": "object", "properties": { "action": { "type": "string", "enum": [ "approve", "edit", "remove", "reopen", "comment", "field-decision", "file-decision", "edit-file" ], "description": "file-decision records a per-expected-file approve/remove (or a note). edit-file uploads corrected bytes and is multipart-only — JSON callers get a 400 pointing at the multipart form." }, "expected": {}, "comment": { "type": [ "string", "null" ] }, "fieldPath": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "filePath": { "description": "Expected-file path for action file-decision.", "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "decision": { "anyOf": [ { "type": "string", "enum": [ "approved", "removed" ] }, { "type": "null" } ] }, "expectedUpdatedAt": { "type": "string", "minLength": 1, "description": "ISO timestamp of the item `updatedAt` the client last observed. Required for optimistic concurrency." } }, "required": [ "action", "expectedUpdatedAt" ] }, "EditDatasetReviewItemFile": { "type": "object", "properties": { "action": { "description": "Must be edit-file for the multipart item PATCH form.", "type": "string", "const": "edit-file" }, "file": { "description": "Corrected expected-file bytes (50MB cap).", "format": "binary", "type": "string" }, "filePath": { "type": "string", "minLength": 1 }, "newPath": { "type": "string", "minLength": 1 }, "comment": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "expectedUpdatedAt": { "type": "string", "minLength": 1 } }, "required": [ "expectedUpdatedAt" ] }, "AutomationDatasetImportMultipartRequest": { "type": "object", "properties": { "file": { "type": "string", "description": "Dataset ZIP file", "format": "binary" }, "mode": { "description": "`append` adds examples without deleting existing rows. `replace` deletes the current dataset before importing.", "type": "string", "enum": [ "append", "replace" ] } }, "required": [ "file" ] }, "EvaluatorConfigUpdate": { "type": "object", "properties": { "yaml": { "type": "string", "minLength": 1, "maxLength": 1048576, "description": "Complete evaluator YAML to validate and store." } }, "required": [ "yaml" ], "description": "Replacement evaluator configuration." }, "DatasetExampleMutation": { "type": "object", "properties": { "name": { "description": "Example name. Required on create; omitted or null uses a generated name where supported.", "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 128 }, { "type": "null" } ] }, "input": { "description": "Input arguments for the example.", "anyOf": [ { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, { "type": "null" } ] }, "expected": { "description": "Expected JSON output. Null clears the expected output.", "anyOf": [ {}, { "type": "null" } ] }, "metadata": { "description": "Caller-managed metadata.", "anyOf": [ { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, { "type": "null" } ] }, "annotation": { "description": "Human note about the example. Null clears the annotation.", "anyOf": [ { "type": "string", "maxLength": 2000 }, { "type": "null" } ] }, "rowOrder": { "description": "Optional display order. Null clears the order.", "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "overrides": { "description": "Step output overrides used during example runs.", "anyOf": [ { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, { "type": "null" } ] } }, "description": "Fields used to create or update a dataset example." }, "DatasetExampleUpdate": { "type": "object", "properties": { "name": { "description": "Example name. Required on create; omitted or null uses a generated name where supported.", "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 128 }, { "type": "null" } ] }, "input": { "description": "Input arguments for the example.", "anyOf": [ { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, { "type": "null" } ] }, "expected": { "description": "Expected JSON output. Null clears the expected output.", "anyOf": [ {}, { "type": "null" } ] }, "metadata": { "description": "Caller-managed metadata.", "anyOf": [ { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, { "type": "null" } ] }, "annotation": { "description": "Human note about the example. Null clears the annotation.", "anyOf": [ { "type": "string", "maxLength": 2000 }, { "type": "null" } ] }, "rowOrder": { "description": "Optional display order. Null clears the order.", "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "overrides": { "description": "Step output overrides used during example runs.", "anyOf": [ { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, { "type": "null" } ] } }, "additionalProperties": false, "description": "Partial update for a dataset example. Omitted fields are preserved." }, "DatasetExampleExpectedFileUploadRequest": { "type": "object", "properties": { "file": { "type": "array", "items": { "type": "string", "format": "binary" }, "description": "One or more expected files to upload." } }, "required": [ "file" ] }, "DatasetExampleExpectedFileRenameRequest": { "type": "object", "properties": { "newFilename": { "type": "string", "description": "New basename for the file. The parent folder is preserved." } }, "required": [ "newFilename" ] }, "DatasetExampleInputFileUploadRequest": { "type": "object", "properties": { "file": { "type": "array", "items": { "type": "string", "format": "binary" }, "description": "One or more input files to upload." } }, "required": [ "file" ] }, "DatasetExampleInputFileRenameRequest": { "type": "object", "properties": { "newFilename": { "type": "string", "description": "New basename for the file. The parent folder is preserved." } }, "required": [ "newFilename" ] }, "ExperimentCreate": { "type": "object", "properties": { "examples": { "description": "Optional dataset example ids to run. Omit to run the full dataset.", "type": "array", "items": { "type": "string" } }, "batchConcurrency": { "description": "Maximum concurrent example runs for this experiment.", "anyOf": [ { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "sourceRef": { "description": "Optional source version/ref to use for experiment runs.", "type": "string" } }, "description": "Request body for starting an experiment batch." }, "CreateAutomationVersionRequest": { "anyOf": [ { "type": "object", "properties": { "yaml": { "type": "string", "minLength": 1, "maxLength": 1048576, "description": "Validated workflow YAML to publish as a new tagged version. Mutually exclusive with `historyId`. At most 1 MiB." }, "version": { "type": "string", "pattern": "^\\d+\\.\\d+\\.\\d+$", "description": "Bare semver tag such as 1.2.0. Do not include a leading v." }, "activate": { "description": "Whether to make the new version current immediately. Defaults to true. Set false to keep a tagged candidate off live traffic until promote. `activate: false` requires an existing current workflow version and returns 400 if HEAD is empty.", "type": "boolean" } }, "required": [ "yaml", "version" ], "additionalProperties": false }, { "type": "object", "properties": { "historyId": { "type": "string", "minLength": 1, "description": "Existing version id from GET /automations/{id}/versions. Creates a new tagged snapshot copied from that version; the source tag is left unchanged. Mutually exclusive with `yaml`." }, "version": { "type": "string", "pattern": "^\\d+\\.\\d+\\.\\d+$", "description": "Bare semver tag such as 1.2.0. Do not include a leading v." }, "activate": { "description": "Whether to make the new version current immediately. Defaults to true. Set false to keep a tagged candidate off live traffic until promote. `activate: false` requires an existing current workflow version and returns 400 if HEAD is empty.", "type": "boolean" } }, "required": [ "historyId", "version" ], "additionalProperties": false } ], "description": "Exactly one of `yaml` or `historyId`, plus a bare semver `version`. YAML is capped at 1 MiB. `historyId` copies the selected snapshot into a new tagged row and does not retag the source. Set `activate: false` to create a detached candidate that does not move live HEAD; that path requires an existing current version." }, "RestoreAutomationVersionRequest": { "type": "object", "properties": { "message": { "description": "Optional restore commit message. Defaults to a timestamped restore note.", "type": "string" } }, "description": "Optional JSON body. Send `{}` when no message is needed. Restore always creates a new untagged current snapshot; it does not retag the source version." }, "CreateEmailServerRequest": { "oneOf": [ { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 128 }, "enabled": { "default": true, "type": "boolean" }, "transport": { "type": "string", "const": "resend" }, "apiKey": { "type": "string", "minLength": 1 }, "fromEmail": { "type": "string", "format": "email", "pattern": "^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" }, "fromName": { "type": "string", "minLength": 1, "maxLength": 128 } }, "required": [ "name", "transport", "apiKey", "fromEmail", "fromName" ], "additionalProperties": false }, { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 128 }, "enabled": { "default": true, "type": "boolean" }, "transport": { "type": "string", "const": "smtp" }, "host": { "type": "string", "minLength": 1, "maxLength": 253 }, "port": { "type": "integer", "minimum": 1, "maximum": 65535 }, "security": { "default": "starttls", "type": "string", "enum": [ "starttls", "tls", "none" ] }, "username": { "type": "string", "minLength": 1, "maxLength": 256 }, "password": { "type": "string", "minLength": 1 }, "caPem": { "type": "string", "minLength": 1 }, "fromEmail": { "type": "string", "format": "email", "pattern": "^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" }, "fromName": { "type": "string", "minLength": 1, "maxLength": 128 } }, "required": [ "name", "transport", "host", "fromEmail", "fromName" ], "additionalProperties": false } ], "type": "object" }, "UpdateEmailServerRequest": { "oneOf": [ { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 128 }, "enabled": { "type": "boolean" }, "transport": { "type": "string", "const": "resend" }, "apiKey": { "type": "string", "minLength": 1 }, "fromEmail": { "type": "string", "format": "email", "pattern": "^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" }, "fromName": { "type": "string", "minLength": 1, "maxLength": 128 } }, "required": [ "transport", "fromEmail", "fromName" ], "additionalProperties": false }, { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 128 }, "enabled": { "type": "boolean" }, "transport": { "type": "string", "const": "smtp" }, "host": { "type": "string", "minLength": 1, "maxLength": 253 }, "port": { "type": "integer", "minimum": 1, "maximum": 65535 }, "security": { "type": "string", "enum": [ "starttls", "tls", "none" ] }, "username": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 256 }, { "type": "null" } ] }, "password": { "type": "string", "minLength": 1 }, "caPem": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "fromEmail": { "type": "string", "format": "email", "pattern": "^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" }, "fromName": { "type": "string", "minLength": 1, "maxLength": 128 } }, "required": [ "transport", "host", "port", "security", "fromEmail", "fromName" ], "additionalProperties": false }, { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 128 }, "enabled": { "type": "boolean" }, "transport": { "not": {} } }, "additionalProperties": false } ], "type": "object" }, "TestEmailServerRequest": { "type": "object", "properties": { "to": { "type": "string", "format": "email", "pattern": "^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" } }, "required": [ "to" ], "additionalProperties": false }, "CreateFileMultipartRequest": { "type": "object", "properties": { "file": { "type": "string", "description": "Binary file field", "format": "binary" }, "purpose": { "description": "Optional lifecycle marker. `run-input` marks a retry-safe temporary run pre-upload reaped after 24 hours. `builder-attachment` marks a Studio builder intermediary (any MIME) with the same TTL.", "type": "string", "enum": [ "run-input", "builder-attachment" ] } }, "required": [ "file" ] }, "CreateFileUploadSessionRequest": { "type": "object", "properties": { "filename": { "type": "string", "minLength": 1, "maxLength": 255 }, "contentType": { "type": "string", "minLength": 1, "maxLength": 255 }, "size": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "purpose": { "type": "string", "enum": [ "run-input", "builder-attachment" ] }, "idempotencyKey": { "type": "string", "minLength": 1, "maxLength": 256 } }, "required": [ "filename", "contentType", "size" ] }, "PresignFileUploadPartRequest": { "type": "object", "properties": { "partNumber": { "type": "integer", "minimum": 1, "maximum": 10000 } }, "required": [ "partNumber" ] }, "FolderType": { "type": "string", "enum": [ "workflow", "template" ] }, "CreateFolderRequest": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Folder name. Cannot contain `/`." }, "type": { "description": "Which folder tree to create in. Required; there is no default.", "$ref": "#/components/schemas/FolderType" }, "parentId": { "description": "Parent folder id. Omit or `null` to create at the tree root.", "type": [ "string", "null" ] } }, "required": [ "name", "type" ] }, "UpdateFolderRequest": { "type": "object", "properties": { "name": { "description": "New folder name. Cannot contain `/`.", "type": "string", "minLength": 1, "maxLength": 255 }, "parentId": { "description": "New parent folder id. `null` moves the folder to the tree root.", "type": [ "string", "null" ] } } }, "RunStartBody": { "type": "object", "properties": { "tags": { "description": "One exact tag or a list of up to 100 (256 characters each). Tags are returned on the run and in every webhook event as `data.run.tags`, so use them to carry your own correlation IDs.", "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 256 }, { "maxItems": 100, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 256 } } ] }, "target": { "type": "string", "minLength": 1, "description": "Automation target without a version suffix, e.g. workflows.invoice or agents.support." }, "input": { "description": "Scalar and structured automation arguments.", "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "files": { "description": "File inputs as ingress references (`{ \"$fileId\": \"file_...\" }` or `{ \"$inline\": { filename, mimeType, base64 } }`). Upload bytes via multipart `files.` parts instead.", "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "anyOf": [ { "anyOf": [ { "type": "object", "properties": { "$fileId": { "type": "string", "minLength": 1, "description": "Reusable file-pool id to materialize" } }, "required": [ "$fileId" ], "additionalProperties": false }, { "type": "object", "properties": { "$inline": { "type": "object", "properties": { "filename": { "type": "string", "minLength": 1, "description": "Original filename for the materialized artifact" }, "mimeType": { "type": "string", "minLength": 1, "description": "MIME type for the materialized artifact" }, "base64": { "type": "string", "minLength": 1, "description": "Base64-encoded file bytes" } }, "required": [ "filename", "mimeType", "base64" ], "additionalProperties": false } }, "required": [ "$inline" ], "additionalProperties": false } ] }, { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "$fileId": { "type": "string", "minLength": 1, "description": "Reusable file-pool id to materialize" } }, "required": [ "$fileId" ], "additionalProperties": false }, { "type": "object", "properties": { "$inline": { "type": "object", "properties": { "filename": { "type": "string", "minLength": 1, "description": "Original filename for the materialized artifact" }, "mimeType": { "type": "string", "minLength": 1, "description": "MIME type for the materialized artifact" }, "base64": { "type": "string", "minLength": 1, "description": "Base64-encoded file bytes" } }, "required": [ "filename", "mimeType", "base64" ], "additionalProperties": false } }, "required": [ "$inline" ], "additionalProperties": false } ] } } ] } }, "overrides": { "description": "Per-step output overrides. Workflow runs only.", "type": "object", "properties": { "steps": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } } } }, "metadata": { "description": "Caller-supplied run metadata.", "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "target" ], "description": "Run envelope. Declare provenance with the `X-Eigenpal-Trigger` header (`api` or `cli`). Legacy 0.5.12 body shapes remain accepted." }, "RunStartMultipartRequest": { "type": "object", "properties": { "tags": { "description": "JSON string or string array of exact execution tags. Returned in every webhook event as `data.run.tags`.", "type": "string" }, "target": { "type": "string", "description": "Automation target, e.g. `workflows.invoice`." }, "input": { "description": "JSON-encoded scalar input object.", "type": "string" }, "overrides": { "description": "JSON-encoded step overrides.", "type": "string" }, "metadata": { "description": "JSON-encoded run metadata.", "type": "string" } }, "required": [ "target" ], "additionalProperties": { "description": "Dynamic binary fields like `files.`." } }, "PromoteRunRequest": { "type": "object", "properties": { "name": { "description": "Dataset example name to create or update. Defaults to a generated name when omitted.", "type": "string", "minLength": 1, "maxLength": 128 } }, "description": "Create or update a dataset example from the run input, actual output, and review corrections." }, "RunReviewRequest": { "type": "object", "properties": { "verdict": { "description": "Reviewer verdict. Omit or send null for feedback without a ranking (nit). Defaults are applied client-side only; any verdict/status combination is accepted.", "anyOf": [ { "type": "string", "enum": [ "correct", "incorrect" ] }, { "type": "null" } ] }, "status": { "description": "Review lifecycle. Defaults from verdict (`correct` → `closed`, otherwise `open`). Use `closed` or `wont_fix` to close an open review.", "type": "string", "enum": [ "open", "closed", "wont_fix" ] }, "note": { "description": "Reviewer note.", "type": [ "string", "null" ] }, "correctedOutput": { "description": "Corrected JSON output for this run. Send `null` to clear a previously stored correction.", "anyOf": [ {}, { "type": "null" } ] }, "corrections": { "description": "Field and file corrections. When present, replaces the entire correction set for this review. Omit to leave existing corrections unchanged.", "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "kind": { "type": "string", "enum": [ "field", "file" ] }, "path": { "type": "string", "minLength": 1 }, "label": { "type": [ "string", "null" ] }, "originalValue": {}, "correctedValue": {}, "note": { "type": [ "string", "null" ] }, "correctedArtifactPath": { "type": [ "string", "null" ] } }, "required": [ "kind", "path" ] } } }, "description": "Create or replace review metadata for a run. Attribution fields (`reviewedBy`, `closedBy`, and their emails) are read-only and populated from the authenticated user or API key creator." }, "RunReviewExpectedFileCopyRequest": { "type": "object", "properties": { "outputFileName": { "type": "string", "description": "Name of an existing run output file to copy into corrected artifacts." }, "expectedName": { "description": "Optional name for the copied corrected file. Defaults to the original output file name.", "type": "string" } }, "required": [ "outputFileName" ], "description": "JSON request body for copying one run output file into the corrected artifact set." }, "RunReviewExpectedFileUploadRequest": { "type": "object", "properties": { "file": { "type": "string", "description": "Corrected artifact file to upload.", "format": "binary" }, "name": { "description": "Optional stored corrected file name. Defaults to the uploaded filename.", "type": "string" } }, "required": [ "file" ] }, "RunReviewExpectedFileUpdateRequest": { "type": "object", "properties": { "name": { "type": "string", "description": "New corrected file name." } }, "required": [ "name" ], "description": "Rename one corrected file." }, "TemplateFileReferenceRequest": { "type": "object", "properties": { "fileId": { "type": "string", "pattern": "^file_[A-Za-z0-9_-]{21}$", "description": "Reusable file id produced by the direct file upload flow. It is consumed as upload transport, not exposed as template identity." }, "name": { "type": "string" }, "description": { "type": "string" }, "staged": { "description": "When true, the create response includes a one-time cleanupProof for unpublished CLI staging. Normal uploads omit this.", "type": "boolean" } }, "required": [ "fileId" ] }, "TemplateReplaceRequest": { "type": "object", "properties": { "fileId": { "type": "string", "pattern": "^file_[A-Za-z0-9_-]{21}$", "description": "Reusable file id produced by the direct file upload flow. It is consumed as upload transport, not exposed as template identity." } }, "required": [ "fileId" ] }, "TemplateStagingRequest": { "type": "object", "properties": { "proof": { "type": "string", "minLength": 16, "maxLength": 128 }, "action": { "type": "string", "enum": [ "cleanup", "finalize" ] } }, "required": [ "proof", "action" ] }, "AuthCheckResponse": { "type": "object", "properties": { "ok": { "type": "boolean", "const": true }, "tenantId": { "type": "string" }, "tenantSlug": { "type": "string" }, "tenantName": { "type": [ "string", "null" ] }, "userId": { "type": [ "string", "null" ] }, "keyId": { "type": "string" }, "email": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "scope": { "type": "array", "items": { "type": "string" } }, "wildcardGranted": { "type": "boolean" } }, "required": [ "ok", "tenantId", "tenantSlug", "tenantName", "userId", "keyId", "email", "name", "scope", "wildcardGranted" ], "additionalProperties": false }, "ApiErrorEnvelope": { "type": "object", "properties": { "issues": { "type": "array", "items": { "$ref": "#/components/schemas/ApiErrorIssue" } }, "requestId": { "type": "string", "description": "Request id echoed via the x-request-id header" }, "hint": { "description": "Suggested fix for known error patterns", "type": "string" }, "docsUrl": { "description": "Link to relevant docs", "type": "string" }, "conflictingWorkflowId": { "description": "Present on 409 workflow_name_conflict responses. Id of the workflow that already owns the requested name.", "type": "string" } }, "required": [ "issues", "requestId" ], "additionalProperties": false }, "ApiErrorIssue": { "type": "object", "properties": { "field": { "type": "string", "description": "JSON path of the offending field, or \"\"" }, "message": { "type": "string", "description": "Human-readable error message" }, "code": { "type": "string", "description": "Machine-readable error code (e.g. invalid_value, not_found, api_trigger_disabled, manual_trigger_disabled)" }, "severity": { "type": "string", "enum": [ "error", "warning" ], "description": "Issue severity" } }, "required": [ "field", "message", "code", "severity" ], "additionalProperties": false }, "ListAutomationsResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/AutomationSummary" } }, "total": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "limit": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "offset": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "data", "total", "limit", "offset" ], "additionalProperties": false }, "AutomationSummary": { "type": "object", "properties": { "id": { "type": "string", "description": "Implementation id for the automation. Workflow automations use workflow ids; agent automations use agent workflow ids." }, "type": { "$ref": "#/components/schemas/AutomationType" }, "slug": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "status": { "type": "string" }, "version": { "type": [ "string", "null" ] }, "triggers": { "$ref": "#/components/schemas/AutomationTriggerState" }, "implementationAvailable": { "description": "False when the automations registry row exists but the workflow/agent implementation row is missing.", "type": "boolean" }, "folderId": { "description": "Workflow folder id. Null for unfiled workflows, agent automations, and orphan registry rows.", "type": [ "string", "null" ] }, "folderPath": { "description": "Slash-separated workflow folder path from the tenant root, such as `billing/invoices`. Null at root and for agent automations.", "type": [ "string", "null" ] }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "type", "slug", "name", "folderId", "folderPath", "createdAt" ], "additionalProperties": false }, "AutomationType": { "type": "string", "enum": [ "workflow", "agent" ] }, "AutomationTriggerState": { "type": "object", "properties": { "api": { "type": "boolean" }, "email": { "type": "boolean" }, "manual": { "type": "boolean" }, "cron": { "type": "boolean" } }, "required": [ "api", "email", "manual", "cron" ], "additionalProperties": false }, "AutomationDetail": { "type": "object", "properties": { "id": { "type": "string", "description": "Implementation id for the automation. Workflow automations use workflow ids; agent automations use agent workflow ids." }, "type": { "$ref": "#/components/schemas/AutomationType" }, "slug": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "status": { "type": "string" }, "version": { "type": [ "string", "null" ] }, "triggers": { "$ref": "#/components/schemas/AutomationTriggerState" }, "implementationAvailable": { "description": "False when the automations registry row exists but the workflow/agent implementation row is missing.", "type": "boolean" }, "folderId": { "description": "Workflow folder id. Null for unfiled workflows, agent automations, and orphan registry rows.", "type": [ "string", "null" ] }, "folderPath": { "description": "Slash-separated workflow folder path from the tenant root, such as `billing/invoices`. Null at root and for agent automations.", "type": [ "string", "null" ] }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" }, "inputSchema": { "anyOf": [ { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, { "type": "null" } ] }, "outputSchema": { "anyOf": [ { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, { "type": "null" } ] } }, "required": [ "id", "type", "slug", "name", "folderId", "folderPath", "createdAt" ], "additionalProperties": false }, "DeleteAutomationResponse": { "type": "object", "properties": { "deleted": { "type": "boolean", "const": true }, "id": { "type": "string" } }, "required": [ "deleted", "id" ], "additionalProperties": false }, "DatasetReviewRequestList": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/DatasetReviewRequest" } }, "total": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "limit": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "offset": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "data", "total", "limit", "offset" ], "additionalProperties": false }, "DatasetReviewRequest": { "type": "object", "properties": { "id": { "type": "string" }, "automationId": { "type": "string" }, "title": { "type": "string" }, "instructions": { "type": [ "string", "null" ] }, "focusFields": { "type": "array", "items": { "$ref": "#/components/schemas/DatasetReviewFocusFieldOutput" } }, "ignoredFields": { "type": "array", "items": { "type": "string" } }, "status": { "type": "string", "enum": [ "draft", "open", "paused", "closed", "cancelled" ] }, "exampleNames": { "type": "array", "items": { "type": "string" } }, "progress": { "$ref": "#/components/schemas/DatasetReviewProgress" }, "createdBy": { "type": [ "string", "null" ] }, "createdAt": { "type": "string" }, "closedAt": { "type": [ "string", "null" ] } }, "required": [ "id", "automationId", "title", "instructions", "focusFields", "ignoredFields", "status", "exampleNames", "progress", "createdBy", "createdAt", "closedAt" ], "additionalProperties": false }, "DatasetReviewProgress": { "type": "object", "properties": { "total": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "pending": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "approved": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "edited": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "removed": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "remaining": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Count of examples still pending a decision." }, "complete": { "type": "boolean", "description": "True when every example has been approved, edited, or removed. Close the request when review is finished; dataset write-back is always manual." } }, "required": [ "total", "pending", "approved", "edited", "removed", "remaining", "complete" ], "additionalProperties": false }, "DatasetReviewDetail": { "type": "object", "properties": { "id": { "type": "string" }, "automationId": { "type": "string" }, "title": { "type": "string" }, "instructions": { "type": [ "string", "null" ] }, "focusFields": { "type": "array", "items": { "$ref": "#/components/schemas/DatasetReviewFocusFieldOutput" } }, "ignoredFields": { "type": "array", "items": { "type": "string" } }, "status": { "type": "string", "enum": [ "draft", "open", "paused", "closed", "cancelled" ] }, "exampleNames": { "type": "array", "items": { "type": "string" } }, "progress": { "$ref": "#/components/schemas/DatasetReviewProgress" }, "createdBy": { "type": [ "string", "null" ] }, "createdAt": { "type": "string" }, "closedAt": { "type": [ "string", "null" ] }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/DatasetReviewItem" } }, "events": { "type": "array", "items": { "$ref": "#/components/schemas/DatasetReviewEvent" } } }, "required": [ "id", "automationId", "title", "instructions", "focusFields", "ignoredFields", "status", "exampleNames", "progress", "createdBy", "createdAt", "closedAt", "items" ], "additionalProperties": false }, "DatasetReviewItem": { "type": "object", "properties": { "id": { "type": "string" }, "reviewId": { "type": "string" }, "exampleName": { "type": "string" }, "snapshotInputJson": { "anyOf": [ { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, { "type": "null" } ] }, "snapshotExpectedJson": { "anyOf": [ {}, { "type": "null" } ] }, "snapshotManifest": { "type": "object", "properties": { "expectedFiles": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" } }, "required": [ "name" ], "additionalProperties": false } }, "metadata": { "anyOf": [ { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, { "type": "null" } ] }, "inputFileHashes": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "sha256": { "type": "string" } }, "required": [ "path", "sha256" ], "additionalProperties": false } } }, "required": [ "expectedFiles", "metadata" ], "additionalProperties": false }, "status": { "type": "string", "enum": [ "pending", "approved", "edited", "removed" ] }, "currentExpectedJson": { "anyOf": [ {}, { "type": "null" } ] }, "fieldDecisions": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "$ref": "#/components/schemas/DatasetReviewFieldDecision" } }, "currentExpectedFiles": { "anyOf": [ { "type": "array", "items": { "$ref": "#/components/schemas/DatasetReviewExpectedFile" } }, { "type": "null" } ], "description": "Overlay of the snapshot manifest expected files. Null means pristine — the reviewer has not corrected or uploaded any file yet." }, "fileDecisions": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "$ref": "#/components/schemas/DatasetReviewFileDecision" }, "description": "Durable per-expected-file approve/remove, keyed by expected-file path." }, "inputDrifted": { "type": "boolean", "description": "True when live dataset input-file bytes no longer match the hashes captured at request creation." }, "updatedBy": { "type": [ "string", "null" ] }, "updatedAt": { "type": "string" } }, "required": [ "id", "reviewId", "exampleName", "snapshotInputJson", "snapshotExpectedJson", "snapshotManifest", "status", "currentExpectedJson", "fieldDecisions", "currentExpectedFiles", "fileDecisions", "inputDrifted", "updatedBy", "updatedAt" ], "additionalProperties": false }, "DatasetReviewFieldDecision": { "type": "object", "properties": { "decision": { "type": "string", "enum": [ "approved", "removed" ] }, "comment": { "type": [ "string", "null" ] }, "reviewerId": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "decision", "reviewerId", "updatedAt" ], "additionalProperties": false }, "DatasetReviewExpectedFile": { "type": "object", "properties": { "path": { "type": "string", "description": "Expected-file path relative to the example expected/ folder." }, "fileId": { "type": "string", "description": "Version id for the current bytes. Empty for snapshot-origin files, which resolve by path." }, "filename": { "type": "string" }, "origin": { "type": "string", "enum": [ "snapshot", "corrected", "uploaded" ], "description": "Whether the current bytes are the snapshotted dataset file, a reviewer-corrected version, or a brand-new reviewer upload." } }, "required": [ "path", "fileId", "filename", "origin" ], "additionalProperties": false }, "DatasetReviewFileDecision": { "type": "object", "properties": { "decision": { "type": "string", "enum": [ "approved", "removed" ] }, "comment": { "type": [ "string", "null" ] }, "reviewerId": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "decision", "reviewerId", "updatedAt" ], "additionalProperties": false }, "DatasetReviewEvent": { "type": "object", "properties": { "id": { "type": "string" }, "reviewId": { "type": "string" }, "itemId": { "type": [ "string", "null" ] }, "actorUserId": { "type": [ "string", "null" ] }, "action": { "type": "string", "enum": [ "created", "approved", "edited", "removed", "reopened", "commented", "field-decision", "file-decision", "file-edited" ] }, "diffSummary": { "anyOf": [ {}, { "type": "null" } ] }, "createdAt": { "type": "string" } }, "required": [ "id", "reviewId", "itemId", "actorUserId", "action", "diffSummary", "createdAt" ], "additionalProperties": false }, "DatasetReviewEventList": { "type": "object", "properties": { "events": { "type": "array", "items": { "$ref": "#/components/schemas/DatasetReviewEvent" } } }, "required": [ "events" ], "additionalProperties": false }, "DatasetReviewItemList": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/DatasetReviewItem" } } }, "required": [ "items" ], "additionalProperties": false }, "DatasetReviewItemResponse": { "type": "object", "properties": { "item": { "$ref": "#/components/schemas/DatasetReviewItem" } }, "required": [ "item" ], "additionalProperties": false }, "DatasetImportResponse": { "anyOf": [ { "type": "object", "properties": { "mode": { "type": "string", "const": "append" }, "created": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "expectedSet": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "skipped": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "issues": { "type": "array", "items": {} } }, "required": [ "mode", "created", "expectedSet", "skipped", "issues" ], "additionalProperties": false }, { "type": "object", "properties": { "mode": { "type": "string", "const": "replace" }, "created": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "expectedSet": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "deleted": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "filesDeleted": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "mode", "created", "expectedSet", "deleted", "filesDeleted" ], "additionalProperties": false } ] }, "EvaluatorConfigResponse": { "oneOf": [ { "$ref": "#/components/schemas/WorkflowEvaluatorConfigResponse" }, { "$ref": "#/components/schemas/AgentEvaluatorConfigResponse" } ], "description": "Workflow evaluator YAML or typed agent evaluator metadata from its pinned requested source commit. Edit agent.ts and release to change agent evaluations.", "type": "object", "discriminator": { "propertyName": "automationType", "mapping": { "workflow": "#/components/schemas/WorkflowEvaluatorConfigResponse", "agent": "#/components/schemas/AgentEvaluatorConfigResponse" } } }, "WorkflowEvaluatorConfigResponse": { "type": "object", "properties": { "automationId": { "type": "string" }, "automationType": { "type": "string", "const": "workflow" }, "yaml": { "type": "string", "description": "Workflow evaluator configuration YAML." }, "config": { "$ref": "#/components/schemas/WorkflowEvaluatorConfig" } }, "required": [ "automationId", "automationType", "yaml", "config" ], "additionalProperties": false }, "WorkflowEvaluatorConfig": { "type": "object", "properties": { "evaluators": { "type": "array", "items": {} }, "passThreshold": { "type": "number" } }, "required": [ "evaluators", "passThreshold" ], "additionalProperties": false }, "AgentEvaluatorConfigResponse": { "type": "object", "properties": { "automationId": { "type": "string" }, "automationType": { "type": "string", "const": "agent" }, "source": { "type": "object", "properties": { "path": { "type": "string" }, "ref": { "type": "string" }, "commit": { "type": "string" } }, "required": [ "path", "ref", "commit" ], "additionalProperties": false }, "evaluation": { "anyOf": [ { "$ref": "#/components/schemas/AgentEvaluation" }, { "type": "null" } ] } }, "required": [ "automationId", "automationType", "source", "evaluation" ], "additionalProperties": false }, "AgentEvaluation": { "type": "object", "properties": { "evaluators": { "type": "object", "propertyNames": { "type": "string", "pattern": "^[a-zA-Z][a-zA-Z0-9_-]{0,63}$" }, "additionalProperties": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "custom" } }, "required": [ "kind" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "exact-diff" }, "options": { "type": "object", "properties": { "rules": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "object", "properties": { "ignore": { "type": "boolean", "const": true }, "order": { "type": "string", "enum": [ "ordered", "unordered" ] }, "items": { "type": "string", "enum": [ "at-least", "at-most", "exactly" ] }, "matchBy": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] }, "allowExtraFields": { "type": "boolean" }, "numericTolerance": { "type": "number", "minimum": 0 } }, "additionalProperties": false } }, "paths": { "type": "array", "items": { "type": "string" } }, "unorderedPaths": { "type": "array", "items": { "type": "string" } }, "numericTolerance": { "type": "number", "minimum": 0 }, "allowExtraFields": { "type": "boolean" } }, "additionalProperties": false } }, "required": [ "kind" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "llm-judge" }, "prompt": { "type": "string", "minLength": 10, "maxLength": 131072 }, "model": { "type": "string", "minLength": 1 } }, "required": [ "kind", "prompt" ], "additionalProperties": false } ], "type": "object" } }, "pass": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "callback" } }, "required": [ "kind" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "weighted" }, "weights": { "type": "object", "propertyNames": { "type": "string", "pattern": "^[a-zA-Z][a-zA-Z0-9_-]{0,63}$" }, "additionalProperties": { "type": "number", "minimum": 0 } }, "threshold": { "type": "number", "minimum": 0, "maximum": 1 } }, "required": [ "kind", "weights", "threshold" ], "additionalProperties": false } ], "type": "object" } }, "required": [ "evaluators", "pass" ], "additionalProperties": false }, "DatasetExampleList": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/DatasetExample" } }, "total": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "limit": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "offset": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "data", "total", "limit", "offset" ], "additionalProperties": false }, "DatasetExample": { "type": "object", "properties": { "id": { "type": "string", "description": "Stable public example id. Workflow examples use DB ids; agent examples use deterministic name-derived ids." }, "name": { "type": "string", "description": "Human-readable dataset example name." }, "automationId": { "type": "string", "description": "Automation that owns this example." }, "automationType": { "$ref": "#/components/schemas/AutomationType" }, "input": { "anyOf": [ { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, { "type": "null" } ], "description": "Input arguments used when this example is run. Null when listing with `include=metadata`." }, "expected": { "anyOf": [ {}, { "type": "null" } ], "description": "Expected JSON output for evaluator comparisons. Null when listing with `include=metadata`." }, "expectedFiles": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "Expected file name." }, "url": { "description": "Download URL for the expected file.", "type": "string" } }, "required": [ "name" ], "additionalProperties": false }, "description": "Expected files attached to this example." }, "metadata": { "anyOf": [ { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, { "type": "null" } ], "description": "Caller-managed metadata for sorting or filtering examples." }, "annotation": { "description": "Human note about the example.", "type": [ "string", "null" ] }, "rowOrder": { "description": "Optional display order within the dataset.", "type": [ "number", "null" ] }, "overrides": { "anyOf": [ { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, { "type": "null" } ], "description": "Step output overrides used when running this example." }, "latestRunId": { "description": "Most recent run id created from this example.", "type": [ "string", "null" ] }, "createdAt": { "type": "string" }, "updatedAt": { "type": [ "string", "null" ] } }, "required": [ "id", "name", "automationId", "automationType", "input", "expected", "expectedFiles", "metadata", "annotation", "rowOrder", "overrides", "latestRunId" ], "additionalProperties": false, "description": "One input/expected-output row in an automation dataset." }, "DatasetExampleExpectedFileList": { "type": "object", "properties": { "files": { "type": "array", "items": { "type": "string" }, "description": "Paths under the example expected folder." } }, "required": [ "files" ], "additionalProperties": false }, "DatasetExampleExpectedFileUploadResponse": { "type": "object", "properties": { "uploaded": { "type": "array", "items": { "type": "string" }, "description": "Stored expected file paths." } }, "required": [ "uploaded" ], "additionalProperties": false }, "DatasetExampleExpectedFileRenameResponse": { "type": "object", "properties": { "ok": { "type": "boolean", "const": true }, "filename": { "type": "string" }, "path": { "type": "string", "description": "Updated expected file path." } }, "required": [ "ok", "filename", "path" ], "additionalProperties": false }, "DatasetExampleInputFileList": { "type": "object", "properties": { "files": { "type": "array", "items": { "type": "string" }, "description": "Paths under the example input folder." } }, "required": [ "files" ], "additionalProperties": false }, "DatasetExampleInputFileUploadResponse": { "type": "object", "properties": { "uploaded": { "type": "array", "items": { "type": "string" }, "description": "Stored input file paths." } }, "required": [ "uploaded" ], "additionalProperties": false }, "DatasetExampleInputFileRenameResponse": { "type": "object", "properties": { "ok": { "type": "boolean", "const": true }, "filename": { "type": "string" }, "path": { "type": "string", "description": "Updated input file path." } }, "required": [ "ok", "filename", "path" ], "additionalProperties": false }, "ExampleRunResponse": { "type": "object", "properties": { "id": { "type": "string", "description": "Run id created for this example." }, "type": { "type": "string", "enum": [ "workflow", "agent" ], "description": "Implementation type behind the automation." }, "batchId": { "description": "Experiment batch id when the run is associated with a batch. The API also calls this an experiment id in experiment routes.", "type": [ "string", "null" ] }, "finished": { "type": "boolean", "const": false, "description": "Example runs are accepted asynchronously." } }, "required": [ "id", "type", "batchId", "finished" ], "additionalProperties": false }, "Experiment": { "type": "object", "properties": { "id": { "type": "string", "description": "Experiment batch id. Some CLI commands historically call this a batch id." }, "automationId": { "type": "string", "description": "Automation this experiment belongs to." }, "automationType": { "$ref": "#/components/schemas/AutomationType" }, "status": { "type": "string", "enum": [ "queued", "running", "completed" ], "description": "Experiment batch status." }, "runCount": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Total runs in the experiment." }, "completedCount": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Runs that have completed." }, "passedCount": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Runs whose evaluator scores passed." }, "failedCount": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Runs whose evaluator scores failed." }, "avgScore": { "description": "Average automated evaluator score.", "type": [ "number", "null" ] }, "createdAt": { "type": "string" }, "completedAt": { "type": [ "string", "null" ] }, "version": { "type": [ "string", "null" ] } }, "required": [ "id", "automationId", "automationType", "status", "runCount", "completedCount", "passedCount", "failedCount", "avgScore", "createdAt", "completedAt", "version" ], "additionalProperties": false, "description": "Experiment batch summary for an automation dataset run." }, "ExperimentCreateResponse": { "type": "object", "properties": { "id": { "type": "string", "description": "Experiment batch id." }, "runs": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Run id." }, "exampleId": { "description": "Dataset example id.", "type": [ "string", "null" ] } }, "required": [ "id", "exampleId" ], "additionalProperties": false }, "description": "Runs enqueued for this experiment." }, "total": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Number of runs enqueued." } }, "required": [ "id", "runs", "total" ], "additionalProperties": false, "description": "Accepted experiment batch and the runs it enqueued." }, "ExperimentDetail": { "type": "object", "properties": { "id": { "type": "string", "description": "Experiment batch id. Some CLI commands historically call this a batch id." }, "automationId": { "type": "string", "description": "Automation this experiment belongs to." }, "automationType": { "$ref": "#/components/schemas/AutomationType" }, "status": { "type": "string", "enum": [ "queued", "running", "completed" ], "description": "Experiment batch status." }, "runCount": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Total runs in the experiment." }, "completedCount": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Runs that have completed." }, "passedCount": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Runs whose evaluator scores passed." }, "failedCount": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Runs whose evaluator scores failed." }, "avgScore": { "description": "Average automated evaluator score.", "type": [ "number", "null" ] }, "createdAt": { "type": "string" }, "completedAt": { "type": [ "string", "null" ] }, "version": { "type": [ "string", "null" ] }, "runs": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Run id created for the experiment." }, "status": { "type": "string", "description": "Current run status." }, "exampleId": { "description": "Dataset example id for the run.", "type": [ "string", "null" ] }, "exampleName": { "description": "Dataset example name for the run.", "type": [ "string", "null" ] }, "evalScore": { "description": "Persisted weighted evaluator score.", "type": [ "number", "null" ] }, "evalPassed": { "description": "Persisted aggregate evaluator verdict.", "type": [ "boolean", "null" ] }, "createdAt": { "type": "string" }, "completedAt": { "type": [ "string", "null" ] } }, "required": [ "id", "status", "exampleId", "exampleName", "evalScore", "evalPassed", "createdAt", "completedAt" ], "additionalProperties": false }, "description": "Runs created for dataset examples in this experiment." }, "resultsByRun": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "array", "items": { "$ref": "#/components/schemas/EvalResult" } }, "description": "Evaluator results keyed by run id." } }, "required": [ "id", "automationId", "automationType", "status", "runCount", "completedCount", "passedCount", "failedCount", "avgScore", "createdAt", "completedAt", "version", "runs", "resultsByRun" ], "additionalProperties": false, "description": "Experiment batch detail." }, "EvalResult": { "type": "object", "properties": { "id": { "type": "string", "description": "Evaluator result id." }, "runId": { "type": "string", "description": "Run this score belongs to." }, "automationId": { "description": "Automation this score belongs to.", "type": [ "string", "null" ] }, "evaluatorName": { "type": "string", "description": "Evaluator name from configuration." }, "evaluatorType": { "type": "string", "description": "Evaluator implementation type." }, "score": { "description": "Automated evaluator score. Do not confuse this with a human review verdict.", "type": [ "number", "null" ] }, "passed": { "description": "Whether this evaluator passed.", "type": [ "boolean", "null" ] }, "label": { "description": "Optional evaluator label.", "type": [ "string", "null" ] }, "weight": { "description": "Weight used in aggregate scoring.", "type": [ "number", "null" ] }, "passThreshold": { "description": "Score threshold required for this evaluator to pass.", "type": [ "number", "null" ] }, "description": { "description": "Evaluator description.", "type": [ "string", "null" ] }, "details": { "anyOf": [ {}, { "type": "null" } ], "description": "Evaluator-specific details." }, "error": { "description": "Evaluator error, when scoring failed.", "type": [ "string", "null" ] }, "createdAt": { "type": "string" } }, "required": [ "id", "runId", "automationId", "evaluatorName", "evaluatorType", "score", "passed", "label", "weight", "passThreshold", "description", "details", "error", "createdAt" ], "additionalProperties": false, "description": "Automated evaluator result for one run." }, "RunReviewHealthResponse": { "type": "object", "properties": { "timeRange": { "type": "object", "properties": { "from": { "type": "string" }, "to": { "type": "string" } }, "required": [ "from", "to" ], "additionalProperties": false }, "granularity": { "type": "object", "properties": { "bucket": { "type": "string", "enum": [ "day", "week", "month" ] }, "rollingWindow": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "minRollingReviews": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "bucket", "rollingWindow", "minRollingReviews" ], "additionalProperties": false }, "summary": { "$ref": "#/components/schemas/RunReviewHealthSummary" }, "buckets": { "type": "array", "items": { "$ref": "#/components/schemas/RunReviewHealthBucket" } }, "rolling": { "type": "array", "items": { "$ref": "#/components/schemas/RunReviewHealthRollingPoint" } } }, "required": [ "timeRange", "granularity", "summary", "buckets", "rolling" ], "additionalProperties": false }, "RunReviewHealthSummary": { "type": "object", "properties": { "totalRuns": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "reviewedRuns": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Runs with a ranked verdict (`correct` or `incorrect`). Null verdict (nit) is excluded." }, "reviewCoverage": { "type": [ "number", "null" ] }, "correctReviews": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "incorrectReviews": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "nitReviews": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Runs with a review row and null verdict (nit). Excluded from review coverage and accuracy." }, "reviewedCorrectness": { "type": [ "number", "null" ] }, "confidence": { "$ref": "#/components/schemas/RunReviewHealthConfidence" } }, "required": [ "totalRuns", "reviewedRuns", "reviewCoverage", "correctReviews", "incorrectReviews", "nitReviews", "reviewedCorrectness", "confidence" ], "additionalProperties": false }, "RunReviewHealthConfidence": { "type": "object", "properties": { "lower": { "type": [ "number", "null" ] }, "upper": { "type": [ "number", "null" ] }, "method": { "type": "string", "const": "wilson" } }, "required": [ "lower", "upper", "method" ], "additionalProperties": false, "description": "Wilson score confidence interval for reviewed correctness. Null bounds mean there are no reviewed runs in the sample." }, "RunReviewHealthBucket": { "type": "object", "properties": { "start": { "type": "string" }, "end": { "type": "string" }, "totalRuns": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "reviewedRuns": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Runs with a ranked verdict (`correct` or `incorrect`). Null verdict (nit) is excluded." }, "reviewCoverage": { "type": [ "number", "null" ] }, "correctReviews": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "incorrectReviews": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "nitReviews": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Runs with a review row and null verdict (nit). Excluded from review coverage and accuracy." }, "reviewedCorrectness": { "type": [ "number", "null" ] } }, "required": [ "start", "end", "totalRuns", "reviewedRuns", "reviewCoverage", "correctReviews", "incorrectReviews", "nitReviews", "reviewedCorrectness" ], "additionalProperties": false }, "RunReviewHealthRollingPoint": { "type": "object", "properties": { "at": { "type": "string" }, "reviewedRuns": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Runs with a ranked verdict (`correct` or `incorrect`). Null verdict (nit) is excluded." }, "correctReviews": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "reviewedCorrectness": { "type": "number" }, "confidenceLower": { "type": "number" }, "confidenceUpper": { "type": "number" }, "totalRunsInWindow": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Total production runs in the rolling window ending at this point." }, "reviewCoverage": { "type": "number", "description": "Share of runs in the rolling window that were reviewed (0-1). Uses the same window size as rolling accuracy, applied to all runs." } }, "required": [ "at", "reviewedRuns", "correctReviews", "reviewedCorrectness", "confidenceLower", "confidenceUpper", "totalRunsInWindow", "reviewCoverage" ], "additionalProperties": false }, "AutomationTriggersResponse": { "type": "object", "properties": { "automationId": { "type": "string" }, "type": { "$ref": "#/components/schemas/AutomationType" }, "triggers": { "$ref": "#/components/schemas/AutomationTriggerState" } }, "required": [ "automationId", "type", "triggers" ], "additionalProperties": false }, "ListAutomationVersionsResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/AutomationVersion" } }, "total": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "limit": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "offset": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "data", "total", "limit", "offset" ], "additionalProperties": false }, "AutomationVersion": { "type": "object", "properties": { "id": { "type": "string" }, "automationId": { "type": "string" }, "version": { "type": [ "string", "null" ] }, "sourceRef": { "type": [ "string", "null" ] }, "isCurrent": { "type": "boolean" }, "createdAt": { "type": "string" } }, "required": [ "id", "automationId", "version" ], "additionalProperties": false }, "DatasetReviewInboxList": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/DatasetReviewInboxItem" } }, "total": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "limit": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "offset": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "data", "total", "limit", "offset" ], "additionalProperties": false }, "DatasetReviewInboxItem": { "type": "object", "properties": { "id": { "type": "string" }, "automationId": { "type": "string" }, "title": { "type": "string" }, "instructions": { "type": [ "string", "null" ] }, "focusFields": { "type": "array", "items": { "$ref": "#/components/schemas/DatasetReviewFocusFieldOutput" } }, "ignoredFields": { "type": "array", "items": { "type": "string" } }, "status": { "type": "string", "enum": [ "draft", "open", "paused", "closed", "cancelled" ] }, "exampleNames": { "type": "array", "items": { "type": "string" } }, "progress": { "$ref": "#/components/schemas/DatasetReviewProgress" }, "createdBy": { "type": [ "string", "null" ] }, "createdAt": { "type": "string" }, "closedAt": { "type": [ "string", "null" ] }, "automationName": { "type": "string", "description": "Display name for the automation that owns this review request." } }, "required": [ "id", "automationId", "title", "instructions", "focusFields", "ignoredFields", "status", "exampleNames", "progress", "createdBy", "createdAt", "closedAt", "automationName" ], "additionalProperties": false }, "ListEmailServersResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/EmailServer" } }, "total": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "limit": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "offset": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "data", "total", "limit", "offset" ], "additionalProperties": false }, "EmailServer": { "oneOf": [ { "$ref": "#/components/schemas/PublicResendEmailServer" }, { "$ref": "#/components/schemas/PublicSmtpEmailServer" } ], "type": "object", "discriminator": { "propertyName": "transport", "mapping": { "resend": "#/components/schemas/PublicResendEmailServer", "smtp": "#/components/schemas/PublicSmtpEmailServer" } } }, "PublicResendEmailServer": { "type": "object", "properties": { "id": { "type": "string", "maxLength": 128, "pattern": "^ems_[A-Za-z0-9_-]+$" }, "name": { "type": "string", "minLength": 1, "maxLength": 128 }, "enabled": { "type": "boolean" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" }, "transport": { "type": "string", "const": "resend" }, "fromEmail": { "type": "string", "format": "email", "pattern": "^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" }, "fromName": { "type": "string", "minLength": 1, "maxLength": 128 }, "apiKeyConfigured": { "type": "boolean", "const": true } }, "required": [ "id", "name", "enabled", "createdAt", "updatedAt", "transport", "fromEmail", "fromName", "apiKeyConfigured" ], "additionalProperties": false }, "PublicSmtpEmailServer": { "type": "object", "properties": { "id": { "type": "string", "maxLength": 128, "pattern": "^ems_[A-Za-z0-9_-]+$" }, "name": { "type": "string", "minLength": 1, "maxLength": 128 }, "enabled": { "type": "boolean" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" }, "transport": { "type": "string", "const": "smtp" }, "fromEmail": { "type": "string", "format": "email", "pattern": "^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" }, "fromName": { "type": "string", "minLength": 1, "maxLength": 128 }, "host": { "type": "string", "minLength": 1, "maxLength": 253 }, "port": { "type": "integer", "minimum": 1, "maximum": 65535 }, "security": { "type": "string", "enum": [ "starttls", "tls", "none" ] }, "username": { "type": [ "string", "null" ] }, "passwordConfigured": { "type": "boolean" }, "caPemConfigured": { "type": "boolean" } }, "required": [ "id", "name", "enabled", "createdAt", "updatedAt", "transport", "fromEmail", "fromName", "host", "port", "security", "username", "passwordConfigured", "caPemConfigured" ], "additionalProperties": false }, "DeleteEmailServerResponse": { "type": "object", "properties": { "deleted": { "type": "boolean", "const": true }, "id": { "type": "string", "maxLength": 128, "pattern": "^ems_[A-Za-z0-9_-]+$" } }, "required": [ "deleted", "id" ], "additionalProperties": false }, "TestEmailServerResponse": { "oneOf": [ { "type": "object", "properties": { "ok": { "type": "boolean", "const": true }, "transport": { "type": "string", "enum": [ "resend", "smtp" ] }, "messageId": { "type": "string", "minLength": 1 } }, "required": [ "ok", "transport", "messageId" ], "additionalProperties": false }, { "type": "object", "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string", "minLength": 1 } }, "required": [ "ok", "error" ], "additionalProperties": false } ], "type": "object" }, "ExperimentRef": { "type": "object", "properties": { "id": { "type": "string" }, "automationId": { "type": "string" } }, "required": [ "id", "automationId" ], "additionalProperties": false }, "File": { "type": "object", "properties": { "id": { "type": "string" }, "filename": { "type": "string" }, "contentType": { "type": [ "string", "null" ] }, "size": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "purpose": { "description": "Optional lifecycle marker. `run-input` marks a retry-safe temporary run pre-upload reaped after 24 hours. `builder-attachment` marks a Studio builder intermediary (any MIME) with the same TTL. Omitted/null means a durable reusable file.", "type": [ "string", "null" ] }, "createdAt": { "type": "string" } }, "required": [ "id", "filename", "contentType", "size", "createdAt" ], "additionalProperties": false }, "DeleteFileResponse": { "type": "object", "properties": { "deleted": { "type": "boolean" } }, "required": [ "deleted" ], "additionalProperties": false }, "PresignedFileUploadSession": { "type": "object", "properties": { "transport": { "type": "string", "const": "presigned-put" }, "uploadId": { "type": "string" }, "fileId": { "type": "string" }, "url": { "type": "string", "format": "uri" }, "headers": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" } }, "expiresAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, "maxFileSizeBytes": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "transport", "uploadId", "fileId", "url", "headers", "expiresAt", "maxFileSizeBytes" ], "additionalProperties": false }, "PresignedMultipartFileUploadSession": { "type": "object", "properties": { "transport": { "type": "string", "const": "presigned-multipart" }, "uploadId": { "type": "string" }, "fileId": { "type": "string" }, "partSizeBytes": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "partCount": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "partsUrl": { "type": "string" }, "completeUrl": { "type": "string" }, "expiresAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, "maxFileSizeBytes": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "transport", "uploadId", "fileId", "partSizeBytes", "partCount", "partsUrl", "completeUrl", "expiresAt", "maxFileSizeBytes" ], "additionalProperties": false }, "HttpChunkedFileUploadSession": { "type": "object", "properties": { "transport": { "type": "string", "const": "http-chunked" }, "uploadId": { "type": "string" }, "fileId": { "type": "string" }, "chunkSizeBytes": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "chunkCount": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "chunksUrl": { "type": "string" }, "completeUrl": { "type": "string" }, "expiresAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, "maxFileSizeBytes": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "transport", "uploadId", "fileId", "chunkSizeBytes", "chunkCount", "chunksUrl", "completeUrl", "expiresAt", "maxFileSizeBytes" ], "additionalProperties": false }, "MultipartFileUploadFallback": { "type": "object", "properties": { "transport": { "type": "string", "const": "multipart" }, "url": { "type": "string" }, "maxFileSizeBytes": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "transport", "url", "maxFileSizeBytes" ], "additionalProperties": false }, "FileUploadSession": { "type": "object", "properties": { "uploadId": { "type": "string" }, "fileId": { "type": "string" }, "transport": { "type": "string", "enum": [ "presigned-put", "presigned-multipart", "http-chunked" ] }, "status": { "type": "string" }, "expiresAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, "partSizeBytes": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "partCount": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "chunkSizeBytes": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "chunkCount": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "parts": { "type": "array", "items": { "type": "object", "properties": { "partNumber": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "size": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "etag": { "type": "string" } }, "required": [ "partNumber", "etag" ], "additionalProperties": false } } }, "required": [ "uploadId", "fileId", "transport", "status", "expiresAt" ], "additionalProperties": false }, "AbortFileUploadResponse": { "type": "object", "properties": { "aborted": { "type": "boolean", "const": true } }, "required": [ "aborted" ], "additionalProperties": false }, "AcceptHttpChunkedUploadChunkResponse": { "type": "object", "properties": { "accepted": { "type": "boolean", "const": true }, "chunkIndex": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "size": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "accepted", "chunkIndex", "size" ], "additionalProperties": false }, "ListFileUploadPartsResponse": { "type": "object", "properties": { "transport": { "type": "string", "const": "presigned-multipart" }, "uploadId": { "type": "string" }, "fileId": { "type": "string" }, "partSizeBytes": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "partCount": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "expiresAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, "parts": { "type": "array", "items": { "type": "object", "properties": { "partNumber": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "size": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "etag": { "type": "string" } }, "required": [ "partNumber", "etag" ], "additionalProperties": false } } }, "required": [ "transport", "uploadId", "fileId", "partSizeBytes", "partCount", "expiresAt", "parts" ], "additionalProperties": false }, "PresignFileUploadPartResponse": { "type": "object", "properties": { "transport": { "type": "string", "const": "presigned-multipart" }, "partNumber": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "url": { "type": "string", "format": "uri" }, "headers": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" } }, "expiresAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, "partSizeBytes": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "transport", "partNumber", "url", "headers", "expiresAt", "partSizeBytes" ], "additionalProperties": false }, "ListFoldersResponse": { "type": "array", "items": { "$ref": "#/components/schemas/Folder" } }, "Folder": { "type": "object", "properties": { "id": { "type": "string" }, "parentId": { "type": [ "string", "null" ] }, "type": { "$ref": "#/components/schemas/FolderType" }, "name": { "type": "string" }, "createdAt": { "type": "string" }, "childCount": { "description": "Direct subfolder count. Present on tree listings.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "workflowCount": { "description": "Workflows filed directly in this folder. Present on workflow-tree listings.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "previewItems": { "description": "Up to a handful of item names — subfolders first, then workflows — for a peek at folder contents. Present on workflow-tree listings.", "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "kind": { "type": "string", "enum": [ "folder", "workflow" ] } }, "required": [ "name", "kind" ], "additionalProperties": false } } }, "required": [ "id", "parentId", "type", "name", "createdAt" ], "additionalProperties": false }, "DeleteFolderResponse": { "type": "object", "properties": { "deleted": { "type": "boolean", "const": true }, "id": { "type": "string" } }, "required": [ "deleted", "id" ], "additionalProperties": false }, "HumanReviewListResponse": { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "executionId": { "type": "string", "minLength": 1 }, "automationId": { "type": "string", "minLength": 1 }, "automationName": { "type": "string", "minLength": 1 }, "sourceKind": { "type": "string", "enum": [ "workflow_step", "agent_tool" ] }, "sourceLabel": { "type": "string", "minLength": 1 }, "status": { "type": "string", "enum": [ "pending", "approved", "rejected", "cancelled" ] }, "requiredCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "confirmedCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "version": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "executionId", "automationId", "automationName", "sourceKind", "sourceLabel", "status", "requiredCount", "confirmedCount", "version", "createdAt", "updatedAt" ], "additionalProperties": false } }, "nextCursor": { "type": [ "string", "null" ] } }, "required": [ "tasks", "nextCursor" ], "additionalProperties": false }, "HumanReviewTaskResponse": { "type": "object", "properties": { "task": { "$ref": "#/components/schemas/HumanReviewTaskDetail" } }, "required": [ "task" ], "additionalProperties": false }, "HumanReviewTaskDetail": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "executionId": { "type": "string", "minLength": 1 }, "automationId": { "type": "string", "minLength": 1 }, "automationName": { "type": "string", "minLength": 1 }, "sourceKind": { "type": "string", "enum": [ "workflow_step", "agent_tool" ] }, "sourceLabel": { "type": "string", "minLength": 1 }, "status": { "type": "string", "enum": [ "pending", "approved", "rejected", "cancelled" ] }, "requiredCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "confirmedCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "version": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" }, "files": { "type": "array", "items": { "type": "object", "properties": { "fileId": { "type": "string", "minLength": 1 }, "filename": { "type": "string", "minLength": 1 }, "mimeType": { "type": "string" }, "size": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "fieldName": { "type": "string" }, "artifactPath": { "type": "string", "minLength": 1 }, "role": { "description": "run_input for authorized run input files; attachment for extra current-run files. Omitted on historical tasks and inferred at read time.", "type": "string", "enum": [ "run_input", "attachment" ] } }, "required": [ "fileId", "filename", "artifactPath" ], "additionalProperties": false } }, "input": { "anyOf": [ { "oneOf": [ { "type": "object", "properties": { "status": { "type": "string", "const": "available" }, "data": { "anyOf": [ { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, { "type": "array", "items": {} } ] } }, "required": [ "status", "data" ], "additionalProperties": false }, { "type": "object", "properties": { "status": { "type": "string", "const": "omitted_too_large" } }, "required": [ "status" ], "additionalProperties": false } ], "type": "object" }, { "type": "null" } ], "description": "Non-file trigger input derived at read time. Null when every field is a file or external source id. omitted_too_large when the projection exceeds the review data byte limit." }, "machineData": { "anyOf": [ { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, { "type": "array", "items": {} } ] }, "draftData": { "anyOf": [ { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, { "type": "array", "items": {} } ] }, "schema": { "anyOf": [ { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, { "type": "null" } ] }, "fieldMetadata": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "object", "properties": { "confidence": { "description": "Routing confidence: categorical low|medium|high from ai.extract grounding, or legacy 0–1 numeric when authored. Numeric grounding scores from extract land in display.score instead. Not calibrated by Eigenpal.", "anyOf": [ { "type": "number", "minimum": 0, "maximum": 1 }, { "type": "string", "enum": [ "low", "medium", "high" ] }, { "type": "string", "minLength": 1 } ] }, "label": { "description": "Short label shown in the review UI", "type": "string", "maxLength": 500 }, "description": { "description": "Longer reviewer guidance for this field", "type": "string", "maxLength": 5000 }, "review": { "description": "Legacy per-field override kept for existing tasks. Prefer selection.fields.review.", "default": "auto", "type": "string", "enum": [ "auto", "always", "never" ] }, "display": { "description": "Opaque display metadata preserved for the review UI. When metadataFrom is ai.extract, numeric grounding scores are copied here as display.score; routing confidence stays on confidence as categorical low|medium|high.", "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "additionalProperties": false } }, "requiredPaths": { "type": "array", "items": { "type": "string" } }, "selectionReasons": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string", "enum": [ "always", "explicit", "low_confidence", "missing_confidence", "all", "reviewer_edit", "threshold_met", "never", "excluded", "unmatched", "missing_confidence_skip" ] } }, "decisions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "path": { "type": "string" }, "originalValue": { "type": [ "string", "number", "boolean", "null" ] }, "currentValue": { "type": [ "string", "number", "boolean", "null" ] }, "required": { "type": "boolean" }, "reason": { "type": "string", "enum": [ "always", "explicit", "low_confidence", "missing_confidence", "all", "reviewer_edit", "threshold_met", "never", "excluded", "unmatched", "missing_confidence_skip" ] }, "confirmedBy": { "type": [ "string", "null" ] }, "confirmedAt": { "type": [ "string", "null" ] }, "version": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "required": [ "id", "path", "originalValue", "currentValue", "required", "reason", "confirmedBy", "confirmedAt", "version" ], "additionalProperties": false } }, "instructions": { "type": [ "string", "null" ] }, "completedBy": { "type": [ "string", "null" ] }, "completedAt": { "type": [ "string", "null" ] }, "outcomeReason": { "type": [ "string", "null" ] }, "lineage": { "description": "Optional lineage@1 document resolved from the extract sidecar. Omitted when missing or unreadable. Validate with @openparser/lineage.", "type": "object", "additionalProperties": true }, "parsedDocument": { "description": "Optional ParsedDocument resolved from the extract sidecar. Omitted when missing or unreadable. Validate with @openparser/schema.", "type": "object", "additionalProperties": true } }, "required": [ "id", "executionId", "automationId", "automationName", "sourceKind", "sourceLabel", "status", "requiredCount", "confirmedCount", "version", "createdAt", "updatedAt", "files", "input", "machineData", "draftData", "schema", "fieldMetadata", "requiredPaths", "selectionReasons", "decisions", "instructions", "completedBy", "completedAt", "outcomeReason" ], "additionalProperties": false }, "HumanReviewApproveResponse": { "type": "object", "properties": { "task": { "$ref": "#/components/schemas/HumanReviewTaskDetail" } }, "required": [ "task" ], "additionalProperties": false }, "HumanReviewFieldResponse": { "type": "object", "properties": { "task": { "$ref": "#/components/schemas/HumanReviewTaskDetail" } }, "required": [ "task" ], "additionalProperties": false }, "HumanReviewRejectResponse": { "type": "object", "properties": { "task": { "$ref": "#/components/schemas/HumanReviewTaskDetail" } }, "required": [ "task" ], "additionalProperties": false }, "ListModelsResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/PublicModel" } }, "total": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "data", "total" ], "additionalProperties": false }, "PublicModel": { "type": "object", "properties": { "id": { "type": "string" }, "kind": { "type": "string", "enum": [ "llm", "ocr" ] }, "provider": { "type": "string" }, "label": { "type": "string" }, "capabilities": { "minItems": 1, "type": "array", "items": { "type": "string", "enum": [ "text", "vision", "ocr" ] } }, "configured": { "type": "boolean" }, "available": { "type": "boolean" }, "health": { "type": "string", "enum": [ "configured", "unconfigured", "unknown" ], "description": "Configuration state only: `configured` means credentials are present in this environment; `unconfigured` means the catalog entry exists but credentials are missing. This list does not probe live providers, so it never reports healthy/degraded/outage. `unknown` is reserved and is not emitted by this endpoint." }, "defaultFor": { "type": "array", "items": { "type": "string", "enum": [ "text", "vision", "ocr" ] } }, "location": { "type": "string", "enum": [ "local", "hosted" ], "description": "`local` means on-prem / no cloud provider egress (`local: true` or tesseract). `hosted` means the provider is a cloud API. Endpoints are never returned." }, "limits": { "$ref": "#/components/schemas/PublicModelLimits" }, "cost": { "description": "Static Eigenpal credit rates when known without a live vendor catalog. Omitted for OpenParser OCR and for LLMs (token prices are not part of this catalog).", "$ref": "#/components/schemas/PublicModelCost" }, "aliases": { "type": "array", "items": { "type": "string" } }, "tags": { "type": "array", "items": { "type": "string" } }, "capabilityRank": { "description": "Optional picker rank. Higher is more capable. Omitted on catalog rows that do not set it. Does not change role defaults.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "id", "kind", "provider", "label", "capabilities", "configured", "available", "health", "defaultFor", "location", "aliases", "tags" ], "additionalProperties": false }, "PublicModelLimits": { "type": "object", "properties": { "requestTimeoutSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "maxConcurrentRequests": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "additionalProperties": false }, "PublicModelCost": { "type": "object", "properties": { "creditsPerPage": { "type": "number", "minimum": 0 }, "unit": { "type": "string", "const": "credits" } }, "required": [ "unit" ], "additionalProperties": false }, "ParsingReadiness": { "type": "object", "properties": { "stepType": { "type": "string", "const": "ai.parse-v2" }, "imageReading": { "type": "string", "enum": [ "configured", "unconfigured" ] }, "providers": { "type": "object", "properties": { "ocr": { "type": [ "string", "null" ] }, "vision": { "type": [ "string", "null" ] } }, "required": [ "ocr", "vision" ], "additionalProperties": false }, "nativeExtraction": { "type": "string", "const": "requires-worker-probe" }, "liveProbe": { "type": "boolean", "const": false }, "warnings": { "type": "array", "items": { "type": "string" } } }, "required": [ "stepType", "imageReading", "providers", "nativeExtraction", "liveProbe", "warnings" ], "additionalProperties": false }, "RunsListResponse": { "type": "object", "properties": { "runs": { "type": "array", "items": { "$ref": "#/components/schemas/RunListItem" } }, "nextCursor": { "type": [ "string", "null" ] } }, "required": [ "runs", "nextCursor" ], "additionalProperties": false }, "RunListItem": { "type": "object", "properties": { "tags": { "type": "array", "items": { "type": "string" } }, "id": { "type": "string" }, "type": { "type": "string", "enum": [ "workflow", "agent" ] }, "finished": { "type": "boolean", "description": "True when the run has reached a terminal status." }, "sampleRank": { "type": "number", "minimum": 0, "maximum": 1, "description": "Deterministic pseudo-random rank in [0, 1) for this run within the tenant. Use with a sample rate threshold to review a stable subset." }, "parentExecutionId": { "description": "Parent run id when this run was started by an invoke-workflow step. Omitted for top-level runs.", "type": "string" }, "timing": { "$ref": "#/components/schemas/RunTiming" }, "source": { "$ref": "#/components/schemas/RunSource" }, "trigger": { "$ref": "#/components/schemas/RunTrigger" }, "eval": { "description": "Present only on eval-scoped runs. Omitted otherwise.", "$ref": "#/components/schemas/RunEval" }, "error": { "description": "Structured processing failure, independent of the HTTP response status. Includes control.fail statusCode and step when known. Present on terminal runs; null when no error is recorded. Absent while in flight.", "anyOf": [ { "$ref": "#/components/schemas/RunError" }, { "type": "null" } ] }, "execution": { "$ref": "#/components/schemas/RunExecutionMeta" } }, "required": [ "tags", "id", "type", "finished", "sampleRank", "timing", "source", "trigger", "execution" ], "additionalProperties": false }, "RunTiming": { "type": "object", "properties": { "createdAt": { "type": "string" }, "startedAt": { "type": [ "string", "null" ] }, "completedAt": { "type": [ "string", "null" ] }, "durationMs": { "type": [ "number", "null" ] }, "cancelRequestedAt": { "description": "When the user requested cancel; status may still be `running` until the worker stops.", "type": [ "string", "null" ] } }, "required": [ "createdAt", "startedAt", "completedAt", "durationMs", "cancelRequestedAt" ], "additionalProperties": false }, "RunSource": { "type": "object", "properties": { "id": { "type": "string", "description": "Owning workflow id or agent id." }, "name": { "type": [ "string", "null" ] }, "version": { "description": "Workflow version label (workflow runs only).", "type": [ "string", "null" ] }, "versionId": { "description": "Captured workflow version id (workflow runs only).", "type": [ "string", "null" ] }, "slug": { "description": "Agent slug (agent runs only).", "type": [ "string", "null" ] }, "model": { "description": "LLM model used (agent runs only).", "type": [ "string", "null" ] }, "git": { "description": "Git provenance (agent runs only).", "anyOf": [ { "$ref": "#/components/schemas/RunSourceGit" }, { "type": "null" } ] }, "implementationAvailable": { "description": "Whether the live workflow/agent implementation still exists (`GET /api/v1/runs/:id` detail only).", "type": "boolean" }, "automationFound": { "description": "Whether the owning automation registry row still exists (`GET /api/v1/runs/:id` detail only).", "type": "boolean" }, "currentVersion": { "description": "Current released workflow version label when the source is live (`GET /api/v1/runs/:id` detail only).", "type": [ "string", "null" ] } }, "required": [ "id", "name", "version" ], "additionalProperties": false }, "RunSourceGit": { "type": "object", "properties": { "requestedRef": { "type": [ "string", "null" ] }, "resolvedRef": { "type": [ "string", "null" ] }, "resolvedTag": { "type": [ "string", "null" ] }, "commitSha": { "type": [ "string", "null" ] } }, "required": [ "requestedRef", "resolvedRef", "resolvedTag", "commitSha" ], "additionalProperties": false }, "RunTrigger": { "type": "object", "properties": { "type": { "type": [ "string", "null" ] }, "by": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "email": { "type": "string" } }, "required": [ "id", "name", "email" ], "additionalProperties": false }, { "type": "null" } ] }, "email": { "description": "Inbound email trigger details (agent runs, `expand=input` not required)." } }, "required": [ "type", "by" ], "additionalProperties": false }, "RunEval": { "type": "object", "properties": { "example": { "description": "Eval example label (agent example name or workflow example id).", "type": [ "string", "null" ] }, "exampleId": { "description": "Workflow eval example folder id (workflow runs only).", "type": [ "string", "null" ] }, "score": { "type": [ "number", "null" ] }, "passed": { "type": [ "boolean", "null" ] } }, "required": [ "example", "score", "passed" ], "additionalProperties": false }, "RunError": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable failure code. Do not branch on message text." }, "message": { "type": "string", "description": "Human-readable failure explanation." }, "statusCode": { "description": "HTTP-style business code configured by control.fail, not the API response status. Absent for untyped failures.", "type": "integer", "minimum": 400, "maximum": 599 }, "step": { "description": "Name of the control.fail step that rejected the run, when known.", "type": "string" }, "retryable": { "type": "boolean", "description": "Whether another attempt might succeed. Does not schedule a retry." } }, "required": [ "code", "message", "retryable" ], "additionalProperties": false }, "RunExecutionMeta": { "type": "object", "properties": { "status": { "description": "Status of this run. `retry.nextRun.status` is a later retry, not this run.", "$ref": "#/components/schemas/ExecutionStatus" }, "schemaValid": { "description": "Whether the completed output matched the workflow or agent output schema.", "type": [ "boolean", "null" ] }, "batchId": { "description": "Experiment batch id when the run is part of a batch.", "type": [ "string", "null" ] }, "retry": { "$ref": "#/components/schemas/RunExecutionRetry" }, "review": { "description": "Lightweight review state for run list rows.", "anyOf": [ { "$ref": "#/components/schemas/RunReviewSummary" }, { "type": "null" } ] }, "humanReview": { "description": "Pending in-flight human review when the run is waiting on a reviewer.", "anyOf": [ { "$ref": "#/components/schemas/RunHumanReviewSummary" }, { "type": "null" } ] } }, "required": [ "status", "schemaValid", "batchId", "retry" ], "additionalProperties": false }, "ExecutionStatus": { "type": "string", "enum": [ "created", "pending", "running", "waiting", "finalizing", "completed", "failed", "cancelled", "rejected" ] }, "RunExecutionRetry": { "type": "object", "properties": { "number": { "type": "number", "description": "Retry attempt index (0 = original run)." }, "previousRunId": { "description": "Run id of the prior attempt in the retry chain.", "type": [ "string", "null" ] }, "nextRun": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string" } }, "required": [ "id", "status" ], "additionalProperties": false }, { "type": "null" } ], "description": "Retry run spawned from this run, if any. Present on list and detail without `expand`. `status` here is the later retry, not this run." } }, "required": [ "number", "previousRunId", "nextRun" ], "additionalProperties": false }, "RunReviewSummary": { "type": "object", "properties": { "verdict": { "anyOf": [ { "type": "string", "enum": [ "correct", "incorrect" ] }, { "type": "null" } ] }, "status": { "type": "string", "enum": [ "open", "closed", "wont_fix" ] }, "hasNote": { "type": "boolean", "description": "True when review notes were left." }, "correctionCount": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Number of field/file corrections." } }, "required": [ "verdict", "status", "hasNote", "correctionCount" ], "additionalProperties": false }, "RunHumanReviewSummary": { "type": "object", "properties": { "taskId": { "type": "string" }, "sourceKind": { "type": "string", "enum": [ "workflow_step", "agent_tool" ] }, "sourceLabel": { "type": "string" }, "status": { "type": "string", "const": "pending" }, "requiredCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "confirmedCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "version": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "required": [ "taskId", "sourceKind", "sourceLabel", "status", "requiredCount", "confirmedCount", "version" ], "additionalProperties": false }, "Run": { "type": "object", "properties": { "tags": { "type": "array", "items": { "type": "string" } }, "id": { "type": "string" }, "type": { "type": "string", "enum": [ "workflow", "agent" ] }, "finished": { "type": "boolean", "description": "True when the run has reached a terminal status." }, "sampleRank": { "type": "number", "minimum": 0, "maximum": 1, "description": "Deterministic pseudo-random rank in [0, 1) for this run within the tenant. Use with a sample rate threshold to review a stable subset." }, "parentExecutionId": { "description": "Parent run id when this run was started by an invoke-workflow step. Omitted for top-level runs.", "type": "string" }, "timing": { "$ref": "#/components/schemas/RunTiming" }, "source": { "$ref": "#/components/schemas/RunSource" }, "trigger": { "$ref": "#/components/schemas/RunTrigger" }, "eval": { "description": "Present only on eval-scoped runs. Omitted otherwise.", "$ref": "#/components/schemas/RunEval" }, "output": { "description": "Completed runs only. Per-automation business result — not a generic schema. Absent until the run completes.", "anyOf": [ { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, { "type": "null" } ] }, "files": { "description": "Completed runs only. Download with GET /api/v1/runs/:id/artifacts/:path. Absent until the run completes.", "type": "array", "items": { "$ref": "#/components/schemas/RunArtifact" } }, "error": { "description": "Structured processing failure, independent of the HTTP response status. Includes control.fail statusCode and step when known. Present on terminal runs; null when no error is recorded. Absent while in flight.", "anyOf": [ { "$ref": "#/components/schemas/RunError" }, { "type": "null" } ] }, "input": { "description": "Present only with `expand=input`.", "$ref": "#/components/schemas/RunInput" }, "usage": { "description": "Present only with `expand=usage`. Null for old runs without telemetry.", "anyOf": [ { "$ref": "#/components/schemas/RunUsage" }, { "type": "null" } ] }, "execution": { "anyOf": [ { "$ref": "#/components/schemas/RunExecutionMeta" }, { "$ref": "#/components/schemas/RunExecution" } ], "description": "Slim execution metadata always present (`status`, `schemaValid`, `batchId`, `retry`). Pass `expand=execution` to replace with full RunExecution (WorkflowRunExecution or AgentRunExecution depending on run type)." }, "debug": { "description": "Present only with `expand=debug`.", "$ref": "#/components/schemas/RunDebug" } }, "required": [ "tags", "id", "type", "finished", "sampleRank", "timing", "source", "trigger", "execution" ], "additionalProperties": false, "example": { "id": "wfx_01HZXEXAMPLE", "type": "workflow", "finished": true, "sampleRank": 0.42, "timing": { "createdAt": "2026-01-15T10:00:00.000Z", "startedAt": "2026-01-15T10:00:01.000Z", "completedAt": "2026-01-15T10:00:08.000Z", "durationMs": 7000, "cancelRequestedAt": null }, "source": { "id": "wf_invoice", "name": "Invoice extraction", "version": "3", "versionId": "wfh_3" }, "trigger": { "type": "api", "by": null }, "output": { "vendor": "Acme", "total": 149.5 }, "files": [ { "name": "file_1-invoice.json", "role": "output", "path": "output/extract/file_1-invoice.json", "stepName": "extract" } ], "error": null, "execution": { "status": "completed", "schemaValid": true, "batchId": null, "retry": { "number": 0, "previousRunId": null, "nextRun": null } } } }, "RunArtifact": { "type": "object", "properties": { "name": { "type": "string" }, "role": { "type": "string", "description": "`input`, `output`, `debug`, `report`, or another stable artifact role." }, "path": { "type": "string", "description": "Canonical artifact path for GET /api/v1/runs/:id/artifacts/:path." }, "stepName": { "description": "Workflow step that produced the file, when known.", "type": "string" }, "contentType": { "type": [ "string", "null" ] }, "size": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] } }, "required": [ "name", "role", "path" ], "additionalProperties": false }, "RunInput": { "type": "object", "properties": { "args": { "description": "Input arguments the run was started with." }, "files": { "description": "Uploaded input files (agent runs only).", "type": "array", "items": { "$ref": "#/components/schemas/RunFile" } }, "metadata": { "description": "Caller-supplied run metadata, if any." } }, "required": [ "args" ], "additionalProperties": false }, "RunFile": { "type": "object", "properties": { "name": { "type": "string" } }, "required": [ "name" ], "additionalProperties": false }, "RunUsage": { "type": "object", "properties": { "tokens": { "type": "object", "properties": { "input": { "type": [ "number", "null" ] }, "output": { "type": [ "number", "null" ] }, "cacheRead": { "type": [ "number", "null" ] }, "cacheWrite": { "type": [ "number", "null" ] } }, "required": [ "input", "output", "cacheRead", "cacheWrite" ], "additionalProperties": false }, "creditsCharged": { "type": [ "number", "null" ] }, "durationMs": { "type": [ "number", "null" ] }, "llmCallCount": { "description": "LLM call count (workflow runs only).", "type": "number" }, "ocrPagesProcessed": { "description": "OCR pages processed (workflow runs only).", "type": "number" }, "agentTurns": { "description": "Agent conversation turns (agent runs only).", "type": [ "number", "null" ] } }, "required": [ "tokens", "creditsCharged", "durationMs" ], "additionalProperties": false }, "RunExecution": { "anyOf": [ { "$ref": "#/components/schemas/WorkflowRunExecution" }, { "$ref": "#/components/schemas/AgentRunExecution" } ] }, "WorkflowRunExecution": { "type": "object", "properties": { "status": { "description": "Status of this run. `retry.nextRun.status` is a later retry, not this run.", "$ref": "#/components/schemas/ExecutionStatus" }, "schemaValid": { "description": "Whether the completed output matched the workflow or agent output schema.", "type": [ "boolean", "null" ] }, "batchId": { "description": "Experiment batch id when the run is part of a batch.", "type": [ "string", "null" ] }, "retry": { "$ref": "#/components/schemas/RunExecutionRetry" }, "review": { "anyOf": [ { "$ref": "#/components/schemas/RunReview" }, { "type": "null" } ] }, "humanReview": { "description": "Pending in-flight human review when the run is waiting on a reviewer.", "anyOf": [ { "$ref": "#/components/schemas/RunHumanReviewSummary" }, { "type": "null" } ] }, "steps": { "type": "array", "items": {}, "description": "Slim per-step rows (`id`, name, type, status, timing, order, capped error excerpt). Full `input`/`output` live on `GET /api/v1/runs/{id}/steps/{stepExecutionId}`." }, "childExecutions": { "description": "Child invoke-workflow runs and their steps (`expand=execution`, workflow runs only). Omitted when there are no children.", "type": "array", "items": {} }, "definitionSnapshot": { "description": "Workflow definition snapshot captured when the run was created (`expand=execution`).", "anyOf": [ {}, { "type": "null" } ] }, "expected": { "description": "Ground-truth expected output and files.", "type": "object", "properties": { "output": {}, "files": { "type": "array", "items": { "$ref": "#/components/schemas/RunFile" } } }, "additionalProperties": false } }, "required": [ "status", "schemaValid", "batchId", "retry", "steps" ], "additionalProperties": false }, "RunReview": { "type": "object", "properties": { "id": { "type": "string" }, "verdict": { "anyOf": [ { "type": "string", "enum": [ "correct", "incorrect" ] }, { "type": "null" } ] }, "status": { "type": "string", "enum": [ "open", "closed", "wont_fix" ] }, "note": { "type": "string" }, "correctedOutput": { "anyOf": [ {}, { "type": "null" } ] }, "reviewedBy": { "description": "User id of the last reviewer. Read-only; set from the authenticated user or API key creator.", "type": [ "string", "null" ] }, "reviewedByEmail": { "description": "Email of the last reviewer. Read-only; set from the authenticated user or API key creator.", "type": [ "string", "null" ] }, "reviewedAt": { "type": "string" }, "closedBy": { "description": "User id recorded when the review was closed. Read-only; set when status becomes closed or wont_fix.", "type": [ "string", "null" ] }, "closedByEmail": { "description": "Email recorded when the review was closed. Read-only; set when status becomes closed or wont_fix.", "type": [ "string", "null" ] }, "closedAt": { "type": [ "string", "null" ] }, "closedNote": { "type": [ "string", "null" ] }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" }, "corrections": { "type": "array", "items": { "$ref": "#/components/schemas/RunReviewCorrection" } } }, "required": [ "id", "verdict", "status", "note", "reviewedBy", "reviewedByEmail", "reviewedAt", "closedBy", "closedByEmail", "closedAt", "closedNote", "createdAt", "updatedAt", "corrections" ], "additionalProperties": false }, "RunReviewCorrection": { "type": "object", "properties": { "id": { "type": "string" }, "kind": { "type": "string", "enum": [ "field", "file" ] }, "path": { "type": "string", "description": "JSON Pointer for field corrections, or canonical artifact path for file reviews." }, "label": { "type": [ "string", "null" ] }, "originalValue": { "anyOf": [ {}, { "type": "null" } ] }, "correctedValue": { "anyOf": [ {}, { "type": "null" } ] }, "note": { "type": "string" }, "correctedArtifactPath": { "type": [ "string", "null" ] }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "kind", "path", "label", "note", "createdAt", "updatedAt" ], "additionalProperties": false }, "AgentRunExecution": { "type": "object", "properties": { "status": { "description": "Status of this run. `retry.nextRun.status` is a later retry, not this run.", "$ref": "#/components/schemas/ExecutionStatus" }, "schemaValid": { "description": "Whether the completed output matched the workflow or agent output schema.", "type": [ "boolean", "null" ] }, "batchId": { "description": "Experiment batch id when the run is part of a batch.", "type": [ "string", "null" ] }, "retry": { "$ref": "#/components/schemas/RunExecutionRetry" }, "review": { "anyOf": [ { "$ref": "#/components/schemas/RunReview" }, { "type": "null" } ] }, "humanReview": { "description": "Pending in-flight human review when the run is waiting on a reviewer.", "anyOf": [ { "$ref": "#/components/schemas/RunHumanReviewSummary" }, { "type": "null" } ] }, "files": { "type": "object", "properties": { "output": { "type": "array", "items": { "$ref": "#/components/schemas/RunFile" }, "description": "Output artifacts the agent produced." } }, "required": [ "output" ], "additionalProperties": false }, "expected": { "description": "Ground-truth expected output and files.", "type": "object", "properties": { "output": {}, "files": { "type": "array", "items": { "$ref": "#/components/schemas/RunFile" } } }, "additionalProperties": false }, "comparison": { "description": "Expected-vs-actual comparison for eval runs (terminal runs only)." } }, "required": [ "status", "schemaValid", "batchId", "retry", "files" ], "additionalProperties": false }, "RunDebug": { "type": "object", "properties": { "observability": { "description": "Execution phase timeline and structured failure." }, "traceId": { "description": "Workflow trace id for span lookup (workflow runs only).", "type": [ "string", "null" ] } }, "required": [ "observability" ], "additionalProperties": false }, "RunAccepted": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "workflow", "agent" ] }, "finished": { "type": "boolean", "const": false }, "source": { "$ref": "#/components/schemas/RunSource" } }, "required": [ "id", "type", "finished" ], "additionalProperties": false, "example": { "id": "wfx_01HZXEXAMPLE", "type": "workflow", "finished": false, "source": { "id": "wf_invoice", "name": "Invoice extraction", "version": null } } }, "RunArtifactsResponse": { "type": "object", "properties": { "artifacts": { "type": "array", "items": { "$ref": "#/components/schemas/RunArtifact" } } }, "required": [ "artifacts" ], "additionalProperties": false }, "RunCancelResponse": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "workflow", "agent" ] }, "finished": { "type": "boolean", "description": "True when the run has reached a terminal status." }, "execution": { "type": "object", "properties": { "status": { "$ref": "#/components/schemas/ExecutionStatus" } }, "required": [ "status" ], "additionalProperties": false }, "cancellation": { "type": "object", "properties": { "state": { "type": "string", "enum": [ "cancelled", "requested", "already_terminal" ], "description": "`cancelled` — the run was terminated immediately (it had not started). `requested` — the run is in-flight; cancellation was requested and the status will become `cancelled` shortly. `already_terminal` — the run had already finished; nothing changed." }, "wasStatus": { "description": "Run status at the time the cancel request was received.", "$ref": "#/components/schemas/ExecutionStatus" } }, "required": [ "state", "wasStatus" ], "additionalProperties": false } }, "required": [ "id", "type", "finished", "execution", "cancellation" ], "additionalProperties": false }, "RunEventsResponse": { "type": "object", "properties": { "events": { "type": "array", "items": { "$ref": "#/components/schemas/RunEvent" } } }, "required": [ "events" ], "additionalProperties": false }, "RunEvent": { "type": "object", "properties": { "type": { "type": "string" }, "timestamp": { "type": "string" }, "status": { "type": [ "string", "null" ] }, "message": { "type": [ "string", "null" ] }, "metadata": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "type", "timestamp" ], "additionalProperties": false }, "PromoteRunResponse": { "type": "object", "properties": { "automationId": { "type": "string", "description": "Automation that owns the promoted example." }, "automationType": { "type": "string", "enum": [ "workflow", "agent" ], "description": "Implementation type behind the automation." }, "exampleId": { "type": "string", "description": "Dataset example identifier returned for follow-up API calls." }, "name": { "description": "Dataset example name.", "type": [ "string", "null" ] } }, "required": [ "automationId", "automationType", "exampleId", "name" ], "additionalProperties": false }, "RunReviewDetail": { "type": "object", "properties": { "review": { "anyOf": [ { "$ref": "#/components/schemas/RunReview" }, { "type": "null" } ], "description": "Review metadata and corrections. Corrected files are listed separately at GET /runs/{id}/reviews/expected." } }, "required": [ "review" ], "additionalProperties": false }, "RunReviewExpectedArtifacts": { "type": "object", "properties": { "files": { "type": "array", "items": { "$ref": "#/components/schemas/RunFile" }, "description": "Corrected artifact files attached to the run review. Corrected JSON output lives on the review object at GET /runs/{id}/reviews." } }, "required": [ "files" ], "additionalProperties": false }, "RunReviewExpectedFileMutationResponse": { "description": "Corrected file created or renamed by the request.", "$ref": "#/components/schemas/RunFile" }, "RunReviewExpectedFileUpdateResponse": { "description": "Corrected file after the rename.", "$ref": "#/components/schemas/RunFile" }, "RunScoresResponse": { "type": "object", "properties": { "scores": { "type": "array", "items": { "$ref": "#/components/schemas/EvalResult" }, "description": "Automated evaluator scores for the run. These are separate from human review verdicts." } }, "required": [ "scores" ], "additionalProperties": false, "description": "Automated evaluator results attached to a run." }, "RunStepsResponse": { "type": "object", "properties": { "steps": { "type": "array", "items": {} }, "total": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "steps", "total" ], "additionalProperties": false }, "RunStepDetailResponse": {}, "RunTraceResponse": { "type": "object", "properties": { "events": { "type": "array", "items": { "$ref": "#/components/schemas/RunTraceEvent" }, "description": "Chronological trace events. Workflow runs return observability phases or step executions; agent runs return parsed trace.jsonl events." } }, "required": [ "events" ], "additionalProperties": false }, "RunTraceEvent": { "type": "object", "properties": { "type": { "description": "Event type when present. Agent traces mirror trace.jsonl events; workflow traces use execution phase or step records.", "type": "string" }, "phase": { "description": "Workflow execution phase, when present.", "type": "string" }, "stepName": { "description": "Workflow step name, when present.", "type": "string" }, "status": { "description": "Event or execution status, when present.", "type": "string" }, "startedAt": { "description": "Event start timestamp.", "type": [ "string", "null" ] }, "completedAt": { "description": "Event completion timestamp.", "type": [ "string", "null" ] }, "message": { "description": "Human-readable event message.", "type": [ "string", "null" ] } }, "additionalProperties": {}, "description": "Trace event emitted by a workflow or agent run. Extra fields depend on the run type and event source." }, "RunUsageResponse": { "type": "object", "properties": { "usage": { "anyOf": [ { "$ref": "#/components/schemas/RunUsage" }, { "type": "null" } ] } }, "required": [ "usage" ], "additionalProperties": false }, "ListTemplatesResponse": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Template" } }, "total": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "items", "total" ], "additionalProperties": false }, "Template": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^tmpl_[A-Za-z0-9_-]{21}$", "description": "Stable logical template id (tmpl_…)." }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "filename": { "type": "string" }, "format": { "type": "string", "enum": [ "docx", "xlsx" ] }, "mimeType": { "type": "string" }, "size": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "sha256": { "anyOf": [ { "type": "string", "minLength": 64, "maxLength": 64 }, { "type": "null" } ] }, "tokens": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "path": { "type": "array", "items": { "type": "string" } }, "kind": { "type": "string", "enum": [ "variable", "loop" ] }, "type": { "type": "string", "enum": [ "string", "number", "date", "boolean", "array", "object" ] }, "required": { "type": "boolean" }, "description": { "type": "string" } }, "required": [ "name" ], "additionalProperties": false } }, "grammar": { "type": "object", "properties": { "syntax": { "type": "string" }, "tokenDiscovery": { "type": "boolean" }, "capabilities": { "type": "array", "items": { "type": "string" } } }, "required": [ "syntax", "tokenDiscovery", "capabilities" ], "additionalProperties": false }, "currentRevision": { "anyOf": [ { "$ref": "#/components/schemas/TemplateRevision" }, { "type": "null" } ] }, "createdAt": { "type": "string" }, "updatedAt": { "type": [ "string", "null" ] } }, "required": [ "id", "name", "filename", "format", "mimeType", "tokens", "grammar", "createdAt" ], "additionalProperties": false }, "TemplateRevision": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^tmpr_[A-Za-z0-9_-]{21}$", "description": "Immutable template revision id (tmpr_…)." }, "number": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "sha256": { "type": "string", "minLength": 64, "maxLength": 64 }, "createdAt": { "type": "string" } }, "required": [ "id", "number", "sha256", "createdAt" ], "additionalProperties": false }, "CreatedTemplate": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^tmpl_[A-Za-z0-9_-]{21}$", "description": "Stable logical template id (tmpl_…)." }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "filename": { "type": "string" }, "format": { "type": "string", "enum": [ "docx", "xlsx" ] }, "mimeType": { "type": "string" }, "size": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "sha256": { "anyOf": [ { "type": "string", "minLength": 64, "maxLength": 64 }, { "type": "null" } ] }, "tokens": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "path": { "type": "array", "items": { "type": "string" } }, "kind": { "type": "string", "enum": [ "variable", "loop" ] }, "type": { "type": "string", "enum": [ "string", "number", "date", "boolean", "array", "object" ] }, "required": { "type": "boolean" }, "description": { "type": "string" } }, "required": [ "name" ], "additionalProperties": false } }, "grammar": { "type": "object", "properties": { "syntax": { "type": "string" }, "tokenDiscovery": { "type": "boolean" }, "capabilities": { "type": "array", "items": { "type": "string" } } }, "required": [ "syntax", "tokenDiscovery", "capabilities" ], "additionalProperties": false }, "currentRevision": { "anyOf": [ { "$ref": "#/components/schemas/TemplateRevision" }, { "type": "null" } ] }, "createdAt": { "type": "string" }, "updatedAt": { "type": [ "string", "null" ] }, "cleanupProof": { "description": "One-time proof to finalize or hard-clean this unpublished staged template. Returned only on staged create, never on GET or list.", "type": "string" } }, "required": [ "id", "name", "filename", "format", "mimeType", "tokens", "grammar", "createdAt" ], "additionalProperties": false }, "DeleteTemplateResponse": { "type": "object", "properties": { "deleted": { "type": "boolean" } }, "required": [ "deleted" ], "additionalProperties": false }, "TemplateStagingResponse": { "type": "object", "properties": { "cleaned": { "type": "boolean" }, "finalized": { "type": "boolean" } }, "additionalProperties": false }, "DatasetReviewFocusFieldOutput": { "type": "object", "properties": { "path": { "type": "string", "minLength": 1, "description": "Dotted expected-output path the reviewer should inspect, e.g. vendor.iban." }, "reason": { "description": "Optional reason this field needs attention.", "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] } }, "required": [ "path" ], "additionalProperties": false } }, "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "API key issued from Settings → API Keys. Pass as `Authorization: Bearer `." } } } }