{
  "openapi": "3.1.0",
  "info": {
    "title": "Octomatica Agent-as-a-Service API",
    "version": "1.0.0",
    "description": "Public integration surface for creating isolated Octomatica agent spaces, configuring manifests and tools, running asynchronous turns, retrieving artifacts, and metering usage per end user. This curated specification contains only the public /v1 integration API.",
    "contact": {
      "name": "Octomatica integrations",
      "email": "labs@octomatica.ru",
      "url": "https://octomatica.ru/developers.md"
    }
  },
  "externalDocs": {
    "description": "Interactive Octomatica API documentation",
    "url": "https://dash.octomatica.ru/v1/docs"
  },
  "servers": [
    {
      "url": "https://dash.octomatica.ru/v1",
      "description": "Production API"
    }
  ],
  "security": [
    {
      "OctomaticaApiKey": []
    }
  ],
  "tags": [
    {
      "name": "Spaces",
      "description": "Create and configure isolated agent spaces."
    },
    {
      "name": "Turns",
      "description": "Submit asynchronous work and retrieve its result or artifacts."
    },
    {
      "name": "Usage",
      "description": "Read account, key, space, and end-user usage."
    },
    {
      "name": "Catalog",
      "description": "Read supported models and built-in tool capabilities."
    }
  ],
  "paths": {
    "/spaces": {
      "post": {
        "operationId": "createSpace",
        "summary": "Create an isolated agent space",
        "description": "Creates a space controlled by the calling key. Store the returned space_id in the integrating application's own record.",
        "tags": ["Spaces"],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateSpaceRequest"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Space created",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CreateSpaceResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/QuotaExceeded"
          }
        }
      },
      "get": {
        "operationId": "listSpaces",
        "summary": "List API spaces visible to the key",
        "description": "Keys restricted to their own spaces only receive spaces created by that key.",
        "tags": ["Spaces"],
        "responses": {
          "200": {
            "description": "Visible spaces",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/Space"
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        }
      }
    },
    "/spaces/{slug}/manifest": {
      "parameters": [
        {
          "$ref": "#/components/parameters/SpaceSlug"
        }
      ],
      "put": {
        "operationId": "setSpaceManifest",
        "summary": "Set durable instructions for a space",
        "description": "Stores the instructions that define how the agent should behave and use the integrating application. Do not include credentials.",
        "tags": ["Spaces"],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["manifest"],
                "properties": {
                  "manifest": {
                    "type": "string",
                    "minLength": 1
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Manifest stored",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Manifest"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      },
      "get": {
        "operationId": "getSpaceManifest",
        "summary": "Read durable instructions for a space",
        "description": "Returns the stored manifest for a space visible to the calling key.",
        "tags": ["Spaces"],
        "responses": {
          "200": {
            "description": "Stored manifest",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Manifest"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/spaces/{slug}/secret": {
      "parameters": [
        {
          "$ref": "#/components/parameters/SpaceSlug"
        }
      ],
      "put": {
        "operationId": "setSpaceSecret",
        "summary": "Store a write-only application credential",
        "description": "Encrypts and stores a credential for server-side tool calls. The value is never returned and should never be placed in a prompt.",
        "tags": ["Spaces"],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["secret"],
                "properties": {
                  "secret": {
                    "type": "string",
                    "minLength": 1,
                    "writeOnly": true
                  }
                }
              }
            }
          }
        },
        "responses": {
          "204": {
            "description": "Secret stored"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/spaces/{slug}/tools": {
      "parameters": [
        {
          "$ref": "#/components/parameters/SpaceSlug"
        }
      ],
      "put": {
        "operationId": "setSpaceTools",
        "summary": "Set the least-privilege tool configuration",
        "description": "Configures built-in capability keys and optional external MCP servers for the space.",
        "tags": ["Spaces"],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ToolConfiguration"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Tool configuration stored",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ToolConfiguration"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      },
      "get": {
        "operationId": "getSpaceTools",
        "summary": "Read the tool configuration",
        "description": "Returns the configured built-in allowlist and external MCP server registrations.",
        "tags": ["Spaces"],
        "responses": {
          "200": {
            "description": "Current tool configuration",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ToolConfiguration"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/spaces/{slug}/turns": {
      "get": {
        "operationId": "listSpaceTurns",
        "summary": "List recent turns for a space",
        "description": "Returns recent turns, with a default limit of 50 and a maximum of 200.",
        "tags": ["Turns"],
        "parameters": [
          {
            "$ref": "#/components/parameters/SpaceSlug"
          },
          {
            "name": "limit",
            "in": "query",
            "description": "Maximum number of recent turns to return.",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 200,
              "default": 50
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Recent turns",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/Turn"
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/tools/catalog": {
      "get": {
        "operationId": "getToolCatalog",
        "summary": "List built-in capability keys",
        "description": "Returns capability keys that can be placed in a space's allowlist, including web, image, media, transcription, gdrive, seo, code, files, and research.",
        "tags": ["Catalog"],
        "responses": {
          "200": {
            "description": "Built-in capability catalog",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "additionalProperties": true
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        }
      }
    },
    "/models": {
      "get": {
        "operationId": "listModels",
        "summary": "List supported engines and models",
        "description": "Returns valid engine and model combinations for space creation.",
        "tags": ["Catalog"],
        "responses": {
          "200": {
            "description": "Supported engine and model combinations",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "additionalProperties": true
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        }
      }
    },
    "/turns": {
      "post": {
        "operationId": "createTurn",
        "summary": "Submit asynchronous work to a space",
        "description": "Queues a prompt for execution. Always send a unique Idempotency-Key for a logical message so network retries cannot create duplicate paid turns.",
        "tags": ["Turns"],
        "parameters": [
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateTurnRequest"
              }
            }
          }
        },
        "responses": {
          "202": {
            "description": "Turn accepted and queued",
            "headers": {
              "Location": {
                "description": "Polling URL for this turn.",
                "schema": {
                  "type": "string",
                  "format": "uri-reference"
                }
              },
              "X-Trace-Id": {
                "$ref": "#/components/headers/TraceId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CreateTurnResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "409": {
            "description": "The idempotency key was reused with a different request body.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/QuotaExceeded"
          }
        }
      }
    },
    "/turns/{turn_id}": {
      "get": {
        "operationId": "getTurn",
        "summary": "Poll a turn",
        "description": "Poll with capped backoff until the state is done, failed, or cancelled. The result field is a human-readable summary, not a typed machine-output contract.",
        "tags": ["Turns"],
        "parameters": [
          {
            "$ref": "#/components/parameters/TurnId"
          }
        ],
        "responses": {
          "200": {
            "description": "Current turn state and result when terminal",
            "headers": {
              "X-Trace-Id": {
                "$ref": "#/components/headers/TraceId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Turn"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/turns/{turn_id}/cancel": {
      "post": {
        "operationId": "cancelTurn",
        "summary": "Cancel a non-terminal turn",
        "description": "Requests cooperative cancellation. A terminal turn returns ALREADY_TERMINAL.",
        "tags": ["Turns"],
        "parameters": [
          {
            "$ref": "#/components/parameters/TurnId"
          }
        ],
        "responses": {
          "200": {
            "description": "Cancellation requested",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Turn"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "description": "Turn is already terminal",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          }
        }
      }
    },
    "/turns/{turn_id}/files": {
      "get": {
        "operationId": "listTurnFiles",
        "summary": "List files produced by a turn",
        "description": "Returns artifact metadata and download URLs for a completed turn.",
        "tags": ["Turns"],
        "parameters": [
          {
            "$ref": "#/components/parameters/TurnId"
          }
        ],
        "responses": {
          "200": {
            "description": "Produced files",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/ProducedFile"
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/files/{file_id}": {
      "get": {
        "operationId": "downloadFile",
        "summary": "Download a produced file",
        "description": "Streams the file bytes with a Content-Disposition filename.",
        "tags": ["Turns"],
        "parameters": [
          {
            "$ref": "#/components/parameters/FileId"
          }
        ],
        "responses": {
          "200": {
            "description": "File bytes",
            "content": {
              "application/octet-stream": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/usage": {
      "get": {
        "operationId": "getUsage",
        "summary": "Read usage and spend",
        "description": "Returns spend and turn counts. Use group_by=end_user for per-user metering and scope=key to restrict results to the calling key.",
        "tags": ["Usage"],
        "parameters": [
          {
            "name": "group_by",
            "in": "query",
            "description": "Optional aggregation dimension.",
            "schema": {
              "type": "string",
              "enum": ["end_user", "space", "model"]
            }
          },
          {
            "name": "scope",
            "in": "query",
            "description": "Use key for only the calling key's turns or account for the full owner account.",
            "schema": {
              "type": "string",
              "enum": ["key", "account"],
              "default": "account"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Usage summary",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        }
      }
    },
    "/spaces/{slug}/end-users": {
      "get": {
        "operationId": "listSpaceEndUsers",
        "summary": "List end-user spend and caps for a space",
        "description": "Returns cumulative spend and configured limits for end_user_ref values used in this space.",
        "tags": ["Usage"],
        "parameters": [
          {
            "$ref": "#/components/parameters/SpaceSlug"
          }
        ],
        "responses": {
          "200": {
            "description": "End-user usage records",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "additionalProperties": true
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/spaces/{slug}/end-users/{ref}": {
      "patch": {
        "operationId": "setEndUserLimit",
        "summary": "Set an end user's cumulative spend cap",
        "description": "Sets total_limit_usd for an opaque end_user_ref. Use null to remove the cap.",
        "tags": ["Usage"],
        "parameters": [
          {
            "$ref": "#/components/parameters/SpaceSlug"
          },
          {
            "name": "ref",
            "in": "path",
            "required": true,
            "description": "Opaque end-user reference supplied by the integrating application.",
            "schema": {
              "type": "string",
              "minLength": 1
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["total_limit_usd"],
                "properties": {
                  "total_limit_usd": {
                    "type": ["number", "null"],
                    "minimum": 0
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Limit updated",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "OctomaticaApiKey": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "octo_live_...",
        "description": "Server-side API key created in Dashboard > Integrations > API Keys. Keys can be limited to only spaces they create, one specific space, or all account spaces. Prefer the first option and configure a daily USD cap."
      }
    },
    "parameters": {
      "SpaceSlug": {
        "name": "slug",
        "in": "path",
        "required": true,
        "description": "Space identifier returned as space_id when the space is created.",
        "schema": {
          "type": "string",
          "minLength": 1
        }
      },
      "TurnId": {
        "name": "turn_id",
        "in": "path",
        "required": true,
        "description": "Turn identifier returned when asynchronous work is accepted.",
        "schema": {
          "type": "string",
          "minLength": 1
        }
      },
      "FileId": {
        "name": "file_id",
        "in": "path",
        "required": true,
        "description": "Produced file identifier.",
        "schema": {
          "type": "string",
          "minLength": 1
        }
      },
      "IdempotencyKey": {
        "name": "Idempotency-Key",
        "in": "header",
        "required": true,
        "description": "Unique value for one logical turn. Reuse only for an exact retry with the same request body.",
        "schema": {
          "type": "string",
          "minLength": 8,
          "maxLength": 255
        }
      }
    },
    "headers": {
      "TraceId": {
        "description": "Trace identifier to preserve when reporting an API error.",
        "schema": {
          "type": "string"
        }
      }
    },
    "responses": {
      "BadRequest": {
        "description": "Invalid request",
        "headers": {
          "X-Trace-Id": {
            "$ref": "#/components/headers/TraceId"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorEnvelope"
            }
          }
        }
      },
      "Unauthorized": {
        "description": "Missing, malformed, unknown, or revoked API key",
        "headers": {
          "X-Trace-Id": {
            "$ref": "#/components/headers/TraceId"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorEnvelope"
            }
          }
        }
      },
      "Forbidden": {
        "description": "The API key is not authorized for this space",
        "headers": {
          "X-Trace-Id": {
            "$ref": "#/components/headers/TraceId"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorEnvelope"
            }
          }
        }
      },
      "NotFound": {
        "description": "Resource not found or not visible to the calling key",
        "headers": {
          "X-Trace-Id": {
            "$ref": "#/components/headers/TraceId"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorEnvelope"
            }
          }
        }
      },
      "QuotaExceeded": {
        "description": "Daily key cap or cumulative end-user cap reached",
        "headers": {
          "X-Trace-Id": {
            "$ref": "#/components/headers/TraceId"
          },
          "Retry-After": {
            "description": "Seconds until retry when a retry window applies.",
            "schema": {
              "type": "integer",
              "minimum": 0
            }
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorEnvelope"
            }
          }
        }
      }
    },
    "schemas": {
      "CreateSpaceRequest": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "engine": {
            "type": "string",
            "description": "Execution engine. Defaults to claude-code.",
            "examples": ["claude-code"]
          },
          "model": {
            "type": "string",
            "description": "Model identifier valid for the selected engine.",
            "examples": ["opus"]
          },
          "title": {
            "type": "string",
            "description": "Human-readable title for the space."
          }
        }
      },
      "CreateSpaceResponse": {
        "type": "object",
        "required": ["space_id", "origin"],
        "properties": {
          "space_id": {
            "type": "string",
            "description": "Stable space slug to store in the integrating application."
          },
          "origin": {
            "type": "string",
            "const": "api"
          }
        }
      },
      "Space": {
        "type": "object",
        "required": ["space_id"],
        "properties": {
          "space_id": {
            "type": "string"
          },
          "title": {
            "type": ["string", "null"]
          },
          "engine": {
            "type": ["string", "null"]
          },
          "model": {
            "type": ["string", "null"]
          },
          "origin": {
            "type": "string"
          }
        },
        "additionalProperties": true
      },
      "Manifest": {
        "type": "object",
        "required": ["manifest"],
        "properties": {
          "manifest": {
            "type": "string"
          }
        }
      },
      "ToolConfiguration": {
        "type": "object",
        "properties": {
          "allow": {
            "type": ["array", "null"],
            "description": "Least-privilege allowlist of built-in capability keys. Null means unrestricted.",
            "items": {
              "type": "string",
              "enum": ["web", "image", "media", "transcription", "gdrive", "seo", "code", "files", "research"]
            }
          },
          "mcp_servers": {
            "type": "array",
            "description": "External MCP servers the space may call.",
            "items": {
              "$ref": "#/components/schemas/McpServer"
            },
            "default": []
          }
        },
        "additionalProperties": false
      },
      "McpServer": {
        "type": "object",
        "required": ["name", "url"],
        "properties": {
          "name": {
            "type": "string",
            "minLength": 1
          },
          "url": {
            "type": "string",
            "format": "uri"
          },
          "headers": {
            "type": "object",
            "description": "Optional server-side headers. Treat their values as secrets.",
            "additionalProperties": {
              "type": "string"
            },
            "writeOnly": true
          }
        },
        "additionalProperties": false
      },
      "CreateTurnRequest": {
        "type": "object",
        "required": ["space", "text"],
        "properties": {
          "space": {
            "type": "string",
            "description": "Space slug returned by createSpace."
          },
          "text": {
            "type": "string",
            "minLength": 1,
            "description": "User task or prompt. Do not include credentials."
          },
          "end_user_ref": {
            "type": "string",
            "description": "Opaque user identifier from the integrating application, used for usage attribution and caps."
          },
          "metadata": {
            "type": "object",
            "description": "Opaque metadata echoed in the turn response. Maximum encoded size is 8 KB.",
            "additionalProperties": true
          }
        },
        "additionalProperties": false
      },
      "CreateTurnResponse": {
        "type": "object",
        "required": ["turn_id", "state", "trace_id"],
        "properties": {
          "turn_id": {
            "type": "string"
          },
          "state": {
            "type": "string",
            "const": "queued"
          },
          "trace_id": {
            "type": "string"
          }
        }
      },
      "Turn": {
        "type": "object",
        "required": ["turn_id", "state"],
        "properties": {
          "turn_id": {
            "type": "string"
          },
          "state": {
            "type": "string",
            "enum": ["queued", "running", "done", "failed", "cancelled"]
          },
          "current_activity": {
            "type": ["string", "null"]
          },
          "result": {
            "type": ["string", "null"],
            "description": "Human-readable result summary. Do not parse as a typed output contract."
          },
          "result_truncated": {
            "type": "boolean"
          },
          "error": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/ErrorDetail"
              },
              {
                "type": "null"
              }
            ]
          },
          "usage": {
            "$ref": "#/components/schemas/TokenUsage"
          },
          "billed_cost_usd": {
            "type": ["number", "null"],
            "minimum": 0
          },
          "metadata": {
            "type": ["object", "null"],
            "additionalProperties": true
          },
          "created_at": {
            "type": ["string", "null"],
            "format": "date-time"
          },
          "started_at": {
            "type": ["string", "null"],
            "format": "date-time"
          },
          "completed_at": {
            "type": ["string", "null"],
            "format": "date-time"
          }
        },
        "additionalProperties": true
      },
      "TokenUsage": {
        "type": ["object", "null"],
        "properties": {
          "input_tokens": {
            "type": "integer",
            "minimum": 0
          },
          "output_tokens": {
            "type": "integer",
            "minimum": 0
          },
          "total_tokens": {
            "type": "integer",
            "minimum": 0
          },
          "provider": {
            "type": "string"
          },
          "model": {
            "type": "string"
          }
        },
        "additionalProperties": true
      },
      "ProducedFile": {
        "type": "object",
        "required": ["file_id", "name", "content_type", "size", "url"],
        "properties": {
          "file_id": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "content_type": {
            "type": "string"
          },
          "size": {
            "type": "integer",
            "minimum": 0
          },
          "url": {
            "type": "string",
            "format": "uri-reference"
          }
        }
      },
      "ErrorEnvelope": {
        "type": "object",
        "required": ["error"],
        "properties": {
          "error": {
            "$ref": "#/components/schemas/ErrorDetail"
          }
        }
      },
      "ErrorDetail": {
        "type": "object",
        "required": ["code", "message"],
        "properties": {
          "code": {
            "type": "string",
            "examples": ["INVALID_REQUEST"]
          },
          "message": {
            "type": "string"
          },
          "details": {
            "type": ["object", "null"],
            "additionalProperties": true
          },
          "trace_id": {
            "type": ["string", "null"]
          }
        },
        "additionalProperties": true
      }
    }
  }
}