{ "openapi": "3.1.0", "info": { "title": "Backoffice API", "version": "1.0.0", "description": "Customer, resource usage, settled billing and log queries, plus explicitly scoped suspension and Box stop commands. [Agent guide](/llms.txt)." }, "servers": [ { "url": "/v1" } ], "paths": { "/observability/schema": { "get": { "operationId": "describeLogSchema", "description": "Live DESCRIBE output for otel.otel_logs, using the same authentication and query budget.", "security": [ { "LogApiKey": [] } ], "x-required-scopes": [ "observability.logs.query" ], "responses": { "200": { "$ref": "#/components/responses/LogQueryResult" }, "401": { "$ref": "#/components/responses/Problem" }, "403": { "$ref": "#/components/responses/Problem" }, "429": { "$ref": "#/components/responses/Problem" }, "502": { "$ref": "#/components/responses/Problem" }, "503": { "$ref": "#/components/responses/Problem" }, "504": { "$ref": "#/components/responses/Problem" } } } }, "/observability/query": { "post": { "operationId": "queryLogsSql", "description": "One SELECT or WITH statement, typed ClickHouse parameters, fixed JSON output. FORMAT, INTO, SETTINGS and multiple statements are rejected. Requires a personal log API key; cookies do not authorize queries.", "security": [ { "LogApiKey": [] } ], "x-required-scopes": [ "observability.logs.query" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LogSqlQuery" } } } }, "responses": { "200": { "$ref": "#/components/responses/LogQueryResult" }, "400": { "$ref": "#/components/responses/Problem" }, "401": { "$ref": "#/components/responses/Problem" }, "403": { "$ref": "#/components/responses/Problem" }, "413": { "$ref": "#/components/responses/Problem" }, "422": { "$ref": "#/components/responses/Problem" }, "429": { "$ref": "#/components/responses/Problem" }, "502": { "$ref": "#/components/responses/Problem" }, "503": { "$ref": "#/components/responses/Problem" }, "504": { "$ref": "#/components/responses/Problem" } } } }, "/observability/logs/search": { "post": { "operationId": "searchLogs", "description": "Search the half-open interval from <= Timestamp < to, at most seven days. Returns newest logs first; narrow the interval to retrieve more.", "security": [ { "LogApiKey": [] } ], "x-required-scopes": [ "observability.logs.query" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LogSearch" } } } }, "responses": { "200": { "$ref": "#/components/responses/LogQueryResult" }, "400": { "$ref": "#/components/responses/Problem" }, "401": { "$ref": "#/components/responses/Problem" }, "403": { "$ref": "#/components/responses/Problem" }, "422": { "$ref": "#/components/responses/Problem" }, "429": { "$ref": "#/components/responses/Problem" }, "502": { "$ref": "#/components/responses/Problem" }, "503": { "$ref": "#/components/responses/Problem" }, "504": { "$ref": "#/components/responses/Problem" } } } }, "/observability/logs/aggregate": { "post": { "operationId": "aggregateLogs", "description": "Count logs by service, severity and/or UTC time bucket. Uses the same filters and seven-day maximum interval as search.", "security": [ { "LogApiKey": [] } ], "x-required-scopes": [ "observability.logs.query" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LogAggregate" } } } }, "responses": { "200": { "$ref": "#/components/responses/LogQueryResult" }, "400": { "$ref": "#/components/responses/Problem" }, "401": { "$ref": "#/components/responses/Problem" }, "403": { "$ref": "#/components/responses/Problem" }, "422": { "$ref": "#/components/responses/Problem" }, "429": { "$ref": "#/components/responses/Problem" }, "502": { "$ref": "#/components/responses/Problem" }, "503": { "$ref": "#/components/responses/Problem" }, "504": { "$ref": "#/components/responses/Problem" } } } }, "/customers": { "get": { "operationId": "listAnalysisCustomers", "description": "Search existing organizations by true creation time. Requires customers.impact.read; cookies cannot authorize this operation. Includes the stored creator reference, nullable current creator identity, member/Box counts and source/impact state. Account linking can update the creator reference to the primary account. Creation filters use a half-open interval; both are optional. Sort is creation time at millisecond precision, then organization ID ascending. Follow nextCursor with unchanged filters; pages are live, not a retained snapshot, and exclude deleted organizations. No usage, billing or activation facts. Unsupported or unavailable sources return 503, never a successful empty list. All responses are private, no-store.", "security": [ { "PersonalApiKey": [] } ], "x-required-scopes": [ "customers.impact.read" ], "parameters": [ { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/CreatedFrom" }, { "$ref": "#/components/parameters/CreatedTo" }, { "in": "query", "name": "q", "schema": { "type": "string", "minLength": 2, "maxLength": 200 } } ], "responses": { "200": { "description": "One bounded page from the current customer directory.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PageAnalysisCustomer" } } } }, "400": { "$ref": "#/components/responses/Problem" }, "401": { "$ref": "#/components/responses/Problem" }, "403": { "$ref": "#/components/responses/Problem" }, "429": { "$ref": "#/components/responses/Problem" }, "503": { "$ref": "#/components/responses/Problem" }, "504": { "$ref": "#/components/responses/Problem" } } } }, "/customers/{organizationId}": { "get": { "operationId": "getAnalysisCustomer", "description": "Read customer metadata with independently paginated members and Box references. Requires customers.impact.read. Usage and billing are neither requested nor returned. Optional include=activation adds the latest Box creation and start/deletion times; null times do not establish never activated. Query every required page; source failure is 503, while a missing organization is 404. All responses are private, no-store.", "security": [ { "PersonalApiKey": [] } ], "x-required-scopes": [ "customers.impact.read" ], "parameters": [ { "in": "path", "name": "organizationId", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,199}$" } }, { "in": "query", "name": "memberCursor", "schema": { "type": "string", "minLength": 1, "maxLength": 2048 } }, { "in": "query", "name": "boxCursor", "schema": { "type": "string", "minLength": 1, "maxLength": 2048 } }, { "in": "query", "name": "sectionLimit", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } }, { "in": "query", "name": "include", "schema": { "type": "string", "const": "activation" }, "description": "Return activation facts only when explicitly requested; usage and billing partitions are forbidden." } ], "responses": { "200": { "description": "Customer registration, members, Box references and impact.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerMetadata" } } } }, "400": { "$ref": "#/components/responses/Problem" }, "401": { "$ref": "#/components/responses/Problem" }, "403": { "$ref": "#/components/responses/Problem" }, "404": { "$ref": "#/components/responses/Problem" }, "429": { "$ref": "#/components/responses/Problem" }, "503": { "$ref": "#/components/responses/Problem" }, "504": { "$ref": "#/components/responses/Problem" } } } }, "/customers/{organizationId}/suspend": { "post": { "operationId": "suspendCustomerWithKey", "description": "Suspend first, then paginate all organization Boxes and request stops when stop_boxes=true. Requires customers.suspend and additionally platform.boxes.stop for stop_boxes=true. Omitted or false leaves existing delayed cleanup unchanged. Inspect stopBoxes.status and listingComplete for partial failure. No automatic retries or rollback.", "security": [ { "PersonalApiKey": [] } ], "x-required-scopes": [ "customers.suspend" ], "parameters": [ { "in": "path", "name": "organizationId", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,199}$" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuspendCustomerRequest" } } } }, "responses": { "200": { "description": "Suspension confirmed; inspect partial Box stop outcomes.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerSuspension" } } } }, "default": { "$ref": "#/components/responses/Problem" } } } }, "/customers/{organizationId}/boxes/{boxId}/stop": { "post": { "operationId": "stopCustomerBoxWithKey", "description": "Verify Box ownership and request its stop using the BoxLite Admin credential. Requires platform.boxes.stop. Accepted means a desired-state request, not observed shutdown. No automatic retries.", "security": [ { "PersonalApiKey": [] } ], "x-required-scopes": [ "platform.boxes.stop" ], "parameters": [ { "in": "path", "name": "organizationId", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,199}$" } }, { "in": "path", "name": "boxId", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,199}$" } } ], "responses": { "202": { "description": "Stop accepted or Box already stopped.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BoxStopResult" } } } }, "default": { "$ref": "#/components/responses/Problem" } } } }, "/customers/{organizationId}/unsuspend": { "post": { "operationId": "unsuspendCustomerWithKey", "description": "Restore organization access without starting or restarting any Boxes. Requires customers.unsuspend. Accepts no body or an empty JSON object; no automatic retries.", "security": [ { "PersonalApiKey": [] } ], "x-required-scopes": [ "customers.unsuspend" ], "parameters": [ { "in": "path", "name": "organizationId", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,199}$" } } ], "responses": { "200": { "description": "Organization access restored; Box states unchanged.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerUnsuspension" } } } }, "default": { "$ref": "#/components/responses/Problem" } } } }, "/usage": { "get": { "operationId": "queryResourceUsage", "description": "Query recorded resource allocations with fixed snapshot pagination. Requires customers.usage.read; returns IDs and metrics without names or emails. Coverage is unknown because missing usage events are not backfilled; missing rows must not be converted to zero. Every page rechecks authorization and is bound to the same employee, Key, stage and query. Repeat query parameters when following nextCursor. A 410 requires restarting the entire query. All responses are private, no-store.", "security": [ { "PersonalApiKey": [] } ], "x-required-scopes": [ "customers.usage.read" ], "parameters": [ { "in": "query", "name": "from", "required": true, "schema": { "type": "string", "format": "date-time" }, "description": "Inclusive RFC3339 instant with timezone and at most millisecond precision." }, { "in": "query", "name": "to", "required": true, "schema": { "type": "string", "format": "date-time" }, "description": "Exclusive instant after from and no later than query time. Hour queries span at most 7 days; day/window at most 90 days." }, { "in": "query", "name": "granularity", "schema": { "type": "string", "enum": [ "window", "hour", "day" ], "default": "window" }, "description": "Buckets start at from; hour/day use fixed 3600/86400 seconds, with the final bucket clipped to to." }, { "in": "query", "name": "metrics", "schema": { "type": "string", "maxLength": 200, "default": "computeVcpuSeconds,storageByteSeconds" }, "description": "Comma-separated distinct computeVcpuSeconds, memoryGibSeconds and/or storageByteSeconds." }, { "in": "query", "name": "groupBy", "schema": { "type": "string", "maxLength": 200, "default": "organizationId" }, "description": "One or two distinct comma-separated organizationId, regionId or boxId dimensions." }, { "in": "query", "name": "organizationId", "schema": { "type": "string", "format": "uuid" } }, { "in": "query", "name": "regionId", "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$" } }, { "in": "query", "name": "boxId", "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$" } }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Limit" } ], "responses": { "200": { "description": "One page of a fixed recorded-usage result; empty items do not prove zero usage.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResourceUsagePage" } } } }, "400": { "$ref": "#/components/responses/Problem" }, "401": { "$ref": "#/components/responses/Problem" }, "403": { "$ref": "#/components/responses/Problem" }, "410": { "$ref": "#/components/responses/Problem" }, "422": { "$ref": "#/components/responses/Problem" }, "429": { "$ref": "#/components/responses/Problem" }, "503": { "$ref": "#/components/responses/Problem" }, "504": { "$ref": "#/components/responses/Problem" } } } }, "/billing/usage": { "get": { "operationId": "queryBillingUsage", "description": "Query settled Commerce usage by invoice creation time with fixed snapshot pagination. Requires customers.billing.read; returns IDs and metrics without names or emails. Coverage is unknown because settlement may be delayed; missing rows must not be converted to zero. Every page rechecks authorization and is bound to the same employee, Key, stage and query. Repeat query parameters when following nextCursor. A 410 requires restarting the entire query. All responses are private, no-store.", "security": [ { "PersonalApiKey": [] } ], "x-required-scopes": [ "customers.billing.read" ], "parameters": [ { "in": "query", "name": "from", "required": true, "schema": { "type": "string", "format": "date-time" }, "description": "Inclusive RFC3339 instant with timezone and at most millisecond precision." }, { "in": "query", "name": "to", "required": true, "schema": { "type": "string", "format": "date-time" }, "description": "Exclusive instant after from and no later than query time. Hour queries span at most 7 days; day/window at most 90 days." }, { "in": "query", "name": "granularity", "schema": { "type": "string", "enum": [ "window", "hour", "day" ], "default": "window" }, "description": "Buckets start at from; hour/day use fixed 3600/86400 seconds, with the final bucket clipped to to." }, { "in": "query", "name": "organizationId", "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,200}$" } }, { "in": "query", "name": "currency", "schema": { "type": "string", "pattern": "^[A-Z]{3}$" } }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Limit" } ], "responses": { "200": { "description": "One page of settled usage; amounts are decimal strings in currency minor units. Empty items do not prove zero usage.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BillingUsagePage" } } } }, "400": { "$ref": "#/components/responses/Problem" }, "401": { "$ref": "#/components/responses/Problem" }, "403": { "$ref": "#/components/responses/Problem" }, "410": { "$ref": "#/components/responses/Problem" }, "422": { "$ref": "#/components/responses/Problem" }, "429": { "$ref": "#/components/responses/Problem" }, "503": { "$ref": "#/components/responses/Problem" }, "504": { "$ref": "#/components/responses/Problem" } } } } }, "components": { "securitySchemes": { "LogApiKey": { "type": "http", "scheme": "bearer", "description": "Legacy bl_logs_ key or scoped bl_api_ key granting observability.logs.query in this environment." }, "PersonalApiKey": { "type": "http", "scheme": "bearer", "description": "Personal scoped key (bl_api_), limited to explicit grants, current employee capabilities and this environment. No employee session or key management access. Writes require explicitly granted command scopes." } }, "responses": { "LogQueryResult": { "description": "Complete bounded query result; budget overflow never silently returns partial aggregation. Int64/UInt64 values are strings, timestamps retain source precision. All responses are private, no-store.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LogQueryResult" } } } }, "Problem": { "description": "Stable problem response.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ApiProblem" } } } } }, "schemas": { "LogQueryResult": { "type": "object", "required": [ "queryId", "columns", "rows", "statistics" ], "properties": { "queryId": { "type": "string", "format": "uuid" }, "columns": { "type": "array", "items": { "type": "object", "required": [ "name", "type" ], "properties": { "name": { "type": "string" }, "type": { "type": "string" } } } }, "rows": { "type": "array", "maxItems": 10000, "items": { "type": "object", "additionalProperties": true } }, "statistics": { "type": "object", "required": [ "elapsedMs", "readRows", "readBytes" ], "properties": { "elapsedMs": { "type": "number" }, "readRows": { "type": "string", "pattern": "^[0-9]+$" }, "readBytes": { "type": "string", "pattern": "^[0-9]+$" } } } } }, "ApiProblem": { "type": "object", "additionalProperties": false, "required": [ "type", "title", "status", "code", "message", "correlationId" ], "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "code": { "type": "string" }, "message": { "type": "string" }, "correlationId": { "type": "string", "format": "uuid" }, "prerequisite": { "type": "string" }, "fields": { "type": "array", "items": { "$ref": "#/components/schemas/ProblemField" } } } }, "ProblemField": { "type": "object", "additionalProperties": false, "required": [ "field", "code", "message" ], "properties": { "field": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } }, "LogSqlQuery": { "type": "object", "additionalProperties": false, "required": [ "sql" ], "properties": { "sql": { "type": "string", "minLength": 1, "maxLength": 32768 }, "parameters": { "type": "object", "maxProperties": 100, "propertyNames": { "pattern": "^[A-Za-z][A-Za-z0-9_]{0,63}$" }, "additionalProperties": { "oneOf": [ { "type": "string", "maxLength": 4096 }, { "type": "number" }, { "type": "boolean" } ] }, "description": "Named values for ClickHouse placeholders such as '{service:String}'." } } }, "LogSearch": { "type": "object", "additionalProperties": false, "required": [ "from", "to" ], "properties": { "from": { "type": "string", "format": "date-time" }, "to": { "type": "string", "format": "date-time" }, "service": { "type": "string", "minLength": 1, "maxLength": 255 }, "severity": { "type": "string", "enum": [ "TRACE", "DEBUG", "INFO", "WARN", "ERROR", "FATAL" ] }, "text": { "type": "string", "minLength": 1, "maxLength": 1024 }, "traceId": { "type": "string", "pattern": "^[a-fA-F0-9]{32}$" }, "limit": { "type": "integer", "minimum": 1, "maximum": 10000, "default": 100 } } }, "LogAggregate": { "type": "object", "additionalProperties": false, "required": [ "from", "to" ], "properties": { "from": { "type": "string", "format": "date-time" }, "to": { "type": "string", "format": "date-time" }, "service": { "type": "string", "minLength": 1, "maxLength": 255 }, "severity": { "type": "string", "enum": [ "TRACE", "DEBUG", "INFO", "WARN", "ERROR", "FATAL" ] }, "text": { "type": "string", "minLength": 1, "maxLength": 1024 }, "traceId": { "type": "string", "pattern": "^[a-fA-F0-9]{32}$" }, "limit": { "type": "integer", "minimum": 1, "maximum": 10000, "default": 100 }, "groupBy": { "type": "array", "minItems": 1, "maxItems": 3, "default": [ "service" ], "items": { "type": "string", "enum": [ "service", "severity", "time" ] } }, "bucketSeconds": { "type": "integer", "enum": [ 60, 300, 3600, 86400 ], "default": 300 } } }, "PageAnalysisCustomer": { "allOf": [ { "$ref": "#/components/schemas/PageBase" }, { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "allOf": [ { "$ref": "#/components/schemas/CustomerSummary" }, { "type": "object", "required": [ "createdAt", "createdBy", "creator" ] } ] } } } } ] }, "PageBase": { "type": "object", "required": [ "nextCursor", "limit", "sources" ], "properties": { "nextCursor": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "limit": { "type": "integer", "minimum": 1, "maximum": 200 }, "sources": { "type": "array", "items": { "$ref": "#/components/schemas/SourceState" } } } }, "SourceState": { "type": "object", "additionalProperties": false, "required": [ "source", "status", "observedAt" ], "properties": { "source": { "type": "string" }, "status": { "type": "string", "enum": [ "live", "stale", "empty", "unavailable" ] }, "observedAt": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "prerequisite": { "type": "string" } } }, "CustomerSummary": { "type": "object", "additionalProperties": false, "required": [ "organizationId", "name", "memberCount", "boxCount", "impactState", "source" ], "properties": { "createdAt": { "type": "string", "format": "date-time", "description": "True organization creation time, not earliest membership." }, "createdBy": { "type": "string", "description": "Stored creator reference; account linking updates it to the primary account ID." }, "creator": { "oneOf": [ { "$ref": "#/components/schemas/CustomerCreator" }, { "type": "null" } ] }, "organizationId": { "type": "string" }, "name": { "type": "string" }, "memberCount": { "type": "integer", "minimum": 0 }, "boxCount": { "type": "integer", "minimum": 0 }, "impactState": { "$ref": "#/components/schemas/ImpactState" }, "source": { "$ref": "#/components/schemas/SourceState" }, "memberEmails": { "type": "array", "maxItems": 200, "description": "Present only with include=directory. The first 200 non-empty member emails, ordered by user ID.", "items": { "type": "string" } }, "wallet": { "$ref": "#/components/schemas/CustomerWallet" } } }, "CustomerCreator": { "type": "object", "additionalProperties": false, "required": [ "userId", "email" ], "description": "Current identity referenced by createdBy, including account-linking changes; not a registration-time identity snapshot.", "properties": { "userId": { "type": "string" }, "email": { "type": [ "string", "null" ], "format": "email" }, "displayName": { "type": "string" } } }, "ImpactState": { "type": "string", "enum": [ "impacted", "not_impacted", "unknown" ] }, "CustomerWallet": { "description": "Present only with include=directory and customers.billing.read. none means no active wallet; error means the wallet could not be read.", "oneOf": [ { "type": "object", "additionalProperties": false, "required": [ "status", "balanceMinor", "currency" ], "properties": { "status": { "type": "string", "enum": [ "ready" ] }, "balanceMinor": { "type": "string", "pattern": "^-?\\d+$" }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$" } } }, { "type": "object", "additionalProperties": false, "required": [ "status" ], "properties": { "status": { "type": "string", "enum": [ "none", "error" ] } } } ] }, "CustomerMetadata": { "type": "object", "additionalProperties": false, "required": [ "organizationId", "name", "createdAt", "createdBy", "creator", "members", "boxes", "impact", "sources" ], "properties": { "organizationId": { "type": "string" }, "suspended": { "type": "boolean", "readOnly": true, "description": "Stored organization suspension flag. Omitted when the source cannot report it; absence does not mean false." }, "name": { "type": "string" }, "activation": { "oneOf": [ { "$ref": "#/components/schemas/CustomerActivation" }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time" }, "createdBy": { "type": "string", "description": "Stored creator reference; account linking updates it to the primary account ID." }, "creator": { "oneOf": [ { "$ref": "#/components/schemas/CustomerCreator" }, { "type": "null" } ] }, "members": { "$ref": "#/components/schemas/PageCustomerMember" }, "boxes": { "$ref": "#/components/schemas/PageCustomerBox" }, "impact": { "type": "object", "additionalProperties": false, "required": [ "state", "evidence" ], "properties": { "state": { "$ref": "#/components/schemas/ImpactState" }, "evidence": { "type": "array", "items": { "$ref": "#/components/schemas/EvidenceItem" } } } }, "sources": { "type": "array", "items": { "$ref": "#/components/schemas/SourceState" } } } }, "CustomerActivation": { "type": "object", "additionalProperties": false, "required": [ "organizationId", "lastBoxCreatedAt", "lastBoxModifiedAt", "observedAt" ], "properties": { "organizationId": { "type": "string" }, "lastBoxCreatedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "Maximum retained Box creation or warm-pool claim time; survives Box deletion. Null means none was recorded; organizations older than tracking only have retained creation times." }, "lastBoxModifiedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "Maximum observed successful-start or accepted-deletion time. Cleanup, stops and label edits do not advance it; use current Box state for ongoing running." }, "observedAt": { "type": "string", "format": "date-time" } } }, "PageCustomerMember": { "allOf": [ { "$ref": "#/components/schemas/PageBase" }, { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/CustomerMemberSummary" } } } } ] }, "CustomerMemberSummary": { "type": "object", "additionalProperties": false, "required": [ "userId", "email", "organizationRole" ], "properties": { "userId": { "type": "string" }, "email": { "type": "string", "maxLength": 320, "description": "Source-provided member email text. An empty string means no email was provided; no email-format guarantee." }, "displayName": { "type": "string" }, "organizationRole": { "type": "string" }, "joinedAt": { "type": "string", "format": "date-time" } } }, "PageCustomerBox": { "allOf": [ { "$ref": "#/components/schemas/PageBase" }, { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/CustomerBoxReference" } } } } ] }, "CustomerBoxReference": { "type": "object", "additionalProperties": false, "required": [ "box", "impactState", "observedAt", "source" ], "properties": { "box": { "$ref": "#/components/schemas/EntityRef" }, "impactState": { "$ref": "#/components/schemas/ImpactState" }, "observedAt": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "source": { "$ref": "#/components/schemas/SourceState" } } }, "EntityRef": { "type": "object", "additionalProperties": false, "required": [ "kind", "id", "label", "href" ], "properties": { "kind": { "type": "string", "enum": [ "incident", "organization", "service", "region", "runner", "box", "job", "release" ] }, "id": { "type": "string" }, "label": { "type": "string" }, "href": { "type": "string", "pattern": "^/" } } }, "EvidenceItem": { "type": "object", "additionalProperties": false, "required": [ "source", "observedAt", "summary" ], "properties": { "source": { "type": "string" }, "observedAt": { "type": "string", "format": "date-time" }, "summary": { "type": "string" }, "externalRef": { "type": "string", "format": "uri" } } }, "SuspendCustomerRequest": { "type": "object", "additionalProperties": false, "properties": { "stop_boxes": { "type": "boolean", "description": "Omit or pass false to suspend only. True also requests stops for all non-archived, non-destroyed Boxes of this organization. False is omitted by the SDK." } } }, "CustomerSuspension": { "type": "object", "additionalProperties": false, "required": [ "organizationId", "suspended", "stopBoxes" ], "properties": { "organizationId": { "type": "string" }, "suspended": { "type": "boolean", "const": true }, "stopBoxes": { "type": "object", "additionalProperties": false, "required": [ "status", "listingComplete", "boxes" ], "properties": { "status": { "type": "string", "enum": [ "not_requested", "requested", "partial" ] }, "listingComplete": { "type": "boolean", "description": "All organization pages and batches visited. False when stops were not requested or traversal was interrupted." }, "boxes": { "type": "array", "maxItems": 20000, "items": { "$ref": "#/components/schemas/BoxStopResult" } }, "errorCode": { "type": "string" } } } } }, "BoxStopResult": { "type": "object", "additionalProperties": false, "required": [ "boxId", "status" ], "properties": { "boxId": { "type": "string" }, "status": { "type": "string", "enum": [ "requested", "already_stopped", "failed" ] }, "errorCode": { "type": "string", "description": "Sanitized upstream failure; inspect Box state before retrying." } } }, "CustomerUnsuspension": { "type": "object", "required": [ "organizationId", "suspended" ], "properties": { "organizationId": { "type": "string" }, "suspended": { "type": "boolean", "const": false } } }, "ResourceUsagePage": { "type": "object", "additionalProperties": false, "required": [ "queryId", "generatedAt", "expiresAt", "definitionVersion", "query", "coverage", "items", "nextCursor" ], "properties": { "queryId": { "type": "string", "format": "uuid" }, "generatedAt": { "type": "string", "format": "date-time" }, "expiresAt": { "type": "string", "format": "date-time", "description": "Fixed snapshot expiry; pagination does not renew it." }, "definitionVersion": { "type": "string", "const": "resource-usage-v1" }, "query": { "$ref": "#/components/schemas/ResourceUsageQuery" }, "coverage": { "type": "object", "additionalProperties": false, "required": [ "status", "reason" ], "properties": { "status": { "type": "string", "const": "unknown" }, "reason": { "type": "string", "const": "usage_events_not_backfilled" } } }, "items": { "type": "array", "maxItems": 200, "items": { "$ref": "#/components/schemas/ResourceUsageRow" } }, "nextCursor": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 2048 } } }, "ResourceUsageQuery": { "type": "object", "additionalProperties": false, "required": [ "from", "to", "granularity", "metrics", "groupBy" ], "properties": { "from": { "type": "string", "format": "date-time" }, "to": { "type": "string", "format": "date-time" }, "granularity": { "type": "string", "enum": [ "window", "hour", "day" ] }, "metrics": { "type": "array", "minItems": 1, "maxItems": 3, "uniqueItems": true, "items": { "type": "string", "enum": [ "computeVcpuSeconds", "memoryGibSeconds", "storageByteSeconds" ] } }, "groupBy": { "type": "array", "minItems": 1, "maxItems": 2, "uniqueItems": true, "items": { "type": "string", "enum": [ "organizationId", "regionId", "boxId" ] } }, "organizationId": { "type": "string", "format": "uuid" }, "regionId": { "type": "string" }, "boxId": { "type": "string" } } }, "ResourceUsageRow": { "type": "object", "additionalProperties": false, "required": [ "from", "to", "dimensions", "values", "sourcePeriodCount" ], "properties": { "from": { "type": "string", "format": "date-time" }, "to": { "type": "string", "format": "date-time" }, "dimensions": { "type": "object", "additionalProperties": false, "minProperties": 1, "maxProperties": 2, "properties": { "organizationId": { "type": "string", "format": "uuid" }, "regionId": { "type": "string" }, "boxId": { "type": "string" } } }, "values": { "type": "object", "additionalProperties": false, "minProperties": 1, "properties": { "computeVcpuSeconds": { "type": "string", "pattern": "^\\d+(\\.\\d+)?$", "description": "Allocated vCPU multiplied by overlapping seconds; not CPU utilization." }, "memoryGibSeconds": { "type": "string", "pattern": "^\\d+(\\.\\d+)?$", "description": "Allocated GiB multiplied by overlapping seconds; not process memory usage." }, "storageByteSeconds": { "type": "string", "pattern": "^\\d+(\\.\\d+)?$", "description": "Allocated disk bytes multiplied by overlapping seconds." } } }, "sourcePeriodCount": { "type": "integer", "minimum": 1, "maximum": 200000, "description": "Recorded periods contributing to this bucket/group; not evidence of complete coverage." } } }, "BillingUsagePage": { "type": "object", "additionalProperties": false, "required": [ "queryId", "generatedAt", "expiresAt", "definitionVersion", "query", "coverage", "items", "nextCursor" ], "properties": { "queryId": { "type": "string", "format": "uuid" }, "generatedAt": { "type": "string", "format": "date-time" }, "expiresAt": { "type": "string", "format": "date-time", "description": "Fixed snapshot expiry; pagination does not renew it." }, "definitionVersion": { "type": "string", "const": "billing-usage-v1" }, "query": { "$ref": "#/components/schemas/BillingUsageQuery" }, "coverage": { "type": "object", "additionalProperties": false, "required": [ "status", "reason" ], "properties": { "status": { "type": "string", "const": "unknown" }, "reason": { "type": "string", "const": "usage_settlement_may_be_delayed" } } }, "items": { "type": "array", "maxItems": 200, "items": { "$ref": "#/components/schemas/BillingUsageRow" } }, "nextCursor": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 2048 } } }, "BillingUsageQuery": { "type": "object", "additionalProperties": false, "required": [ "from", "to", "granularity" ], "properties": { "from": { "type": "string", "format": "date-time" }, "to": { "type": "string", "format": "date-time" }, "granularity": { "type": "string", "enum": [ "window", "hour", "day" ] }, "organizationId": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,200}$" }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$" } } }, "BillingUsageRow": { "type": "object", "additionalProperties": false, "required": [ "from", "to", "organizationId", "currency", "settledUsageMinor", "quotaCoveredMinor", "ordinaryWalletFundedMinor", "invoiceCount" ], "properties": { "from": { "type": "string", "format": "date-time" }, "to": { "type": "string", "format": "date-time" }, "organizationId": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,200}$" }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$" }, "settledUsageMinor": { "type": "string", "pattern": "^\\d+$", "maxLength": 100, "description": "Settled usage invoice amount in currency minor units; equals quotaCoveredMinor plus ordinaryWalletFundedMinor." }, "quotaCoveredMinor": { "type": "string", "pattern": "^\\d+$", "maxLength": 100 }, "ordinaryWalletFundedMinor": { "type": "string", "pattern": "^\\d+$", "maxLength": 100 }, "invoiceCount": { "type": "integer", "minimum": 1, "maximum": 200000 } } } }, "parameters": { "Cursor": { "in": "query", "name": "cursor", "schema": { "type": "string" } }, "Limit": { "in": "query", "name": "limit", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } }, "CreatedFrom": { "in": "query", "name": "createdFrom", "description": "Inclusive organization creation instant, RFC 3339 with offset and at most millisecond precision.", "schema": { "type": "string", "format": "date-time" } }, "CreatedTo": { "in": "query", "name": "createdTo", "description": "Exclusive organization creation instant; must be later than createdFrom when both are supplied.", "schema": { "type": "string", "format": "date-time" } } } }, "x-analysis-catalog": { "version": 1, "guide": "/llms.txt", "authorization": "Static contract only; requiredScopes are not the caller's effective grants or source readiness. Every request may return 401, 403 or 503.", "datasets": [ { "id": "customers", "operationId": "listAnalysisCustomers", "detailOperationId": "getAnalysisCustomer", "definitionVersion": "organization-metadata-v1", "requiredScopes": [ "customers.impact.read" ], "dimensions": [ "organizationId", "createdAt" ], "metrics": [], "coverage": "Current existing organizations only; deleted organizations are excluded. Activation facts require explicit include=activation on detail; null activation times do not establish never activated.", "pagination": { "mode": "live", "cursorField": "nextCursor", "maximumPageSize": 200, "stableSnapshot": false } }, { "id": "resourceUsage", "operationId": "queryResourceUsage", "definitionVersion": "resource-usage-v1", "requiredScopes": [ "customers.usage.read" ], "dimensions": [ "organizationId", "regionId", "boxId" ], "metrics": [ { "id": "computeVcpuSeconds", "unit": "vCPU-second", "meaning": "Allocated vCPU multiplied by overlapping seconds; not CPU utilization." }, { "id": "storageByteSeconds", "unit": "byte-second", "meaning": "Allocated disk bytes multiplied by overlapping seconds." }, { "id": "memoryGibSeconds", "unit": "GiB-second", "meaning": "Allocated GiB multiplied by overlapping seconds; not process memory usage." } ], "limits": { "maximumGroupBy": 2, "hourMaximumDays": 7, "dayMaximumDays": 90, "windowMaximumDays": 90, "maximumPageSize": 200, "maximumSourcePeriods": 200000, "maximumResultRows": 5000 }, "coverage": { "status": "unknown", "reason": "usage_events_not_backfilled", "missingRows": "unknown" }, "pagination": { "mode": "fixedSnapshot", "cursorField": "nextCursor", "lifetimeSeconds": 900, "repeatQuery": true, "expiredStatus": 410, "expiryAction": "Restart whole query and discard prior pages." } }, { "id": "billingUsage", "operationId": "queryBillingUsage", "definitionVersion": "billing-usage-v1", "requiredScopes": [ "customers.billing.read" ], "dimensions": [ "organizationId", "currency" ], "metrics": [ { "id": "settledUsageMinor", "unit": "currency-minor-unit", "meaning": "Settled usage by invoice creation time; not resource event time or card payments." }, { "id": "quotaCoveredMinor", "unit": "currency-minor-unit", "meaning": "Settlement funded by quota." }, { "id": "ordinaryWalletFundedMinor", "unit": "currency-minor-unit", "meaning": "Settlement funded by the ordinary wallet." } ], "limits": { "hourMaximumDays": 7, "dayMaximumDays": 90, "windowMaximumDays": 90, "maximumPageSize": 200, "maximumInvoices": 200000, "maximumResultRows": 5000 }, "coverage": { "status": "unknown", "reason": "usage_settlement_may_be_delayed", "missingRows": "unknown" }, "pagination": { "mode": "fixedSnapshot", "cursorField": "nextCursor", "lifetimeSeconds": 900, "repeatQuery": true, "expiredStatus": 410, "expiryAction": "Restart whole query and discard prior pages." } } ] } }