{ "openapi": "3.1.0", "info": { "title": "Spend Brake admin API", "version": "1.0.0", "description": "Keys, caps, kill switch, provider credentials, spend and events." }, "servers": [ { "url": "/" } ], "components": { "securitySchemes": { "bearer": { "type": "http", "scheme": "bearer", "description": "Admin API token (sbt_...)" } }, "schemas": { "KeyCheck": { "type": "object", "properties": { "apiRestricted": { "type": [ "boolean", "null" ] }, "ipRestricted": { "type": [ "boolean", "null" ] }, "valid": { "type": [ "boolean", "null" ] }, "warnings": { "type": "array", "items": { "type": "string" } } }, "required": [ "apiRestricted", "ipRestricted", "valid", "warnings" ] }, "ProviderCredential": { "type": "object", "properties": { "id": { "type": "string" }, "provider": { "type": "string" }, "name": { "type": "string" }, "hint": { "type": "string", "description": "Last 4 characters of the secret" }, "createdAt": { "type": "string" } }, "required": [ "id", "provider", "name", "hint", "createdAt" ] }, "Error": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": {} } }, "required": [ "error", "message" ] }, "CustomApi": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "origin": { "type": "string" }, "auth": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "header" ] }, "name": { "type": "string" }, "valuePrefix": { "type": "string" } }, "required": [ "type", "name", "valuePrefix" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "query" ] }, "name": { "type": "string" } }, "required": [ "type", "name" ] } ] }, "routes": { "type": "array", "items": { "type": "object", "properties": { "method": { "type": "string" }, "path": { "type": "string" }, "sku": { "type": "string" }, "pricing": { "$ref": "#/components/schemas/CustomApiPricing" } }, "required": [ "method", "path", "sku", "pricing" ] } }, "billed": { "type": "string", "enum": [ "2xx", "all" ] }, "timeoutBilled": { "type": "boolean" }, "proxyPath": { "type": "string", "description": "Call it at /" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "name", "origin", "auth", "routes", "billed", "timeoutBilled", "proxyPath", "createdAt", "updatedAt" ] }, "CustomApiPricing": { "anyOf": [ { "type": "object", "properties": { "model": { "type": "string", "enum": [ "perRequest" ] }, "usd": { "type": "string" } }, "required": [ "model", "usd" ] }, { "type": "object", "properties": { "model": { "type": "string", "enum": [ "reported" ] }, "header": { "type": "string" }, "jsonPath": { "type": "string" }, "usdPerUnit": { "type": "string" }, "maxPerRequest": { "type": "string" } }, "required": [ "model", "usdPerUnit", "maxPerRequest" ] } ] }, "VirtualKey": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "prefix": { "type": "string" }, "status": { "type": "string", "enum": [ "active", "revoked" ] }, "createdAt": { "type": "string" }, "expiresAt": { "type": [ "string", "null" ] }, "config": { "type": "object", "additionalProperties": {} } }, "required": [ "id", "name", "prefix", "status", "createdAt", "expiresAt", "config" ] }, "CreateKey": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "credentials": { "type": "object", "additionalProperties": { "type": "string", "pattern": "^[A-Za-z0-9_.-]{1,128}$" } }, "skus": { "type": [ "array", "null" ], "items": { "type": "string", "minLength": 1 } }, "env": { "type": [ "string", "null" ], "pattern": "^[A-Za-z0-9_.-]{1,128}$" }, "agentId": { "type": [ "string", "null" ], "pattern": "^[A-Za-z0-9_.-]{1,128}$" }, "sessionCapMicros": { "anyOf": [ { "type": "integer", "minimum": 0 }, { "type": "string", "pattern": "^\\d{1,16}$" }, { "type": "null" } ], "description": "Micro-dollars (1 USD = 1,000,000)", "example": 5000000 }, "loop": { "type": [ "object", "null" ], "properties": { "identical": { "type": "integer", "exclusiveMinimum": 0 }, "windowSec": { "type": "integer", "exclusiveMinimum": 0 }, "perMinute": { "type": "integer", "exclusiveMinimum": 0 }, "cooldownSec": { "type": "integer", "exclusiveMinimum": 0 } }, "required": [ "identical", "windowSec", "perMinute", "cooldownSec" ] }, "failOpenMicros": { "anyOf": [ { "type": "integer", "minimum": 0 }, { "type": "string", "pattern": "^\\d{1,16}$" }, { "type": "null" } ], "description": "Micro-dollars (1 USD = 1,000,000)", "example": 5000000 }, "allowedIps": { "type": [ "array", "null" ], "items": { "type": "string", "minLength": 1 } }, "expiresAt": { "type": [ "string", "null" ], "format": "date-time" }, "canMintSessions": { "type": "boolean" }, "countries": { "type": [ "array", "null" ], "items": { "type": "string", "pattern": "^[A-Z]{2}$" }, "maxItems": 250 }, "pumping": { "type": [ "object", "null" ], "properties": { "perNumberPerHour": { "type": "integer", "exclusiveMinimum": 0 }, "perPrefixPerHour": { "type": "integer", "exclusiveMinimum": 0 }, "cooldownSec": { "type": "integer", "exclusiveMinimum": 0 } }, "required": [ "perNumberPerHour", "perPrefixPerHour", "cooldownSec" ] } }, "required": [ "name", "credentials" ] }, "UpdateKey": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "credentials": { "type": "object", "additionalProperties": { "type": "string", "pattern": "^[A-Za-z0-9_.-]{1,128}$" } }, "skus": { "type": [ "array", "null" ], "items": { "type": "string", "minLength": 1 } }, "env": { "type": [ "string", "null" ], "pattern": "^[A-Za-z0-9_.-]{1,128}$" }, "agentId": { "type": [ "string", "null" ], "pattern": "^[A-Za-z0-9_.-]{1,128}$" }, "sessionCapMicros": { "anyOf": [ { "type": "integer", "minimum": 0 }, { "type": "string", "pattern": "^\\d{1,16}$" }, { "type": "null" } ], "description": "Micro-dollars (1 USD = 1,000,000)", "example": 5000000 }, "loop": { "type": [ "object", "null" ], "properties": { "identical": { "type": "integer", "exclusiveMinimum": 0 }, "windowSec": { "type": "integer", "exclusiveMinimum": 0 }, "perMinute": { "type": "integer", "exclusiveMinimum": 0 }, "cooldownSec": { "type": "integer", "exclusiveMinimum": 0 } }, "required": [ "identical", "windowSec", "perMinute", "cooldownSec" ] }, "failOpenMicros": { "anyOf": [ { "type": "integer", "minimum": 0 }, { "type": "string", "pattern": "^\\d{1,16}$" }, { "type": "null" } ], "description": "Micro-dollars (1 USD = 1,000,000)", "example": 5000000 }, "allowedIps": { "type": [ "array", "null" ], "items": { "type": "string", "minLength": 1 } }, "expiresAt": { "type": [ "string", "null" ], "format": "date-time" }, "canMintSessions": { "type": "boolean" }, "countries": { "type": [ "array", "null" ], "items": { "type": "string", "pattern": "^[A-Z]{2}$" }, "maxItems": 250 }, "pumping": { "type": [ "object", "null" ], "properties": { "perNumberPerHour": { "type": "integer", "exclusiveMinimum": 0 }, "perPrefixPerHour": { "type": "integer", "exclusiveMinimum": 0 }, "cooldownSec": { "type": "integer", "exclusiveMinimum": 0 } }, "required": [ "perNumberPerHour", "perPrefixPerHour", "cooldownSec" ] } } }, "Cap": { "type": "object", "properties": { "scope": { "type": "string" }, "kind": { "type": "string", "enum": [ "d", "m" ] }, "hard": { "type": [ "number", "null" ] }, "soft": { "type": [ "number", "null" ] }, "version": { "type": "number" } }, "required": [ "scope", "kind", "hard", "soft", "version" ] }, "PendingCapChange": { "type": "object", "properties": { "scope": { "type": "string" }, "kind": { "type": "string", "enum": [ "d", "m" ] }, "approvalId": { "type": "string" } }, "required": [ "scope", "kind", "approvalId" ] }, "KillSet": { "type": "object", "properties": { "killed": { "type": "array", "items": { "type": "string" } } }, "required": [ "killed" ] }, "ApiToken": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "role": { "type": "string", "enum": [ "viewer", "admin", "owner" ] }, "createdAt": { "type": "string" }, "expiresAt": { "type": [ "string", "null" ] }, "lastUsedAt": { "type": [ "string", "null" ] } }, "required": [ "id", "name", "role", "createdAt", "expiresAt", "lastUsedAt" ] }, "Org": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "timeZone": { "type": "string" }, "settings": { "type": "object", "additionalProperties": {} } }, "required": [ "id", "name", "timeZone", "settings" ] }, "Webhook": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "preset": { "type": "string", "enum": [ "raw", "slack", "discord", "teams" ] }, "urlHint": { "type": "string" }, "events": { "type": "array", "items": { "type": "string" } }, "createdAt": { "type": "string" } }, "required": [ "id", "name", "preset", "urlHint", "events", "createdAt" ] }, "Session": { "type": "object", "properties": { "sessionId": { "type": "string" }, "keyId": { "type": "string" }, "token": { "type": "string" }, "agentId": { "type": "string" }, "budgetMicros": { "type": "number" }, "dayBudgetMicros": { "type": "number" }, "expiresAt": { "type": "string" } }, "required": [ "sessionId", "keyId", "token", "agentId", "budgetMicros", "dayBudgetMicros", "expiresAt" ] }, "SessionEnd": { "type": "object", "properties": { "sessionId": { "type": "string" }, "keyId": { "type": "string" }, "spentMicros": { "type": "number" }, "heldMicros": { "type": "number" } }, "required": [ "sessionId", "keyId", "spentMicros", "heldMicros" ] } }, "parameters": {} }, "paths": { "/v1/providers/credentials": { "post": { "summary": "Add an encrypted provider key (admin)", "tags": [ "Providers" ], "security": [ { "bearer": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "provider": { "type": "string", "pattern": "^[A-Za-z0-9_.-]{1,128}$" }, "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "secret": { "type": "string", "minLength": 1, "maxLength": 4096, "description": "Never returned or logged" } }, "required": [ "provider", "name", "secret" ] } } } }, "responses": { "201": { "description": "OK", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ProviderCredential" }, { "type": "object", "properties": { "check": { "$ref": "#/components/schemas/KeyCheck" }, "reboundKeys": { "type": "array", "items": { "type": "string" }, "description": "Keys that were bound to a deleted credential of this provider and now use this one" } }, "required": [ "reboundKeys" ] } ] } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Role too low", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "get": { "summary": "List provider keys (no secrets) (viewer)", "tags": [ "Providers" ], "security": [ { "bearer": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/ProviderCredential" } } }, "required": [ "items" ] } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Role too low", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/providers/credentials/{id}": { "delete": { "summary": "Delete a provider key (keys that use it move to another key of the provider) (admin)", "tags": [ "Providers" ], "security": [ { "bearer": [] } ], "parameters": [ { "schema": { "type": "string", "pattern": "^[A-Za-z0-9_.-]{1,128}$" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "deleted": { "type": "boolean", "enum": [ true ] }, "reboundKeys": { "type": "array", "items": { "type": "string" }, "description": "Keys moved to another credential" } }, "required": [ "id", "deleted", "reboundKeys" ] } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Role too low", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/custom-apis": { "get": { "summary": "List the org's custom APIs (viewer)", "tags": [ "Custom APIs" ], "security": [ { "bearer": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/CustomApi" } } }, "required": [ "items" ] } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Role too low", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "summary": "Add a custom API (an API you price yourself) (admin)", "tags": [ "Custom APIs" ], "security": [ { "bearer": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[A-Za-z0-9_.-]{1,128}$" }, "auth": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "header" ] }, "name": { "type": "string", "pattern": "^[A-Za-z0-9!#$%&'*+.^_`|~-]{1,128}$" }, "valuePrefix": { "type": "string", "maxLength": 64, "default": "" } }, "required": [ "type", "name" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "query" ] }, "name": { "type": "string", "minLength": 1, "maxLength": 128 } }, "required": [ "type", "name" ], "additionalProperties": false } ] }, "billed": { "type": "string", "enum": [ "2xx", "all" ], "default": "2xx" }, "timeoutBilled": { "type": "boolean", "default": true }, "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "origin": { "type": "string", "maxLength": 2048 }, "routes": { "type": "array", "items": { "type": "object", "properties": { "method": { "type": "string", "pattern": "^(\\*|[A-Za-z]{1,16})$", "default": "*" }, "path": { "type": "string", "maxLength": 512 }, "sku": { "type": "string", "pattern": "^[A-Za-z0-9_.-]{1,128}$" }, "pricing": { "oneOf": [ { "type": "object", "properties": { "model": { "type": "string", "enum": [ "perRequest" ] }, "usd": { "type": "string", "pattern": "^\\d{1,9}(\\.\\d{1,6})?$" } }, "required": [ "model", "usd" ], "additionalProperties": false }, { "type": "object", "properties": { "model": { "type": "string", "enum": [ "reported" ] }, "header": { "type": "string", "pattern": "^[A-Za-z0-9!#$%&'*+.^_`|~-]{1,128}$" }, "jsonPath": { "type": "string", "pattern": "^[A-Za-z0-9_$-]{1,64}(\\.[A-Za-z0-9_$-]{1,64}){0,15}$" }, "usdPerUnit": { "type": "string", "pattern": "^\\d{1,9}(\\.\\d{1,12})?$" }, "maxPerRequest": { "type": "string", "pattern": "^\\d{1,9}(\\.\\d{1,6})?$" } }, "required": [ "model", "usdPerUnit", "maxPerRequest" ], "additionalProperties": false } ] }, "pricePerRequest": { "type": "string", "pattern": "^\\d{1,9}(\\.\\d{1,6})?$" } }, "required": [ "path", "sku" ], "additionalProperties": false }, "minItems": 1, "maxItems": 100 } }, "required": [ "id", "auth", "name", "origin", "routes" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomApi" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Role too low", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/custom-apis/{id}": { "get": { "summary": "Get a custom API (viewer)", "tags": [ "Custom APIs" ], "security": [ { "bearer": [] } ], "parameters": [ { "schema": { "type": "string", "pattern": "^[A-Za-z0-9_.-]{1,128}$" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomApi" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Role too low", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "put": { "summary": "Replace a custom API definition (its id stays) (admin)", "tags": [ "Custom APIs" ], "security": [ { "bearer": [] } ], "parameters": [ { "schema": { "type": "string", "pattern": "^[A-Za-z0-9_.-]{1,128}$" }, "required": true, "name": "id", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "auth": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "header" ] }, "name": { "type": "string", "pattern": "^[A-Za-z0-9!#$%&'*+.^_`|~-]{1,128}$" }, "valuePrefix": { "type": "string", "maxLength": 64, "default": "" } }, "required": [ "type", "name" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "query" ] }, "name": { "type": "string", "minLength": 1, "maxLength": 128 } }, "required": [ "type", "name" ], "additionalProperties": false } ] }, "billed": { "type": "string", "enum": [ "2xx", "all" ], "default": "2xx" }, "timeoutBilled": { "type": "boolean", "default": true }, "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "origin": { "type": "string", "maxLength": 2048 }, "routes": { "type": "array", "items": { "type": "object", "properties": { "method": { "type": "string", "pattern": "^(\\*|[A-Za-z]{1,16})$", "default": "*" }, "path": { "type": "string", "maxLength": 512 }, "sku": { "type": "string", "pattern": "^[A-Za-z0-9_.-]{1,128}$" }, "pricing": { "oneOf": [ { "type": "object", "properties": { "model": { "type": "string", "enum": [ "perRequest" ] }, "usd": { "type": "string", "pattern": "^\\d{1,9}(\\.\\d{1,6})?$" } }, "required": [ "model", "usd" ], "additionalProperties": false }, { "type": "object", "properties": { "model": { "type": "string", "enum": [ "reported" ] }, "header": { "type": "string", "pattern": "^[A-Za-z0-9!#$%&'*+.^_`|~-]{1,128}$" }, "jsonPath": { "type": "string", "pattern": "^[A-Za-z0-9_$-]{1,64}(\\.[A-Za-z0-9_$-]{1,64}){0,15}$" }, "usdPerUnit": { "type": "string", "pattern": "^\\d{1,9}(\\.\\d{1,12})?$" }, "maxPerRequest": { "type": "string", "pattern": "^\\d{1,9}(\\.\\d{1,6})?$" } }, "required": [ "model", "usdPerUnit", "maxPerRequest" ], "additionalProperties": false } ] }, "pricePerRequest": { "type": "string", "pattern": "^\\d{1,9}(\\.\\d{1,6})?$" } }, "required": [ "path", "sku" ], "additionalProperties": false }, "minItems": 1, "maxItems": 100 } }, "required": [ "auth", "name", "origin", "routes" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomApi" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Role too low", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "summary": "Delete a custom API and its provider keys (refused while Spend Brake keys use it) (admin)", "tags": [ "Custom APIs" ], "security": [ { "bearer": [] } ], "parameters": [ { "schema": { "type": "string", "pattern": "^[A-Za-z0-9_.-]{1,128}$" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "deleted": { "type": "boolean", "enum": [ true ] }, "deletedCredentials": { "type": "array", "items": { "type": "string" }, "description": "Provider keys stored for this custom API, deleted with it" } }, "required": [ "id", "deleted", "deletedCredentials" ] } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Role too low", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/keys": { "post": { "summary": "Create a virtual key (the token is shown once) (admin)", "tags": [ "Keys" ], "security": [ { "bearer": [] } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateKey" } } } }, "responses": { "201": { "description": "OK", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/VirtualKey" }, { "type": "object", "properties": { "token": { "type": "string" } }, "required": [ "token" ] } ] } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Role too low", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "get": { "summary": "List virtual keys (viewer)", "tags": [ "Keys" ], "security": [ { "bearer": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/VirtualKey" } } }, "required": [ "items" ] } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Role too low", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/keys/{id}": { "get": { "summary": "Get a virtual key (viewer)", "tags": [ "Keys" ], "security": [ { "bearer": [] } ], "parameters": [ { "schema": { "type": "string", "pattern": "^[A-Za-z0-9_.-]{1,128}$" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VirtualKey" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Role too low", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "summary": "Update a virtual key (admin)", "tags": [ "Keys" ], "security": [ { "bearer": [] } ], "parameters": [ { "schema": { "type": "string", "pattern": "^[A-Za-z0-9_.-]{1,128}$" }, "required": true, "name": "id", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateKey" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VirtualKey" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Role too low", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "summary": "Revoke a virtual key (admin)", "tags": [ "Keys" ], "security": [ { "bearer": [] } ], "parameters": [ { "schema": { "type": "string", "pattern": "^[A-Za-z0-9_.-]{1,128}$" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VirtualKey" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Role too low", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/caps/{scope}": { "put": { "summary": "Set hard / soft caps for a scope, per day and/or month (null removes a limit) (admin)", "tags": [ "Caps" ], "security": [ { "bearer": [] } ], "parameters": [ { "schema": { "type": "string", "pattern": "^(org|key:[A-Za-z0-9_.-]{1,128}|sku:[A-Za-z0-9_.-]{1,128}:[A-Za-z0-9_.-]{1,128}|env:[A-Za-z0-9_.-]{1,128}|sess:[A-Za-z0-9_.-]{1,128}|agent:[A-Za-z0-9_.-]{1,128})$" }, "required": true, "name": "scope", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "day": { "type": "object", "properties": { "hard": { "anyOf": [ { "type": "integer", "minimum": 0 }, { "type": "string", "pattern": "^\\d{1,16}$" }, { "type": "null" } ], "description": "Micro-dollars (1 USD = 1,000,000)", "example": 5000000 }, "soft": { "anyOf": [ { "type": "integer", "minimum": 0 }, { "type": "string", "pattern": "^\\d{1,16}$" }, { "type": "null" } ], "description": "Micro-dollars (1 USD = 1,000,000)", "example": 5000000 } }, "required": [ "hard" ] }, "month": { "type": "object", "properties": { "hard": { "anyOf": [ { "type": "integer", "minimum": 0 }, { "type": "string", "pattern": "^\\d{1,16}$" }, { "type": "null" } ], "description": "Micro-dollars (1 USD = 1,000,000)", "example": 5000000 }, "soft": { "anyOf": [ { "type": "integer", "minimum": 0 }, { "type": "string", "pattern": "^\\d{1,16}$" }, { "type": "null" } ], "description": "Micro-dollars (1 USD = 1,000,000)", "example": 5000000 } }, "required": [ "hard" ] } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Cap" } }, "pending": { "type": "array", "items": { "$ref": "#/components/schemas/PendingCapChange" } } }, "required": [ "items" ] } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Role too low", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "summary": "Remove the caps of a scope (admin)", "tags": [ "Caps" ], "security": [ { "bearer": [] } ], "parameters": [ { "schema": { "type": "string", "pattern": "^(org|key:[A-Za-z0-9_.-]{1,128}|sku:[A-Za-z0-9_.-]{1,128}:[A-Za-z0-9_.-]{1,128}|env:[A-Za-z0-9_.-]{1,128}|sess:[A-Za-z0-9_.-]{1,128}|agent:[A-Za-z0-9_.-]{1,128})$" }, "required": true, "name": "scope", "in": "path" }, { "schema": { "type": "string", "enum": [ "d", "m" ] }, "required": false, "name": "kind", "in": "query" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "scope": { "type": "string" }, "deleted": { "type": "array", "items": { "type": "string", "enum": [ "d", "m" ] } }, "pending": { "type": "array", "items": { "$ref": "#/components/schemas/PendingCapChange" } } }, "required": [ "scope", "deleted" ] } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Role too low", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/caps": { "get": { "summary": "List caps (viewer)", "tags": [ "Caps" ], "security": [ { "bearer": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Cap" } } }, "required": [ "items" ] } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Role too low", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/kill": { "post": { "summary": "Stop all spend for an org, provider, key or session (immediate) (admin)", "tags": [ "Kill switch" ], "security": [ { "bearer": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "target": { "type": "string", "pattern": "^(org|key:[A-Za-z0-9_.-]{1,128}|prov:[A-Za-z0-9_.-]{1,128}|sess:[A-Za-z0-9_.-]{1,128})$" }, "reason": { "type": "string", "maxLength": 500 } }, "required": [ "target" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KillSet" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Role too low", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/unkill": { "post": { "summary": "Lift a kill (admin)", "tags": [ "Kill switch" ], "security": [ { "bearer": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "target": { "type": "string", "pattern": "^(org|key:[A-Za-z0-9_.-]{1,128}|prov:[A-Za-z0-9_.-]{1,128}|sess:[A-Za-z0-9_.-]{1,128})$" }, "reason": { "type": "string", "maxLength": 500 } }, "required": [ "target" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KillSet" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Role too low", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/keys/{id}/resume": { "post": { "summary": "Resume a key paused by the loop breaker (close its circuit before the cooldown ends and reset its repeat counts) (admin)", "tags": [ "Kill switch" ], "security": [ { "bearer": [] } ], "parameters": [ { "schema": { "type": "string", "pattern": "^[A-Za-z0-9_.-]{1,128}$" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "keyId": { "type": "string" }, "resumed": { "type": "boolean", "enum": [ true ] } }, "required": [ "keyId", "resumed" ] } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Role too low", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/status": { "get": { "summary": "Live remaining budget per scope (from Valkey) (viewer)", "tags": [ "Spend" ], "security": [ { "bearer": [] } ], "parameters": [ { "schema": { "anyOf": [ { "type": "string", "pattern": "^(org|key:[A-Za-z0-9_.-]{1,128}|sku:[A-Za-z0-9_.-]{1,128}:[A-Za-z0-9_.-]{1,128}|env:[A-Za-z0-9_.-]{1,128}|sess:[A-Za-z0-9_.-]{1,128}|agent:[A-Za-z0-9_.-]{1,128})$" }, { "type": "array", "items": { "type": "string", "pattern": "^(org|key:[A-Za-z0-9_.-]{1,128}|sku:[A-Za-z0-9_.-]{1,128}:[A-Za-z0-9_.-]{1,128}|env:[A-Za-z0-9_.-]{1,128}|sess:[A-Za-z0-9_.-]{1,128}|agent:[A-Za-z0-9_.-]{1,128})$" } } ], "description": "Defaults to the org and every active key" }, "required": false, "description": "Defaults to the org and every active key", "name": "scope", "in": "query" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "killed": { "type": "array", "items": { "type": "string" } }, "paused": { "type": "array", "items": { "type": "object", "properties": { "keyId": { "type": "string" }, "retryAfterSec": { "type": "number" }, "reason": { "type": "string", "enum": [ "loop", "pumping" ], "description": "What opened the circuit: the loop breaker (repeated requests) or the SMS pumping guard" } }, "required": [ "keyId", "retryAfterSec", "reason" ] }, "description": "Keys refused for every provider (429 loop_detected) until their circuit closes" }, "scopes": { "type": "array", "items": { "type": "object", "properties": { "scope": { "type": "string" }, "window": { "type": "string" }, "spent": { "type": "number" }, "held": { "type": "number" }, "hard": { "type": [ "number", "null" ] }, "soft": { "type": [ "number", "null" ] }, "remaining": { "type": [ "number", "null" ] } }, "required": [ "scope", "window", "spent", "held", "hard", "soft", "remaining" ] } } }, "required": [ "killed", "paused", "scopes" ] } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Role too low", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/spend": { "get": { "summary": "Spend from the ledger, grouped by key, SKU, day, ... (viewer)", "tags": [ "Spend" ], "security": [ { "bearer": [] } ], "parameters": [ { "schema": { "type": "string", "default": "day" }, "required": false, "name": "groupBy", "in": "query" }, { "schema": { "type": "string", "format": "date-time" }, "required": false, "name": "from", "in": "query" }, { "schema": { "type": "string", "format": "date-time" }, "required": false, "name": "to", "in": "query" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "null" } ] } } } }, "required": [ "items" ] } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Role too low", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/events": { "get": { "summary": "Usage events (newest first), or the audit log with source=audit (viewer)", "tags": [ "Events" ], "security": [ { "bearer": [] } ], "parameters": [ { "schema": { "type": "string", "enum": [ "usage", "audit" ], "default": "usage" }, "required": false, "name": "source", "in": "query" }, { "schema": { "type": "string", "maxLength": 64 }, "required": false, "name": "type", "in": "query" }, { "schema": { "type": "string", "pattern": "^[A-Za-z0-9_.-]{1,128}$" }, "required": false, "name": "keyId", "in": "query" }, { "schema": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "string", "format": "date" } ], "description": "Inclusive lower bound on the event time: ISO 8601 with Z or an offset, or a date (00:00 UTC).", "example": "2026-10-01" }, "required": false, "description": "Inclusive lower bound on the event time: ISO 8601 with Z or an offset, or a date (00:00 UTC).", "name": "from", "in": "query" }, { "schema": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "string", "format": "date" } ], "description": "Exclusive upper bound on the event time: ISO 8601 with Z or an offset, or a date (through the end of that day, UTC).", "example": "2026-10-31T18:00:00+02:00" }, "required": false, "description": "Exclusive upper bound on the event time: ISO 8601 with Z or an offset, or a date (through the end of that day, UTC).", "name": "to", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 500, "default": 100 }, "required": false, "name": "limit", "in": "query" }, { "schema": { "type": "string", "maxLength": 500 }, "required": false, "name": "cursor", "in": "query" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "additionalProperties": {} } }, "nextCursor": { "type": [ "string", "null" ] } }, "required": [ "items", "nextCursor" ] } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Role too low", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/events.csv": { "get": { "summary": "The events of /v1/events as a CSV download, newest first (at most 100,000 rows; X-Brake-Truncated says when more matched) (viewer)", "tags": [ "Events" ], "security": [ { "bearer": [] } ], "parameters": [ { "schema": { "type": "string", "enum": [ "usage", "audit" ], "default": "usage" }, "required": false, "name": "source", "in": "query" }, { "schema": { "type": "string", "maxLength": 64 }, "required": false, "name": "type", "in": "query" }, { "schema": { "type": "string", "pattern": "^[A-Za-z0-9_.-]{1,128}$" }, "required": false, "name": "keyId", "in": "query" }, { "schema": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "string", "format": "date" } ], "description": "Inclusive lower bound on the event time: ISO 8601 with Z or an offset, or a date (00:00 UTC).", "example": "2026-10-01" }, "required": false, "description": "Inclusive lower bound on the event time: ISO 8601 with Z or an offset, or a date (00:00 UTC).", "name": "from", "in": "query" }, { "schema": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "string", "format": "date" } ], "description": "Exclusive upper bound on the event time: ISO 8601 with Z or an offset, or a date (through the end of that day, UTC).", "example": "2026-10-31T18:00:00+02:00" }, "required": false, "description": "Exclusive upper bound on the event time: ISO 8601 with Z or an offset, or a date (through the end of that day, UTC).", "name": "to", "in": "query" } ], "responses": { "200": { "description": "OK", "content": { "text/csv": { "schema": { "type": "string" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Role too low", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/tokens": { "post": { "summary": "Create an admin API token (shown once) (owner)", "tags": [ "Admin" ], "security": [ { "bearer": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "role": { "type": "string", "enum": [ "viewer", "admin", "owner" ] }, "expiresAt": { "type": "string", "format": "date-time" } }, "required": [ "name", "role" ] } } } }, "responses": { "201": { "description": "OK", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiToken" }, { "type": "object", "properties": { "token": { "type": "string" } }, "required": [ "token" ] } ] } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Role too low", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "get": { "summary": "List admin API tokens (owner)", "tags": [ "Admin" ], "security": [ { "bearer": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/ApiToken" } } }, "required": [ "items" ] } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Role too low", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/tokens/{id}": { "delete": { "summary": "Revoke an admin API token (owner)", "tags": [ "Admin" ], "security": [ { "bearer": [] } ], "parameters": [ { "schema": { "type": "string", "pattern": "^[A-Za-z0-9_.-]{1,128}$" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiToken" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Role too low", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/org": { "get": { "summary": "Get org settings (viewer)", "tags": [ "Admin" ], "security": [ { "bearer": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Org" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Role too low", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "put": { "summary": "Update org settings (time zone, provider pricing policy, loop policy) (owner)", "tags": [ "Admin" ], "security": [ { "bearer": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "timeZone": { "type": "string" }, "providers": { "type": "object", "additionalProperties": { "type": "object", "properties": { "trustFreeTier": { "type": "boolean", "default": false }, "unpricedPolicy": { "type": "string", "enum": [ "deny", "allow-with-default-price" ], "default": "deny" }, "defaultPriceMicros": { "anyOf": [ { "type": "integer", "minimum": 0 }, { "type": "string", "pattern": "^\\d{1,16}$" } ], "description": "Micro-dollars (1 USD = 1,000,000)", "example": 5000000 } } } }, "alertEmail": { "type": [ "string", "null" ], "format": "email" }, "requireLoginForRaise": { "type": "boolean" }, "loop": { "type": "object", "properties": { "identical": { "type": "integer", "exclusiveMinimum": 0 }, "windowSec": { "type": "integer", "exclusiveMinimum": 0 }, "perMinute": { "type": "integer", "exclusiveMinimum": 0 }, "cooldownSec": { "type": "integer", "exclusiveMinimum": 0 } }, "required": [ "identical", "windowSec", "perMinute", "cooldownSec" ] } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Org" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Role too low", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/webhooks": { "post": { "summary": "Add an alert webhook (the signing secret is shown once) (admin)", "tags": [ "Alerts" ], "security": [ { "bearer": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "url": { "type": "string", "maxLength": 2048, "format": "uri" }, "preset": { "type": "string", "enum": [ "raw", "slack", "discord", "teams" ], "default": "raw" }, "events": { "type": "array", "items": { "type": "string", "enum": [ "threshold", "blocked", "loop", "catalog_underpriced", "upstream_key_error", "reservations_expired", "reconcile_drift" ] }, "default": [] }, "secret": { "type": "string", "minLength": 16, "maxLength": 200 } }, "required": [ "name", "url" ] } } } }, "responses": { "201": { "description": "OK", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Webhook" }, { "type": "object", "properties": { "secret": { "type": "string" } }, "required": [ "secret" ] } ] } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Role too low", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "get": { "summary": "List alert webhooks (viewer)", "tags": [ "Alerts" ], "security": [ { "bearer": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Webhook" } } }, "required": [ "items" ] } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Role too low", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/webhooks/{id}": { "delete": { "summary": "Delete an alert webhook (admin)", "tags": [ "Alerts" ], "security": [ { "bearer": [] } ], "parameters": [ { "schema": { "type": "string", "pattern": "^[A-Za-z0-9_.-]{1,128}$" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Webhook" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Role too low", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/webhooks/{id}/deliveries": { "get": { "summary": "Delivery log of a webhook (newest first) (viewer)", "tags": [ "Alerts" ], "security": [ { "bearer": [] } ], "parameters": [ { "schema": { "type": "string", "pattern": "^[A-Za-z0-9_.-]{1,128}$" }, "required": true, "name": "id", "in": "path" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 500, "default": 100 }, "required": false, "name": "limit", "in": "query" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "alertId": { "type": "string" }, "type": { "type": "string" }, "attempt": { "type": "number" }, "ok": { "type": "boolean" }, "httpStatus": { "type": [ "number", "null" ] }, "error": { "type": [ "string", "null" ] }, "at": { "type": "string" } }, "required": [ "alertId", "type", "attempt", "ok", "httpStatus", "error", "at" ] } } }, "required": [ "items" ] } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Role too low", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/actions/execute": { "post": { "summary": "Run an alert action link (kill, raise, mute, reset circuit); the token is the credential", "tags": [ "Alerts" ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string", "minLength": 10, "maxLength": 4096 }, "amount": { "type": "integer", "exclusiveMinimum": 0 } }, "required": [ "token" ] } } } }, "responses": { "200": { "description": "Done", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [ true ] }, "action": { "type": "string" }, "target": { "type": "string" } }, "required": [ "ok", "action", "target" ], "additionalProperties": {} } } } }, "409": { "description": "Link already used", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Link expired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/sessions": { "post": { "summary": "Mint a session key (admin token, or X-Brake-Key of a parent key with canMintSessions)", "tags": [ "Sessions" ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "parentKeyId": { "type": "string", "pattern": "^[A-Za-z0-9_.-]{1,128}$" }, "budgetMicros": { "anyOf": [ { "type": "integer", "minimum": 0 }, { "type": "string", "pattern": "^\\d{1,16}$" } ], "description": "Micro-dollars (1 USD = 1,000,000)", "example": 5000000 }, "dayBudgetMicros": { "anyOf": [ { "type": "integer", "minimum": 0 }, { "type": "string", "pattern": "^\\d{1,16}$" } ], "description": "Micro-dollars (1 USD = 1,000,000)", "example": 5000000 }, "agentId": { "type": "string", "pattern": "^[A-Za-z0-9_.-]{1,128}$" }, "ttlSec": { "type": "integer", "minimum": 60, "maximum": 604800, "default": 43200 }, "name": { "type": "string", "maxLength": 200 } } } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Session" } } } }, "403": { "description": "Not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/sessions/{keyId}": { "delete": { "summary": "End a session: revoke its key and report its spend (admin, parent or the session key)", "tags": [ "Sessions" ], "parameters": [ { "schema": { "type": "string", "pattern": "^[A-Za-z0-9_.-]{1,128}$" }, "required": true, "name": "keyId", "in": "path" } ], "responses": { "200": { "description": "Ended", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SessionEnd" } } } } } } }, "/v1/setup": { "post": { "summary": "First run: create the org and its owner token (needs BRAKE_SETUP_TOKEN)", "tags": [ "Admin" ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "setupToken": { "type": "string", "minLength": 1, "maxLength": 500 }, "orgId": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,64}$" }, "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "timeZone": { "type": "string", "default": "UTC" } }, "required": [ "setupToken", "orgId", "name" ] } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "orgId": { "type": "string" }, "ownerToken": { "type": "string" } }, "required": [ "orgId", "ownerToken" ] } } } }, "409": { "description": "Already set up", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/me": { "get": { "summary": "Remaining budget of the calling virtual key (X-Brake-Key)", "tags": [ "Sessions" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "keyId": { "type": "string" }, "sessionId": { "type": [ "string", "null" ] }, "killed": { "type": "boolean" }, "scopes": { "type": "array", "items": { "type": "object", "properties": { "scope": { "type": "string" }, "window": { "type": "string" }, "spent": { "type": "number" }, "held": { "type": "number" }, "hard": { "type": [ "number", "null" ] }, "remaining": { "type": [ "number", "null" ] } }, "required": [ "scope", "window", "spent", "held", "hard", "remaining" ] } } }, "required": [ "keyId", "sessionId", "killed", "scopes" ] } } } } } } }, "/v1/estimates/migration": { "post": { "summary": "Price the last N days of Google Maps usage on Geoapify, Stadia Maps, Open Places API, Mapbox and HERE (viewer)", "tags": [ "Spend" ], "security": [ { "bearer": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "days": { "type": "integer", "minimum": 1, "maximum": 90, "default": 30 } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": {}, "additionalProperties": {} } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Role too low", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/auth/options": { "get": { "summary": "How to sign in here (public)", "tags": [ "Auth" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "emailSignIn": { "type": "boolean" }, "signup": { "type": "boolean" }, "proxyUrl": { "type": [ "string", "null" ] }, "egressIps": { "type": "array", "items": { "type": "string" } } }, "required": [ "emailSignIn", "signup", "proxyUrl", "egressIps" ] } } } } } } }, "/v1/auth/email": { "post": { "summary": "Email a sign-in link (public; works once, for 15 minutes)", "tags": [ "Auth" ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string" } }, "required": [ "email" ] } } } }, "responses": { "202": { "description": "Sent if the address belongs to anyone", "content": { "application/json": { "schema": { "type": "object", "properties": {} } } } }, "404": { "description": "Email sign-in is off", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/auth/email/verify": { "post": { "summary": "Spend an emailed sign-in link for a token (public)", "tags": [ "Auth" ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "maxLength": 100 } }, "required": [ "code" ] } } } }, "responses": { "200": { "description": "Signed in", "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string" }, "orgId": { "type": "string" }, "email": { "type": "string" }, "role": { "type": "string" }, "expiresAt": { "type": "string" } }, "required": [ "token", "orgId", "email", "role", "expiresAt" ] } } } }, "400": { "description": "Link unknown, used or expired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/auth/session": { "get": { "summary": "The calling token: its org and role (the dashboard shows only what the role can do) (viewer)", "tags": [ "Auth" ], "security": [ { "bearer": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "orgId": { "type": "string" }, "role": { "type": "string", "enum": [ "viewer", "admin", "owner" ] }, "actor": { "type": "string" }, "signIn": { "type": [ "string", "null" ], "enum": [ "sso", "email", null ] } }, "required": [ "orgId", "role", "actor", "signIn" ] } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Role too low", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "summary": "Sign out: end the calling session (tokens issued at sign-in only) (viewer)", "tags": [ "Auth" ], "security": [ { "bearer": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "revoked": { "type": "boolean" } }, "required": [ "revoked" ] } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Role too low", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/users": { "get": { "summary": "People in the org (admin)", "tags": [ "Team" ], "security": [ { "bearer": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "email": { "type": "string" }, "role": { "type": "string", "enum": [ "viewer", "admin", "owner" ] }, "createdAt": { "type": "string" } }, "required": [ "id", "email", "role", "createdAt" ] } } }, "required": [ "items" ] } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Role too low", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "summary": "Invite a person (emails them a sign-in link when email sign-in is on) (owner)", "tags": [ "Team" ], "security": [ { "bearer": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string" }, "role": { "type": "string", "enum": [ "viewer", "admin", "owner" ] } }, "required": [ "email", "role" ] } } } }, "responses": { "201": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "email": { "type": "string" }, "role": { "type": "string", "enum": [ "viewer", "admin", "owner" ] }, "createdAt": { "type": "string" }, "invited": { "type": "boolean" } }, "required": [ "id", "email", "role", "createdAt", "invited" ] } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Role too low", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/users/{id}": { "patch": { "summary": "Change a person's role (their current sessions end) (owner)", "tags": [ "Team" ], "security": [ { "bearer": [] } ], "parameters": [ { "schema": { "type": "string", "pattern": "^[A-Za-z0-9_.-]{1,128}$" }, "required": true, "name": "id", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "role": { "type": "string", "enum": [ "viewer", "admin", "owner" ] } }, "required": [ "role" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "email": { "type": "string" }, "role": { "type": "string", "enum": [ "viewer", "admin", "owner" ] }, "createdAt": { "type": "string" } }, "required": [ "id", "email", "role", "createdAt" ] } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Role too low", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "summary": "Remove a person from the org (their sessions end) (owner)", "tags": [ "Team" ], "security": [ { "bearer": [] } ], "parameters": [ { "schema": { "type": "string", "pattern": "^[A-Za-z0-9_.-]{1,128}$" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "email": { "type": "string" }, "role": { "type": "string", "enum": [ "viewer", "admin", "owner" ] }, "createdAt": { "type": "string" } }, "required": [ "id", "email", "role", "createdAt" ] } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Role too low", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/metrics": { "get": { "summary": "The org's calls, cost, latency and budget in the Prometheus text format (viewer)", "tags": [ "Telemetry" ], "security": [ { "bearer": [] } ], "responses": { "200": { "description": "OK", "content": { "text/plain": { "schema": { "type": "string" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Role too low", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/telemetry/otlp": { "get": { "summary": "Where calls go as OpenTelemetry spans (null when nowhere) (viewer)", "tags": [ "Telemetry" ], "security": [ { "bearer": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "otlp": { "type": [ "object", "null" ], "properties": { "endpoint": { "type": "string" }, "headerNames": { "type": "array", "items": { "type": "string" } }, "enabled": { "type": "boolean" }, "planAllows": { "type": "boolean", "description": "False when the org's plan no longer includes export: nothing is sent" }, "lastSuccessAt": { "type": [ "string", "null" ] }, "lastErrorAt": { "type": [ "string", "null" ] }, "lastError": { "type": [ "string", "null" ] }, "queued": { "type": "number" } }, "required": [ "endpoint", "headerNames", "enabled", "planAllows", "lastSuccessAt", "lastErrorAt", "lastError", "queued" ] } }, "required": [ "otlp" ] } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Role too low", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "put": { "summary": "Send every call as a span to the org's OTLP/HTTP collector (admin)", "tags": [ "Telemetry" ], "security": [ { "bearer": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "endpoint": { "type": "string", "maxLength": 500, "format": "uri" }, "headers": { "type": "object", "additionalProperties": { "type": "string", "minLength": 1, "maxLength": 2000 } }, "enabled": { "type": "boolean", "default": true } }, "required": [ "endpoint" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "endpoint": { "type": "string" }, "headerNames": { "type": "array", "items": { "type": "string" } }, "enabled": { "type": "boolean" }, "planAllows": { "type": "boolean", "description": "False when the org's plan no longer includes export: nothing is sent" }, "lastSuccessAt": { "type": [ "string", "null" ] }, "lastErrorAt": { "type": [ "string", "null" ] }, "lastError": { "type": [ "string", "null" ] }, "queued": { "type": "number" } }, "required": [ "endpoint", "headerNames", "enabled", "planAllows", "lastSuccessAt", "lastErrorAt", "lastError", "queued" ] } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Role too low", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "summary": "Stop sending spans (and drop the ones waiting) (admin)", "tags": [ "Telemetry" ], "security": [ { "bearer": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "deleted": { "type": "boolean" } }, "required": [ "deleted" ] } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Role too low", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/telemetry/otlp/test": { "post": { "summary": "Send one test span to the configured collector now (admin)", "tags": [ "Telemetry" ], "security": [ { "bearer": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "status": { "type": [ "number", "null" ] }, "error": { "type": [ "string", "null" ] } }, "required": [ "ok", "status", "error" ] } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Role too low", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } } }, "webhooks": {} }