{
  "openapi": "3.1.0",
  "info": {
    "title": "AgentHost Customer API",
    "version": "0.1.0",
    "description": "Customer-facing API for AgentHost computers, browser sessions, API-only mail inboxes, artifacts, realtime state, and usage records. Admin, internal mail-relay, and guest VM endpoints are intentionally excluded from this contract."
  },
  "servers": [
    {
      "url": "https://agent-host.net",
      "description": "Production origin"
    }
  ],
  "tags": [
    { "name": "registration" },
    { "name": "api_keys" },
    { "name": "computers" },
    { "name": "browser" },
    { "name": "mail" },
    { "name": "artifacts" },
    { "name": "realtime" },
    { "name": "usage" },
    { "name": "health" }
  ],
  "paths": {
    "/health": {
      "get": {
        "tags": ["health"],
        "summary": "Health check",
        "responses": {
          "200": {
            "description": "Service health",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": { "type": "string" }
                }
              }
            }
          }
        }
      }
    },
    "/v1/registration": {
      "post": {
        "tags": ["registration"],
        "summary": "Create a new organization, first agent mailbox, and first API key",
        "security": [{ "registrationToken": [] }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/SelfServiceRegistrationRequest" }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Registration result with one-time API key token",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/SelfServiceRegistrationResponse" }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "409": { "$ref": "#/components/responses/Conflict" },
          "503": { "$ref": "#/components/responses/ServiceUnavailable" }
        }
      }
    },
    "/v1/agents/register": {
      "post": {
        "tags": ["registration"],
        "summary": "Register an additional agent mailbox for the authenticated organization",
        "security": [{ "bearerAuth": [] }],
        "x-agentbase-scopes": ["mail:inboxes:create", "mail:inboxes:read"],
        "requestBody": {
          "required": true,
          "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RegisterAgentRequest" } } }
        },
        "responses": {
          "200": { "$ref": "#/components/responses/AgentRegistration" },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "402": { "$ref": "#/components/responses/PaymentRequired" },
          "403": { "$ref": "#/components/responses/Forbidden" },
          "409": { "$ref": "#/components/responses/Conflict" },
          "429": { "$ref": "#/components/responses/TooManyRequests" }
        }
      }
    },
    "/v1/api-keys": {
      "get": {
        "tags": ["api_keys"],
        "summary": "List same-organization API key metadata",
        "security": [{ "bearerAuth": [] }],
        "x-agentbase-scopes": ["api_keys:read"],
        "responses": {
          "200": { "description": "API key metadata", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/APIKeySummary" } } } } },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "403": { "$ref": "#/components/responses/Forbidden" }
        }
      },
      "post": {
        "tags": ["api_keys"],
        "summary": "Create a child API key whose scopes are a subset of the current key",
        "security": [{ "bearerAuth": [] }],
        "x-agentbase-scopes": ["api_keys:create"],
        "requestBody": { "$ref": "#/components/requestBodies/CreateScopedAPIKey" },
        "responses": {
          "200": { "$ref": "#/components/responses/APIKeyCreated" },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "403": { "$ref": "#/components/responses/Forbidden" }
        }
      }
    },
    "/v1/api-keys/{apiKeyID}": {
      "delete": {
        "tags": ["api_keys"],
        "summary": "Revoke a same-organization API key",
        "security": [{ "bearerAuth": [] }],
        "x-agentbase-scopes": ["api_keys:create"],
        "parameters": [{ "$ref": "#/components/parameters/APIKeyID" }],
        "responses": {
          "204": { "description": "API key revoked" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "403": { "$ref": "#/components/responses/Forbidden" },
          "404": { "$ref": "#/components/responses/NotFound" }
        }
      }
    },
    "/v1/computers": {
      "get": {
        "tags": ["computers"],
        "summary": "List organization computers",
        "security": [{ "bearerAuth": [] }],
        "x-agentbase-scopes": ["computers:read"],
        "responses": {
          "200": { "description": "Computers", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ComputerRecord" } } } } },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "403": { "$ref": "#/components/responses/Forbidden" }
        }
      },
      "post": {
        "tags": ["computers"],
        "summary": "Create an execution VM",
        "security": [{ "bearerAuth": [] }],
        "x-agentbase-scopes": ["computers:read", "computers:create"],
        "requestBody": { "$ref": "#/components/requestBodies/CreateComputer" },
        "responses": {
          "200": { "$ref": "#/components/responses/Computer" },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "402": { "$ref": "#/components/responses/PaymentRequired" },
          "403": { "$ref": "#/components/responses/Forbidden" },
          "429": { "$ref": "#/components/responses/TooManyRequests" }
        }
      }
    },
    "/v1/computers/{computerID}": {
      "delete": {
        "tags": ["computers"],
        "summary": "Destroy an execution VM",
        "security": [{ "bearerAuth": [] }],
        "x-agentbase-scopes": ["computers:read", "computers:destroy"],
        "parameters": [{ "$ref": "#/components/parameters/ComputerID" }],
        "responses": {
          "204": { "description": "Computer destroyed" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "403": { "$ref": "#/components/responses/Forbidden" },
          "404": { "$ref": "#/components/responses/NotFound" }
        }
      }
    },
    "/v1/computers/{computerID}/commands": {
      "get": {
        "tags": ["computers"],
        "summary": "List commands queued for a computer",
        "security": [{ "bearerAuth": [] }],
        "x-agentbase-scopes": ["computers:read"],
        "parameters": [{ "$ref": "#/components/parameters/ComputerID" }],
        "responses": {
          "200": { "description": "Commands", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ComputerCommandRecord" } } } } },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "403": { "$ref": "#/components/responses/Forbidden" }
        }
      },
      "post": {
        "tags": ["computers"],
        "summary": "Queue a command for a computer",
        "security": [{ "bearerAuth": [] }],
        "x-agentbase-scopes": ["computers:read", "computers:control"],
        "parameters": [{ "$ref": "#/components/parameters/ComputerID" }],
        "requestBody": { "$ref": "#/components/requestBodies/CreateComputerCommand" },
        "responses": {
          "200": { "$ref": "#/components/responses/ComputerCommand" },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "403": { "$ref": "#/components/responses/Forbidden" },
          "404": { "$ref": "#/components/responses/NotFound" }
        }
      }
    },
    "/v1/computers/{computerID}/commands/{commandID}": {
      "get": {
        "tags": ["computers"],
        "summary": "Get one computer command",
        "security": [{ "bearerAuth": [] }],
        "x-agentbase-scopes": ["computers:read"],
        "parameters": [{ "$ref": "#/components/parameters/ComputerID" }, { "$ref": "#/components/parameters/CommandID" }],
        "responses": {
          "200": { "$ref": "#/components/responses/ComputerCommand" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "403": { "$ref": "#/components/responses/Forbidden" },
          "404": { "$ref": "#/components/responses/NotFound" }
        }
      }
    },
    "/v1/browser/sessions": {
      "get": {
        "tags": ["browser"],
        "summary": "List browser sessions",
        "security": [{ "bearerAuth": [] }],
        "x-agentbase-scopes": ["browser:read"],
        "responses": {
          "200": { "description": "Browser sessions", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/BrowserSessionRecord" } } } } },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "403": { "$ref": "#/components/responses/Forbidden" }
        }
      },
      "post": {
        "tags": ["browser"],
        "summary": "Create a browser session on an existing or newly provisioned VM",
        "security": [{ "bearerAuth": [] }],
        "x-agentbase-scopes": ["browser:read", "browser:create"],
        "requestBody": { "$ref": "#/components/requestBodies/CreateBrowserSession" },
        "responses": {
          "200": { "$ref": "#/components/responses/BrowserSession" },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "402": { "$ref": "#/components/responses/PaymentRequired" },
          "403": { "$ref": "#/components/responses/Forbidden" },
          "404": { "$ref": "#/components/responses/NotFound" },
          "429": { "$ref": "#/components/responses/TooManyRequests" }
        }
      }
    },
    "/v1/browser/sessions/{sessionID}": {
      "delete": {
        "tags": ["browser"],
        "summary": "Close a browser session",
        "security": [{ "bearerAuth": [] }],
        "x-agentbase-scopes": ["browser:read", "browser:destroy"],
        "parameters": [{ "$ref": "#/components/parameters/SessionID" }],
        "responses": {
          "200": { "$ref": "#/components/responses/BrowserSession" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "403": { "$ref": "#/components/responses/Forbidden" },
          "404": { "$ref": "#/components/responses/NotFound" }
        }
      }
    },
    "/v1/browser/sessions/{sessionID}/takeover": {
      "post": { "$ref": "#/components/pathItems/BrowserTakeover" }
    },
    "/v1/browser/sessions/{sessionID}/release": {
      "post": { "$ref": "#/components/pathItems/BrowserRelease" }
    },
    "/v1/browser/sessions/{sessionID}/open": {
      "post": {
        "tags": ["browser"],
        "summary": "Navigate a browser session to an http(s) URL",
        "security": [{ "bearerAuth": [] }],
        "x-agentbase-scopes": ["browser:read", "browser:control"],
        "parameters": [{ "$ref": "#/components/parameters/SessionID" }],
        "requestBody": { "$ref": "#/components/requestBodies/BrowserNavigate" },
        "responses": {
          "200": { "$ref": "#/components/responses/ComputerCommand" },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "403": { "$ref": "#/components/responses/Forbidden" },
          "404": { "$ref": "#/components/responses/NotFound" },
          "409": { "$ref": "#/components/responses/Conflict" }
        }
      }
    },
    "/v1/browser/sessions/{sessionID}/screenshot": {
      "post": {
        "tags": ["browser"],
        "summary": "Queue a browser screenshot command",
        "security": [{ "bearerAuth": [] }],
        "x-agentbase-scopes": ["browser:read", "browser:control"],
        "parameters": [{ "$ref": "#/components/parameters/SessionID" }],
        "requestBody": { "$ref": "#/components/requestBodies/BrowserScreenshot" },
        "responses": {
          "200": { "$ref": "#/components/responses/ComputerCommand" },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "403": { "$ref": "#/components/responses/Forbidden" },
          "404": { "$ref": "#/components/responses/NotFound" },
          "409": { "$ref": "#/components/responses/Conflict" }
        }
      }
    },
    "/v1/browser/sessions/{sessionID}/eval": {
      "post": {
        "tags": ["browser"],
        "summary": "Queue JavaScript evaluation in the active browser page",
        "security": [{ "bearerAuth": [] }],
        "x-agentbase-scopes": ["browser:read", "browser:control"],
        "parameters": [{ "$ref": "#/components/parameters/SessionID" }],
        "requestBody": { "$ref": "#/components/requestBodies/BrowserEval" },
        "responses": {
          "200": { "$ref": "#/components/responses/ComputerCommand" },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "403": { "$ref": "#/components/responses/Forbidden" },
          "404": { "$ref": "#/components/responses/NotFound" },
          "409": { "$ref": "#/components/responses/Conflict" }
        }
      }
    },
    "/v1/browser/sessions/{sessionID}/cookies": {
      "post": {
        "tags": ["browser"],
        "summary": "Queue a browser cookie export command for the active browser profile",
        "description": "Returns a computer command. Poll the command result to read cookies as sensitive session secrets. AgentHost does not expose a cookie-setting endpoint.",
        "security": [{ "bearerAuth": [] }],
        "x-agentbase-scopes": ["browser:read", "browser:cookies:read"],
        "parameters": [{ "$ref": "#/components/parameters/SessionID" }],
        "responses": {
          "200": { "$ref": "#/components/responses/ComputerCommand" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "403": { "$ref": "#/components/responses/Forbidden" },
          "404": { "$ref": "#/components/responses/NotFound" },
          "409": { "$ref": "#/components/responses/Conflict" }
        }
      }
    },
    "/v1/browser/sessions/{sessionID}/webrtc/offer": {
      "post": {
        "tags": ["browser"],
        "summary": "Submit a WebRTC offer through the browser signaling relay",
        "security": [{ "bearerAuth": [] }],
        "x-agentbase-scopes": ["browser:read", "browser:control"],
        "parameters": [{ "$ref": "#/components/parameters/SessionID" }],
        "requestBody": { "$ref": "#/components/requestBodies/WebRTCOffer" },
        "responses": {
          "200": { "description": "Offer accepted for relay", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebRTCSignalResponse" } } } },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "403": { "$ref": "#/components/responses/Forbidden" },
          "404": { "$ref": "#/components/responses/NotFound" },
          "409": { "$ref": "#/components/responses/Conflict" }
        }
      }
    },
    "/v1/browser/sessions/{sessionID}/live-token": {
      "post": {
        "tags": ["browser"],
        "summary": "Mint a short-lived token for the web browser live view",
        "security": [{ "bearerAuth": [] }],
        "x-agentbase-scopes": ["browser:read", "browser:control"],
        "parameters": [{ "$ref": "#/components/parameters/SessionID" }],
        "responses": {
          "200": { "description": "Short-lived live browser token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BrowserLiveTokenResponse" } } } },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "403": { "$ref": "#/components/responses/Forbidden" },
          "404": { "$ref": "#/components/responses/NotFound" },
          "409": { "$ref": "#/components/responses/Conflict" }
        }
      }
    },
    "/v1/browser/sessions/{sessionID}/live-config": {
      "get": {
        "tags": ["browser"],
        "summary": "Read live-view WebRTC configuration using a short-lived browser live token",
        "security": [{ "browserLiveToken": [] }],
        "parameters": [{ "$ref": "#/components/parameters/SessionID" }],
        "responses": {
          "200": { "description": "Live browser configuration", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BrowserLiveConfigurationResponse" } } } },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "404": { "$ref": "#/components/responses/NotFound" },
          "409": { "$ref": "#/components/responses/Conflict" }
        }
      }
    },
    "/v1/browser/sessions/{sessionID}/live/takeover": {
      "post": { "$ref": "#/components/pathItems/BrowserLiveTakeover" }
    },
    "/v1/browser/sessions/{sessionID}/live/release": {
      "post": { "$ref": "#/components/pathItems/BrowserLiveRelease" }
    },
    "/v1/mail/inboxes": {
      "get": {
        "tags": ["mail"],
        "summary": "List API-only mail inboxes",
        "security": [{ "bearerAuth": [] }],
        "x-agentbase-scopes": ["mail:inboxes:read"],
        "responses": {
          "200": { "description": "Inboxes", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/InboxRecord" } } } } },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "403": { "$ref": "#/components/responses/Forbidden" }
        }
      },
      "post": {
        "tags": ["mail"],
        "summary": "Create an API-only inbox on an active AgentHost-managed mail domain",
        "security": [{ "bearerAuth": [] }],
        "x-agentbase-scopes": ["mail:inboxes:read", "mail:inboxes:create"],
        "requestBody": { "$ref": "#/components/requestBodies/CreateInbox" },
        "responses": {
          "200": { "$ref": "#/components/responses/Inbox" },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "402": { "$ref": "#/components/responses/PaymentRequired" },
          "403": { "$ref": "#/components/responses/Forbidden" },
          "409": { "$ref": "#/components/responses/Conflict" },
          "429": { "$ref": "#/components/responses/TooManyRequests" }
        }
      }
    },
    "/v1/api-keys/{apiKeyID}/skill.md": {
      "get": {
        "tags": ["api_keys"],
        "summary": "Download a ready-made Agent Host skill template for a visible API key",
        "security": [{ "bearerAuth": [] }],
        "x-agentbase-scopes": ["api_keys:read"],
        "parameters": [{ "$ref": "#/components/parameters/APIKeyID" }],
        "responses": {
          "200": { "description": "Skill markdown", "content": { "text/markdown": { "schema": { "type": "string" } } } },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "403": { "$ref": "#/components/responses/Forbidden" },
          "404": { "$ref": "#/components/responses/NotFound" }
        }
      }
    },
    "/v1/mail/inboxes/{inboxID}/messages": {
      "get": {
        "tags": ["mail"],
        "summary": "List retained messages for an inbox",
        "security": [{ "bearerAuth": [] }],
        "x-agentbase-scopes": ["mail:inboxes:read", "mail:messages:read"],
        "parameters": [{ "$ref": "#/components/parameters/InboxID" }],
        "responses": {
          "200": { "description": "Mail messages", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/MailMessageRecord" } } } } },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "403": { "$ref": "#/components/responses/Forbidden" },
          "404": { "$ref": "#/components/responses/NotFound" }
        }
      }
    },
    "/v1/mail/inboxes/{inboxID}/messages/{messageID}": {
      "delete": {
        "tags": ["mail"],
        "summary": "Soft-delete a retained message from an inbox",
        "security": [{ "bearerAuth": [] }],
        "x-agentbase-scopes": ["mail:inboxes:read", "mail:messages:delete"],
        "parameters": [
          { "$ref": "#/components/parameters/InboxID" },
          { "$ref": "#/components/parameters/MessageID" }
        ],
        "responses": {
          "204": { "description": "Message deleted" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "403": { "$ref": "#/components/responses/Forbidden" },
          "404": { "$ref": "#/components/responses/NotFound" }
        }
      }
    },
    "/v1/mail/inboxes/{inboxID}/send": {
      "post": {
        "tags": ["mail"],
        "summary": "Queue outbound mail for Postfix relay",
        "security": [{ "bearerAuth": [] }],
        "x-agentbase-scopes": ["mail:inboxes:read", "mail:messages:send"],
        "parameters": [{ "$ref": "#/components/parameters/InboxID" }],
        "requestBody": { "$ref": "#/components/requestBodies/SendMail" },
        "responses": {
          "200": { "description": "Queued outbound message", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MailMessageRecord" } } } },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "402": { "$ref": "#/components/responses/PaymentRequired" },
          "403": { "$ref": "#/components/responses/Forbidden" },
          "404": { "$ref": "#/components/responses/NotFound" },
          "429": { "$ref": "#/components/responses/TooManyRequests" }
        }
      }
    },
    "/v1/artifacts": {
      "get": {
        "tags": ["artifacts"],
        "summary": "List uploaded artifacts",
        "security": [{ "bearerAuth": [] }],
        "x-agentbase-scopes": ["artifacts:read"],
        "responses": {
          "200": { "description": "Artifacts", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ArtifactRecord" } } } } },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "403": { "$ref": "#/components/responses/Forbidden" }
        }
      }
    },
    "/v1/artifacts/{artifactID}": {
      "get": {
        "tags": ["artifacts"],
        "summary": "Get artifact metadata",
        "security": [{ "bearerAuth": [] }],
        "x-agentbase-scopes": ["artifacts:read"],
        "parameters": [{ "$ref": "#/components/parameters/ArtifactID" }],
        "responses": {
          "200": { "description": "Artifact metadata", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ArtifactRecord" } } } },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "403": { "$ref": "#/components/responses/Forbidden" },
          "404": { "$ref": "#/components/responses/NotFound" }
        }
      }
    },
    "/v1/artifacts/{artifactID}/download": {
      "get": {
        "tags": ["artifacts"],
        "summary": "Download artifact bytes",
        "security": [{ "bearerAuth": [] }],
        "x-agentbase-scopes": ["artifacts:read"],
        "parameters": [{ "$ref": "#/components/parameters/ArtifactID" }],
        "responses": {
          "200": { "description": "Artifact bytes", "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "403": { "$ref": "#/components/responses/Forbidden" },
          "404": { "$ref": "#/components/responses/NotFound" }
        }
      }
    },
    "/v1/realtime/snapshot": {
      "get": {
        "tags": ["realtime"],
        "summary": "Read current computers, browser sessions, and inboxes",
        "security": [{ "bearerAuth": [] }],
        "x-agentbase-scopes": ["computers:read", "browser:read", "mail:inboxes:read"],
        "responses": {
          "200": { "description": "Current resource snapshot", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentResourceSnapshot" } } } },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "403": { "$ref": "#/components/responses/Forbidden" }
        }
      }
    },
    "/v1/realtime/events": {
      "get": {
        "tags": ["realtime"],
        "summary": "Open an SSE stream for same-organization resource updates",
        "security": [{ "bearerAuth": [] }],
        "x-agentbase-scopes": ["computers:read", "browser:read", "mail:inboxes:read"],
        "responses": {
          "200": { "description": "Server-sent resource snapshots", "content": { "text/event-stream": { "schema": { "type": "string" } } } },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "403": { "$ref": "#/components/responses/Forbidden" }
        }
      }
    },
    "/v1/usage/events": {
      "get": {
        "tags": ["usage"],
        "summary": "List recent usage events",
        "security": [{ "bearerAuth": [] }],
        "x-agentbase-scopes": ["billing:usage:read"],
        "parameters": [{ "$ref": "#/components/parameters/Limit" }],
        "responses": {
          "200": { "description": "Usage events", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/UsageEventRecord" } } } } },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "403": { "$ref": "#/components/responses/Forbidden" }
        }
      }
    },
    "/v1/usage/summary": {
      "get": {
        "tags": ["usage"],
        "summary": "Read current usage summary",
        "security": [{ "bearerAuth": [] }],
        "x-agentbase-scopes": ["billing:usage:read"],
        "responses": {
          "200": { "description": "Usage summary", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsageSummary" } } } },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "403": { "$ref": "#/components/responses/Forbidden" }
        }
      }
    },
    "/v1/usage/statement": {
      "get": {
        "tags": ["usage"],
        "summary": "Preview a usage statement for a period",
        "security": [{ "bearerAuth": [] }],
        "x-agentbase-scopes": ["billing:usage:read"],
        "parameters": [{ "$ref": "#/components/parameters/StartDate" }, { "$ref": "#/components/parameters/EndDate" }],
        "responses": {
          "200": { "description": "Usage statement preview", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsageStatement" } } } },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "403": { "$ref": "#/components/responses/Forbidden" }
        }
      }
    },
    "/v1/usage/statement/finalize": {
      "post": {
        "tags": ["usage"],
        "summary": "Finalize an immutable internal usage statement",
        "security": [{ "bearerAuth": [] }],
        "x-agentbase-scopes": ["billing:usage:read"],
        "requestBody": { "$ref": "#/components/requestBodies/FinalizeUsageStatement" },
        "responses": {
          "200": { "description": "Finalized usage statement", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FinalizedUsageStatementRecord" } } } },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "403": { "$ref": "#/components/responses/Forbidden" }
        }
      }
    },
    "/v1/usage/billing-account": {
      "get": {
        "tags": ["usage"],
        "summary": "Read the billing account for the authenticated organization",
        "security": [{ "bearerAuth": [] }],
        "x-agentbase-scopes": ["billing:usage:read"],
        "responses": {
          "200": { "description": "Billing account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BillingAccountRecord" } } } },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "403": { "$ref": "#/components/responses/Forbidden" },
          "404": { "$ref": "#/components/responses/NotFound" }
        }
      }
    },
    "/v1/usage/statements": {
      "get": {
        "tags": ["usage"],
        "summary": "List finalized usage statements",
        "security": [{ "bearerAuth": [] }],
        "x-agentbase-scopes": ["billing:usage:read"],
        "responses": {
          "200": { "description": "Finalized usage statements", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/FinalizedUsageStatementRecord" } } } } },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "403": { "$ref": "#/components/responses/Forbidden" }
        }
      }
    },
    "/v1/usage/statements/{statementID}": {
      "get": {
        "tags": ["usage"],
        "summary": "Get one finalized usage statement",
        "security": [{ "bearerAuth": [] }],
        "x-agentbase-scopes": ["billing:usage:read"],
        "parameters": [{ "$ref": "#/components/parameters/StatementID" }],
        "responses": {
          "200": { "description": "Finalized usage statement", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FinalizedUsageStatementRecord" } } } },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "403": { "$ref": "#/components/responses/Forbidden" },
          "404": { "$ref": "#/components/responses/NotFound" }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": { "type": "http", "scheme": "bearer" },
      "registrationToken": { "type": "apiKey", "in": "header", "name": "X-AgentBase-Registration-Token" },
      "browserLiveToken": { "type": "apiKey", "in": "header", "name": "X-AgentBase-Browser-Live-Token" }
    },
    "parameters": {
      "APIKeyID": { "name": "apiKeyID", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/UUID" } },
      "ComputerID": { "name": "computerID", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/UUID" } },
      "CommandID": { "name": "commandID", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/UUID" } },
      "SessionID": { "name": "sessionID", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/UUID" } },
      "InboxID": { "name": "inboxID", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/UUID" } },
      "MessageID": { "name": "messageID", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/UUID" } },
      "ArtifactID": { "name": "artifactID", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/UUID" } },
      "StatementID": { "name": "statementID", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/UUID" } },
      "Limit": { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 500, "default": 100 } },
      "StartDate": { "name": "start", "in": "query", "required": true, "schema": { "type": "string", "format": "date-time" } },
      "EndDate": { "name": "end", "in": "query", "required": true, "schema": { "type": "string", "format": "date-time" } }
    },
    "requestBodies": {
      "CreateScopedAPIKey": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateScopedAPIKeyRequest" } } } },
      "CreateComputer": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateComputerRequest" } } } },
      "CreateComputerCommand": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateComputerCommandRequest" } } } },
      "CreateBrowserSession": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateBrowserSessionRequest" } } } },
      "BrowserNavigate": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BrowserNavigateRequest" } } } },
      "BrowserScreenshot": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BrowserScreenshotRequest" } } } },
      "BrowserEval": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BrowserEvalRequest" } } } },
      "WebRTCOffer": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebRTCOfferRequest" } } } },
      "CreateInbox": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateInboxRequest" } } } },
      "SendMail": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendMailRequest" } } } },
      "FinalizeUsageStatement": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FinalizeUsageStatementRequest" } } } }
    },
    "responses": {
      "APIKeyCreated": { "description": "Created API key; token is returned once", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/APIKeyCreatedResponse" } } } },
      "AgentRegistration": { "description": "Registered agent mailbox", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentRegistrationRecord" } } } },
      "Computer": { "description": "Computer", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ComputerRecord" } } } },
      "ComputerCommand": { "description": "Computer command", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ComputerCommandRecord" } } } },
      "BrowserSession": { "description": "Browser session", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BrowserSessionRecord" } } } },
      "Inbox": { "description": "Mail inbox", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InboxRecord" } } } },
      "BadRequest": { "description": "Bad request" },
      "Unauthorized": { "description": "Missing or invalid credential" },
      "PaymentRequired": { "description": "Billing account is past due or suspended for new billable activity" },
      "Forbidden": { "description": "Credential is valid but lacks required scope or access" },
      "NotFound": { "description": "Resource not found or belongs to another organization" },
      "Conflict": { "description": "Resource state does not allow the requested operation" },
      "TooManyRequests": { "description": "Organization or resource quota was exceeded" },
      "ServiceUnavailable": { "description": "Required service configuration is not available" }
    },
    "pathItems": {
      "BrowserTakeover": {
        "tags": ["browser"],
        "summary": "Mark a browser session as human-controlled",
        "security": [{ "bearerAuth": [] }],
        "x-agentbase-scopes": ["browser:read", "browser:control"],
        "parameters": [{ "$ref": "#/components/parameters/SessionID" }],
        "responses": { "200": { "$ref": "#/components/responses/BrowserSession" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" } }
      },
      "BrowserRelease": {
        "tags": ["browser"],
        "summary": "Return a browser session to agent control",
        "security": [{ "bearerAuth": [] }],
        "x-agentbase-scopes": ["browser:read", "browser:control"],
        "parameters": [{ "$ref": "#/components/parameters/SessionID" }],
        "responses": { "200": { "$ref": "#/components/responses/BrowserSession" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" } }
      },
      "BrowserLiveTakeover": {
        "tags": ["browser"],
        "summary": "Mark a browser session as human-controlled from the live page",
        "security": [{ "browserLiveToken": [] }],
        "parameters": [{ "$ref": "#/components/parameters/SessionID" }],
        "responses": { "200": { "$ref": "#/components/responses/BrowserSession" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" } }
      },
      "BrowserLiveRelease": {
        "tags": ["browser"],
        "summary": "Return a browser session to agent control from the live page",
        "security": [{ "browserLiveToken": [] }],
        "parameters": [{ "$ref": "#/components/parameters/SessionID" }],
        "responses": { "200": { "$ref": "#/components/responses/BrowserSession" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" } }
      }
    },
    "schemas": {
      "UUID": { "type": "string", "format": "uuid" },
      "DateTime": { "type": "string", "format": "date-time" },
      "APIKeyScope": {
        "type": "string",
        "enum": ["computers:create", "computers:read", "computers:control", "computers:destroy", "browser:create", "browser:read", "browser:control", "browser:cookies:read", "browser:destroy", "mail:inboxes:create", "mail:inboxes:read", "mail:messages:read", "mail:messages:send", "mail:messages:delete", "billing:usage:read", "artifacts:read", "api_keys:create", "api_keys:read"]
      },
      "ComputerStatus": { "type": "string", "enum": ["provisioning", "running", "idle", "destroying", "destroyed", "failed"] },
      "BrowserSessionStatus": { "type": "string", "enum": ["provisioning", "ready", "agent_controlled", "human_controlled", "closed", "failed"] },
      "InboxStatus": { "type": "string", "enum": ["active", "disabled"] },
      "MailDeliveryStatus": { "type": "string", "enum": ["received", "queued", "sending", "sent", "failed"] },
      "ComputerCommandStatus": { "type": "string", "enum": ["queued", "running", "succeeded", "failed"] },
      "SelfServiceRegistrationRequest": {
        "type": "object",
        "required": ["name", "emailUserpart"],
        "properties": {
          "name": { "type": "string" },
          "emailUserpart": { "type": "string" },
          "apiKeyName": { "type": "string" },
          "scopes": { "type": "array", "items": { "$ref": "#/components/schemas/APIKeyScope" } }
        }
      },
      "SelfServiceRegistrationResponse": {
        "type": "object",
        "required": ["organizationID", "agent", "apiKey"],
        "properties": {
          "organizationID": { "$ref": "#/components/schemas/UUID" },
          "agent": { "$ref": "#/components/schemas/AgentRegistrationRecord" },
          "apiKey": { "$ref": "#/components/schemas/APIKeyCreatedResponse" }
        }
      },
      "RegisterAgentRequest": { "type": "object", "required": ["name", "emailUserpart"], "properties": { "name": { "type": "string" }, "emailUserpart": { "type": "string" } } },
      "CreateScopedAPIKeyRequest": { "type": "object", "required": ["name"], "properties": { "name": { "type": "string" }, "scopes": { "type": "array", "items": { "$ref": "#/components/schemas/APIKeyScope" } } } },
      "APIKeySummary": {
        "type": "object",
        "required": ["id", "organizationID", "name", "prefix", "scopes", "createdAt"],
        "properties": {
          "id": { "$ref": "#/components/schemas/UUID" },
          "organizationID": { "$ref": "#/components/schemas/UUID" },
          "name": { "type": "string" },
          "prefix": { "type": "string" },
          "scopes": { "type": "array", "items": { "$ref": "#/components/schemas/APIKeyScope" } },
          "createdAt": { "$ref": "#/components/schemas/DateTime" }
        }
      },
      "APIKeyCreatedResponse": {
        "allOf": [
          { "$ref": "#/components/schemas/APIKeySummary" },
          { "type": "object", "required": ["token"], "properties": {
            "token": { "type": "string", "description": "Raw API key token returned only once." },
            "agentPrompt": { "type": "string", "description": "Copyable prompt for an agent to install/use Agent Host." },
            "skillMarkdown": { "type": "string", "description": "Ready-made SKILL.md content returned only with the one-time API key response." },
            "skillDownloadURL": { "type": "string", "format": "uri", "description": "Authenticated URL for a generic SKILL.md template for this key." }
          } }
        ]
      },
      "ComputerRecord": {
        "type": "object",
        "required": ["id", "organizationID", "status", "serverName", "image", "serverType", "location", "ttlSeconds", "createdAt", "updatedAt"],
        "properties": {
          "id": { "$ref": "#/components/schemas/UUID" },
          "organizationID": { "$ref": "#/components/schemas/UUID" },
          "status": { "$ref": "#/components/schemas/ComputerStatus" },
          "providerServerID": { "type": "integer" },
          "serverName": { "type": "string" },
          "image": { "type": "string" },
          "serverType": { "type": "string" },
          "location": { "type": "string" },
          "browserURL": { "type": "string" },
          "browserTitle": { "type": "string" },
          "ttlSeconds": { "type": "integer" },
          "createdAt": { "$ref": "#/components/schemas/DateTime" },
          "updatedAt": { "$ref": "#/components/schemas/DateTime" }
        }
      },
      "CreateComputerRequest": {
        "type": "object",
        "properties": {
          "image": { "type": "string" },
          "serverType": { "type": "string" },
          "location": { "type": "string" },
          "ttlSeconds": { "type": "integer", "minimum": 1 }
        }
      },
      "ComputerCommandRecord": {
        "type": "object",
        "required": ["id", "organizationID", "computerID", "kind", "payload", "status", "createdAt", "updatedAt"],
        "properties": {
          "id": { "$ref": "#/components/schemas/UUID" },
          "organizationID": { "$ref": "#/components/schemas/UUID" },
          "computerID": { "$ref": "#/components/schemas/UUID" },
          "kind": { "type": "string" },
          "payload": { "type": "string" },
          "status": { "$ref": "#/components/schemas/ComputerCommandStatus" },
          "result": { "type": "string" },
          "createdAt": { "$ref": "#/components/schemas/DateTime" },
          "updatedAt": { "$ref": "#/components/schemas/DateTime" }
        }
      },
      "CreateComputerCommandRequest": { "type": "object", "required": ["kind", "payload"], "properties": { "kind": { "type": "string" }, "payload": { "type": "string" } } },
      "BrowserSessionRecord": {
        "type": "object",
        "required": ["id", "organizationID", "computerID", "status", "liveURL", "signalingURL", "guestSignalingURL", "createdAt", "updatedAt"],
        "properties": {
          "id": { "$ref": "#/components/schemas/UUID" },
          "organizationID": { "$ref": "#/components/schemas/UUID" },
          "computerID": { "$ref": "#/components/schemas/UUID" },
          "status": { "$ref": "#/components/schemas/BrowserSessionStatus" },
          "liveURL": { "type": "string" },
          "signalingURL": { "type": "string" },
          "guestSignalingURL": { "type": "string" },
          "createdAt": { "$ref": "#/components/schemas/DateTime" },
          "updatedAt": { "$ref": "#/components/schemas/DateTime" }
        }
      },
      "CreateBrowserSessionRequest": { "type": "object", "properties": { "computerID": { "$ref": "#/components/schemas/UUID" }, "ttlSeconds": { "type": "integer", "minimum": 1 } } },
      "BrowserNavigateRequest": { "type": "object", "required": ["url"], "properties": { "url": { "type": "string", "format": "uri" } } },
      "BrowserScreenshotRequest": { "type": "object", "properties": { "format": { "type": "string", "enum": ["jpeg", "png"], "default": "jpeg" }, "quality": { "type": "integer", "minimum": 1, "maximum": 100, "default": 80 } } },
      "BrowserEvalRequest": { "type": "object", "required": ["expression"], "properties": { "expression": { "type": "string", "minLength": 1, "maxLength": 65536 }, "awaitPromise": { "type": "boolean", "default": true }, "timeoutMilliseconds": { "type": "integer", "minimum": 100, "maximum": 30000, "default": 5000 } } },
      "WebRTCOfferRequest": { "type": "object", "required": ["sdp", "type"], "properties": { "sdp": { "type": "string" }, "type": { "type": "string", "enum": ["offer"] } } },
      "WebRTCSignalResponse": { "type": "object", "required": ["accepted", "sessionID", "message"], "properties": { "accepted": { "type": "boolean" }, "sessionID": { "$ref": "#/components/schemas/UUID" }, "message": { "type": "string" } } },
      "BrowserLiveTokenResponse": { "type": "object", "required": ["sessionID", "token", "expiresAt", "liveURL"], "properties": { "sessionID": { "$ref": "#/components/schemas/UUID" }, "token": { "type": "string" }, "expiresAt": { "$ref": "#/components/schemas/DateTime" }, "liveURL": { "type": "string" } } },
      "BrowserLiveConfigurationResponse": { "type": "object", "required": ["sessionID", "status", "iceServers"], "properties": { "sessionID": { "$ref": "#/components/schemas/UUID" }, "status": { "$ref": "#/components/schemas/BrowserSessionStatus" }, "iceServers": { "type": "array", "items": { "$ref": "#/components/schemas/RTCIceServer" } } } },
      "RTCIceServer": { "type": "object", "required": ["urls"], "properties": { "urls": { "oneOf": [{ "type": "string" }, { "type": "array", "items": { "type": "string" } }] }, "username": { "type": "string" }, "credential": { "type": "string" } } },
      "InboxRecord": {
        "type": "object",
        "required": ["id", "organizationID", "mailDomain", "userpart", "address", "status", "createdAt"],
        "properties": {
          "id": { "$ref": "#/components/schemas/UUID" },
          "organizationID": { "$ref": "#/components/schemas/UUID" },
          "mailDomainID": { "$ref": "#/components/schemas/UUID" },
          "mailDomain": { "type": "string" },
          "storageServerID": { "$ref": "#/components/schemas/UUID" },
          "userpart": { "type": "string" },
          "address": { "type": "string", "format": "email" },
          "status": { "$ref": "#/components/schemas/InboxStatus" },
          "createdAt": { "$ref": "#/components/schemas/DateTime" }
        }
      },
      "CreateInboxRequest": { "type": "object", "required": ["userpart"], "properties": { "userpart": { "type": "string", "description": "Lowercased before insert. The domain is selected from active AgentHost-managed mail domains by the control plane." } } },
      "AgentRegistrationRecord": { "type": "object", "required": ["id", "organizationID", "name", "inbox", "createdAt"], "properties": { "id": { "$ref": "#/components/schemas/UUID" }, "organizationID": { "$ref": "#/components/schemas/UUID" }, "name": { "type": "string" }, "inbox": { "$ref": "#/components/schemas/InboxRecord" }, "createdAt": { "$ref": "#/components/schemas/DateTime" } } },
      "SendMailRequest": { "type": "object", "required": ["to", "subject", "text"], "properties": { "to": { "type": "array", "items": { "type": "string", "format": "email" } }, "subject": { "type": "string" }, "text": { "type": "string" } } },
      "MailMessageRecord": {
        "type": "object",
        "required": ["id", "organizationID", "inboxID", "direction", "deliveryStatus", "deliveryAttempts", "from", "to", "subject", "text", "createdAt", "updatedAt"],
        "properties": {
          "id": { "$ref": "#/components/schemas/UUID" },
          "organizationID": { "$ref": "#/components/schemas/UUID" },
          "inboxID": { "$ref": "#/components/schemas/UUID" },
          "direction": { "type": "string", "enum": ["inbound", "outbound"] },
          "deliveryStatus": { "$ref": "#/components/schemas/MailDeliveryStatus" },
          "deliveryAttempts": { "type": "integer" },
          "lastDeliveryError": { "type": "string" },
          "from": { "type": "string" },
          "to": { "type": "array", "items": { "type": "string" } },
          "subject": { "type": "string" },
          "text": { "type": "string" },
          "createdAt": { "$ref": "#/components/schemas/DateTime" },
          "updatedAt": { "$ref": "#/components/schemas/DateTime" },
          "deletedAt": { "$ref": "#/components/schemas/DateTime" }
        }
      },
      "ArtifactRecord": {
        "type": "object",
        "required": ["id", "organizationID", "kind", "filename", "contentType", "byteCount", "storageKey", "createdAt"],
        "properties": {
          "id": { "$ref": "#/components/schemas/UUID" },
          "organizationID": { "$ref": "#/components/schemas/UUID" },
          "computerID": { "$ref": "#/components/schemas/UUID" },
          "browserSessionID": { "$ref": "#/components/schemas/UUID" },
          "kind": { "type": "string" },
          "filename": { "type": "string" },
          "contentType": { "type": "string" },
          "byteCount": { "type": "integer" },
          "storageKey": { "type": "string" },
          "createdAt": { "$ref": "#/components/schemas/DateTime" }
        }
      },
      "AgentResourceSnapshot": { "type": "object", "required": ["organizationID", "computers", "browserSessions", "inboxes"], "properties": { "organizationID": { "$ref": "#/components/schemas/UUID" }, "computers": { "type": "array", "items": { "$ref": "#/components/schemas/ComputerRecord" } }, "browserSessions": { "type": "array", "items": { "$ref": "#/components/schemas/BrowserSessionRecord" } }, "inboxes": { "type": "array", "items": { "$ref": "#/components/schemas/InboxRecord" } } } },
      "UsageEventRecord": { "type": "object", "required": ["id", "organizationID", "resourceType", "action", "quantity", "metadata", "createdAt"], "properties": { "id": { "$ref": "#/components/schemas/UUID" }, "organizationID": { "$ref": "#/components/schemas/UUID" }, "resourceType": { "type": "string" }, "resourceID": { "$ref": "#/components/schemas/UUID" }, "action": { "type": "string" }, "quantity": { "type": "integer" }, "metadata": { "type": "object", "additionalProperties": { "type": "string" } }, "createdAt": { "$ref": "#/components/schemas/DateTime" } } },
      "UsageComputerBreakdown": { "type": "object", "additionalProperties": true },
      "UsageSummary": {
        "type": "object",
        "required": ["organizationID", "periodEnd", "eventsScanned", "activeComputers", "computerRuntimeSeconds", "computerBillableSeconds", "unpricedServerTypes", "computersByServerType", "browserSessionsCreated", "browserMinutes", "mailInboundMessages", "mailOutboundMessages", "artifactBytes"],
        "properties": {
          "organizationID": { "$ref": "#/components/schemas/UUID" },
          "periodStart": { "$ref": "#/components/schemas/DateTime" },
          "periodEnd": { "$ref": "#/components/schemas/DateTime" },
          "eventsScanned": { "type": "integer" },
          "activeComputers": { "type": "integer" },
          "computerRuntimeSeconds": { "type": "integer" },
          "computerBillableSeconds": { "type": "integer" },
          "computerEstimatedCostMicroEUR": { "type": "integer" },
          "unpricedServerTypes": { "type": "array", "items": { "type": "string" } },
          "computersByServerType": { "type": "array", "items": { "$ref": "#/components/schemas/UsageComputerBreakdown" } },
          "browserSessionsCreated": { "type": "integer" },
          "browserMinutes": { "type": "integer" },
          "mailInboundMessages": { "type": "integer" },
          "mailOutboundMessages": { "type": "integer" },
          "artifactBytes": { "type": "integer" }
        }
      },
      "UsageStatement": {
        "type": "object",
        "additionalProperties": true,
        "required": ["id", "organizationID", "status", "currency", "generatedAt", "periodStart", "periodEnd", "lineItems", "unpricedServerTypes", "unpricedMeters", "summary"],
        "properties": {
          "id": { "$ref": "#/components/schemas/UUID" },
          "organizationID": { "$ref": "#/components/schemas/UUID" },
          "status": { "type": "string" },
          "currency": { "type": "string" },
          "generatedAt": { "$ref": "#/components/schemas/DateTime" },
          "periodStart": { "$ref": "#/components/schemas/DateTime" },
          "periodEnd": { "$ref": "#/components/schemas/DateTime" },
          "billingPlan": { "type": "object", "additionalProperties": true },
          "lineItems": { "type": "array", "items": { "type": "object", "additionalProperties": true } },
          "subtotalMicroEUR": { "type": "integer" },
          "totalMicroEUR": { "type": "integer" },
          "unpricedServerTypes": { "type": "array", "items": { "type": "string" } },
          "unpricedMeters": { "type": "array", "items": { "type": "string" } },
          "summary": { "$ref": "#/components/schemas/UsageSummary" }
        }
      },
      "FinalizeUsageStatementRequest": { "type": "object", "required": ["start", "end"], "properties": { "start": { "$ref": "#/components/schemas/DateTime" }, "end": { "$ref": "#/components/schemas/DateTime" } } },
      "FinalizedUsageStatementRecord": {
        "type": "object",
        "additionalProperties": false,
        "required": ["id", "organizationID", "statementNumber", "status", "currency", "periodStart", "periodEnd", "subtotalMicroEUR", "totalMicroEUR", "finalizedAt", "statement"],
        "properties": {
          "id": { "$ref": "#/components/schemas/UUID" },
          "organizationID": { "$ref": "#/components/schemas/UUID" },
          "statementNumber": { "type": "string" },
          "status": { "type": "string", "enum": ["finalized"] },
          "currency": { "type": "string" },
          "periodStart": { "$ref": "#/components/schemas/DateTime" },
          "periodEnd": { "$ref": "#/components/schemas/DateTime" },
          "subtotalMicroEUR": { "type": "integer" },
          "totalMicroEUR": { "type": "integer" },
          "finalizedAt": { "$ref": "#/components/schemas/DateTime" },
          "mollieInvoiceID": { "type": "string" },
          "mollieInvoiceURL": { "type": "string", "format": "uri" },
          "mollieInvoiceStatus": { "type": "string", "description": "Raw Mollie Sales Invoice status cached from Mollie draft creation or pull reconciliation. AgentHost does not model a separate payment or collection lifecycle." },
          "mollieInvoiceUpdatedAt": { "$ref": "#/components/schemas/DateTime" },
          "financeReviewNote": { "type": "string", "description": "Internal operator note; not sent to Mollie." },
          "financeReviewUpdatedAt": { "$ref": "#/components/schemas/DateTime" },
          "statement": { "$ref": "#/components/schemas/UsageStatement" }
        }
      },
      "BillingAccountRecord": {
        "type": "object",
        "required": ["organizationID", "accessState", "createdAt", "updatedAt"],
        "properties": {
          "organizationID": { "$ref": "#/components/schemas/UUID" },
          "accessState": { "type": "string", "enum": ["active", "past_due", "suspended"] },
          "billingEmail": { "type": "string", "format": "email" },
          "billingName": { "type": "string" },
          "taxID": { "type": "string" },
          "mollieCustomerID": { "type": "string" },
          "createdAt": { "$ref": "#/components/schemas/DateTime" },
          "updatedAt": { "$ref": "#/components/schemas/DateTime" }
        }
      }
    }
  }
}