{ "openapi": "3.1.0", "info": { "title": "Codex Quota Monitor API", "version": "1.0.0", "summary": "Mostly read-only API for CLIProxyAPI-backed Codex OAuth pool monitoring.", "description": "Versioned API contract for local dashboards, agent wrappers, Prometheus, and operator smoke tests. JSON clients must ignore unknown fields. The protected manual quota refresh action is the only mutating v1 endpoint. The monitor API is not an authentication boundary." }, "servers": [ { "url": "http://127.0.0.1:4515", "description": "Default loopback listener" } ], "paths": { "/healthz": { "get": { "summary": "Process liveness", "description": "Returns process liveness only. It does not verify CPA, management key, auth-dir, SQLite, or benchmark import health.", "operationId": "getHealthz", "tags": [ "liveness" ], "responses": { "200": { "description": "The monitor process is reachable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Healthz" }, "examples": { "ok": { "value": { "ok": true } } } } } } }, "x-stability": "stable" } }, "/api/v1/status": { "get": { "summary": "Dashboard snapshot", "description": "Full browser dashboard snapshot. The top-level envelope is stable for v1. Deep tab payloads are UI-oriented and may grow during 0.x releases.", "operationId": "getV1Status", "tags": [ "dashboard" ], "responses": { "200": { "description": "Current dashboard snapshot.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatusSnapshot" } } } } }, "x-stability": "stable-envelope" } }, "/api/v1/stats": { "get": { "summary": "Stats tab payload", "description": "Narrow Stats tab payload with live timestamped CPA usage details, cumulative CPA counters, SQLite-backed history, data sources, and native backup hints.", "operationId": "getV1Stats", "tags": [ "dashboard" ], "responses": { "200": { "description": "Current Stats tab payload.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatsTab" } } } } }, "x-stability": "stable-fields" } }, "/api/v1/stats/series": { "get": { "summary": "Stats time-series payload", "description": "SQLite history-backed Stats workbench payload. The browser dashboard uses this endpoint for token/request curves, breakdown panels, and exporting the current view.", "operationId": "getV1StatsSeries", "tags": [ "dashboard" ], "parameters": [ { "name": "range", "in": "query", "schema": { "type": "string", "enum": [ "1h", "6h", "24h", "7d", "30d", "all" ] }, "description": "Time window to aggregate. Defaults to 24h." }, { "name": "metric", "in": "query", "schema": { "type": "string", "enum": [ "tokens", "requests" ] }, "description": "Primary chart metric. Defaults to tokens." }, { "name": "group", "in": "query", "schema": { "type": "string", "enum": [ "total", "account", "client", "model", "api" ] }, "description": "Series grouping dimension. Defaults to total. Use client with --client-labels-file for privacy-preserving shared-client attribution; api preserves raw CPA API names for compatibility." }, { "name": "top", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 20 }, "description": "Maximum highest-usage items to return. Grouped views use it for chart lines and breakdown rows; total keeps one chart line while still using it for the breakdown. Defaults to 8." }, { "name": "smooth", "in": "query", "schema": { "type": "boolean" }, "description": "When false, the UI should prefer raw bucket points. Also accepts 0, false, off, and no." }, { "name": "mode", "in": "query", "schema": { "type": "string", "enum": [ "bucket", "rate" ] }, "description": "Value display mode: bucket totals or per-minute rate. Defaults to bucket." }, { "name": "format", "in": "query", "schema": { "type": "string", "enum": [ "json", "csv" ] }, "description": "Defaults to JSON. Use csv to export the current view as text/csv." } ], "responses": { "200": { "description": "Current Stats series view.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatsSeries" } }, "text/csv; charset=utf-8": { "schema": { "type": "string" }, "examples": { "header": { "value": "timestamp,series_id,series_label,requests,tokens,failed,request_text,token_text,failure_rate\n" } } } } } }, "x-stability": "stable-fields" } }, "/api/v1/recommendations": { "get": { "summary": "Account recommendations", "description": "Stable wrapper-facing list of accounts ranked by routing score. Account-selection automation should use this endpoint instead of scraping deep /api/v1/status tabs.", "operationId": "getV1Recommendations", "tags": [ "wrappers" ], "responses": { "200": { "description": "Current routing-score recommendations.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Recommendations" }, "examples": { "normal": { "value": { "contractVersion": "1.1", "sampledAt": "2026-04-20T12:00:00+00:00", "source": { "kind": "live", "text": "Live via CLIProxyAPI + direct Codex quota", "gatewayOk": true }, "routingPolicy": { "scoreMax": 100, "capacityWeightUnit": "plus", "hardBlocks": [ "routeEligible=false", "tone=bad", "status disabled/unavailable/invalid/auth invalid/cooldown", "exhausted quota windows" ] }, "summary": "3 routable accounts · 1 blocked account · top score 86", "routableCount": 3, "blockedCount": 1, "topScore": 86, "items": [ { "selector": { "authName": "auth-redacted.json", "authIndex": "acct-redacted", "accountKey": "acct-redacted" }, "authIndex": "acct-redacted", "accountKey": "acct-redacted", "planKind": "plus", "tone": "good", "title": "account-redacted@example.invalid", "badge": "Plus", "summary": "Active · 5h 80% · weekly 80%", "detail": "Direct quota sample 20:00", "routingScore": 86, "routingEligible": true, "scoreComponents": { "capacity": 36, "health": 25, "plan": 5, "load": 10, "reclaim": 10 }, "routingBlockedReasons": [], "capacityWeight": 1, "quotaWindows": [ { "id": "5h", "label": "5h", "state": "known", "percent": 80, "resetAt": "2026-04-20T13:00:00+00:00", "resetsInSeconds": 3600, "remainingText": "1h 0min", "stale": false }, { "id": "week", "label": "Weekly", "state": "known", "percent": 80, "resetAt": "2026-04-21T12:00:00+00:00", "resetsInSeconds": 86400, "remainingText": "1d 0h", "stale": false } ], "reclaimEligible": true, "reclaimWindow": null } ] } } } } } } }, "x-stability": "stable" } }, "/api/v1/quota/refresh": { "post": { "summary": "Start protected manual direct quota refresh", "description": "Starts a manual refresh of direct Codex quota samples. Without a body this refreshes primary, recovery, and discovery accounts. With {\"scope\":\"disabled-diagnostics\"}, it probes operator-disabled Codex accounts for diagnostics while keeping them excluded from routing and capacity. The latest disabled probe result is retained across normal automatic quota refreshes until the next disabled-diagnostics probe or process restart. By default the browser UI sends an in-page refresh token with X-Codex-Quota-Monitor-Refresh-Token. Legacy deployments may set manual_quota_refresh_auth to management-key to require the CPA management key as an Authorization Bearer token; operators may set it to none for trusted local deployments. The request queues the refresh and returns immediately.", "operationId": "postV1QuotaRefresh", "tags": [ "operations" ], "security": [ { "RefreshToken": [] }, { "ManagementBearer": [] }, {} ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "scope": { "type": "string", "enum": [ "default", "disabled-diagnostics" ], "default": "default" } } }, "examples": { "disabledDiagnostics": { "value": { "scope": "disabled-diagnostics" } } } } } }, "responses": { "202": { "description": "Manual quota refresh was accepted or is already running.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManualQuotaRefreshResult" }, "examples": { "running": { "value": { "ok": true, "status": "running", "scope": "default", "startedAt": "2026-05-12T12:00:00+00:00", "completedAt": null, "error": "" } } } } } }, "401": { "description": "Refresh token or legacy bearer token is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManualQuotaRefreshResult" } } } }, "400": { "description": "Request body is invalid JSON or contains an unsupported refresh scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManualQuotaRefreshResult" } } } }, "403": { "description": "Host or Origin guard rejected the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManualQuotaRefreshResult" } } } }, "503": { "description": "Manual refresh is unavailable because management auth is not configured or readable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManualQuotaRefreshResult" } } } } }, "x-stability": "additive" } }, "/metrics": { "get": { "summary": "Prometheus metrics", "description": "Prometheus text exposition for snapshot source, gateway state, alerts, recommendations, and capacity counters.", "operationId": "getMetrics", "tags": [ "prometheus" ], "responses": { "200": { "description": "Prometheus text metrics.", "content": { "text/plain; version=0.0.4; charset=utf-8": { "schema": { "type": "string" } } } } }, "x-stability": "stable-metrics" } }, "/api/v1/health": { "get": { "summary": "Operational health payload", "description": "Aggregated operational health for account actions, monitor data sources, and recent changes. This replaces the older separate diagnostics and alerts payloads.", "operationId": "getV1Health", "tags": [ "operations" ], "responses": { "200": { "description": "Current operational health state.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Health" }, "examples": { "review": { "value": { "title": "Health", "state": "warn", "summary": "1 item needs review.", "pill": "1 action", "actionsTitle": "Action needed", "sourcesTitle": "Source status", "recentChangesTitle": "Recent changes", "actions": [ { "kind": "threshold", "tone": "bad", "title": "5h capacity below threshold", "badge": "Threshold", "summary": "0.40 Plus < 0.50 Plus", "detail": "Configured minimum is 0.50 Plus.", "note": "" } ], "sources": [], "recentChanges": [], "actionCount": 1, "sourceCounts": { "good": 0, "warn": 0, "bad": 0, "unknown": 0 } } } } } } } }, "x-stability": "stable" } } }, "components": { "schemas": { "Healthz": { "type": "object", "additionalProperties": true, "required": [ "ok" ], "properties": { "ok": { "type": "boolean" } } }, "ManualQuotaRefreshResult": { "type": "object", "additionalProperties": true, "required": [ "ok", "status" ], "properties": { "ok": { "type": "boolean" }, "status": { "type": "string" }, "scope": { "type": "string", "description": "Manual refresh scope, for example default or disabled-diagnostics." }, "startedAt": { "type": [ "string", "null" ] }, "completedAt": { "type": [ "string", "null" ] }, "error": { "type": "string" } } }, "StatusSnapshot": { "type": "object", "additionalProperties": true, "required": [ "available", "source", "sourceText", "displayTimezone", "displayTimezoneLabel", "summary", "tabs", "recommendations" ], "properties": { "available": { "type": "boolean" }, "source": { "type": "string" }, "sourceText": { "type": "string" }, "displayTimezone": { "type": "string" }, "displayTimezoneLabel": { "type": "string" }, "summary": { "type": "object", "additionalProperties": true, "properties": { "activityLine": { "type": "string", "description": "Display-safe request/token activity line for dashboard UI." } } }, "tabs": { "type": "object", "additionalProperties": true, "description": "UI-oriented tab payload. Treat nested fields as additive during 0.x releases unless explicitly documented elsewhere." }, "recommendations": { "$ref": "#/components/schemas/Recommendations" } } }, "Recommendations": { "type": "object", "additionalProperties": true, "required": [ "contractVersion", "sampledAt", "source", "routingPolicy", "routableCount", "blockedCount", "topScore", "items" ], "properties": { "contractVersion": { "type": "string", "description": "Additive wrapper-facing recommendations contract version." }, "sampledAt": { "type": [ "string", "null" ], "format": "date-time" }, "source": { "type": "object", "additionalProperties": true, "required": [ "kind", "text", "gatewayOk" ], "properties": { "kind": { "type": "string" }, "text": { "type": "string" }, "gatewayOk": { "type": "boolean" } } }, "routingPolicy": { "type": "object", "additionalProperties": true, "properties": { "scoreMax": { "type": "integer" }, "capacityWeightUnit": { "type": "string" }, "hardBlocks": { "type": "array", "items": { "type": "string" } } } }, "summary": { "type": "string" }, "routableCount": { "type": "integer", "minimum": 0 }, "blockedCount": { "type": "integer", "minimum": 0 }, "topScore": { "type": "integer", "minimum": 0 }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/RecommendationItem" } } } }, "RecommendationItem": { "type": "object", "additionalProperties": true, "required": [ "selector", "authIndex", "accountKey", "planKind", "title", "badge", "summary", "routingScore", "routingEligible", "routingBlockedReasons", "capacityWeight", "quotaWindows", "reclaimEligible" ], "properties": { "selector": { "type": "object", "additionalProperties": false, "required": [ "authName", "authIndex", "accountKey" ], "properties": { "authName": { "type": "string" }, "authIndex": { "type": "string" }, "accountKey": { "type": "string" } }, "description": "Selector-safe account identity. Does not include auth file paths, tokens, management keys, download URLs, or raw auth JSON." }, "authIndex": { "type": "string" }, "accountKey": { "type": "string" }, "planKind": { "type": "string" }, "tone": { "type": "string" }, "title": { "type": "string" }, "badge": { "type": "string" }, "summary": { "type": "string" }, "detail": { "type": "string" }, "note": { "type": "string" }, "routingScore": { "type": "integer", "minimum": 0, "maximum": 100 }, "routingEligible": { "type": "boolean" }, "routingBlockedReasons": { "type": "array", "items": { "type": "string" }, "description": "Empty for routable accounts; stable blocker slugs for accounts excluded from routing." }, "scoreComponents": { "type": "object", "additionalProperties": true }, "reasons": { "type": "array", "items": { "type": "string" } }, "capacityWeight": { "type": "number" }, "quotaWindows": { "type": "array", "description": "Sanitized direct-quota window state without auth secrets.", "items": { "type": "object", "additionalProperties": true, "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "state": { "type": "string" }, "percent": { "type": [ "number", "null" ] }, "resetAt": { "type": [ "string", "null" ], "format": "date-time" }, "resetsInSeconds": { "type": [ "integer", "null" ] }, "remainingText": { "type": [ "string", "null" ] }, "stale": { "type": "boolean" } } } }, "reclaimEligible": { "type": "boolean" }, "reclaimWindow": { "oneOf": [ { "$ref": "#/components/schemas/ReclaimWindow" }, { "type": "null" } ] } } }, "ReclaimWindow": { "type": "object", "additionalProperties": true, "required": [ "id", "percent", "resetsInSeconds" ], "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "percent": { "type": "number" }, "resetsInSeconds": { "type": "integer" } } }, "StatsTab": { "type": "object", "additionalProperties": true, "required": [ "title", "summary", "live", "cumulative", "history", "backup", "sources" ], "properties": { "title": { "type": "string" }, "summary": { "type": "string" }, "live": { "type": "object", "additionalProperties": true, "description": "Recent activity derived from timestamped CLIProxyAPI usage details." }, "cumulative": { "type": "object", "additionalProperties": true, "description": "Latest CPA cumulative request and token counters." }, "history": { "type": "object", "additionalProperties": true, "description": "SQLite-backed Stats summary when --state-db is enabled. Use /api/v1/stats/series for the interactive Stats time-series workbench." }, "backup": { "type": "object", "additionalProperties": true, "description": "Native history export/import hints and commands." }, "sources": { "type": "array", "items": { "$ref": "#/components/schemas/MetricItem" } }, "footnote": { "type": "string" } } }, "StatsSeries": { "type": "object", "additionalProperties": true, "required": [ "title", "summary", "defaults", "options", "query", "available", "bucketSeconds", "range", "totals", "series", "breakdown", "export" ], "properties": { "title": { "type": "string" }, "summary": { "type": "string" }, "defaults": { "type": "object", "additionalProperties": true }, "options": { "type": "object", "additionalProperties": true }, "query": { "type": "object", "additionalProperties": true, "properties": { "range": { "type": "string" }, "metric": { "type": "string" }, "group": { "type": "string" }, "top": { "type": "integer" }, "smooth": { "type": "boolean" }, "mode": { "type": "string" } } }, "available": { "type": "boolean" }, "bucketSeconds": { "type": "integer" }, "range": { "type": "object", "additionalProperties": true, "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "seconds": { "type": [ "integer", "null" ] }, "start": { "type": [ "string", "null" ] }, "end": { "type": [ "string", "null" ] }, "earliest": { "type": [ "string", "null" ] } } }, "totals": { "type": "object", "additionalProperties": true }, "series": { "type": "array", "items": { "$ref": "#/components/schemas/StatsSeriesLine" } }, "breakdown": { "type": "object", "additionalProperties": true }, "export": { "type": "object", "additionalProperties": true, "properties": { "jsonPath": { "type": "string" }, "csvPath": { "type": "string" } } } } }, "StatsSeriesLine": { "type": "object", "additionalProperties": true, "required": [ "id", "label", "requests", "tokens", "failed", "points" ], "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "requests": { "type": "integer" }, "tokens": { "type": "integer" }, "failed": { "type": "integer" }, "requestText": { "type": "string" }, "tokenText": { "type": "string" }, "failureRateText": { "type": "string" }, "smoothTokens": { "type": "array", "items": { "type": "number" } }, "smoothRequests": { "type": "array", "items": { "type": "number" } }, "points": { "type": "array", "items": { "$ref": "#/components/schemas/StatsSeriesPoint" } } } }, "StatsSeriesPoint": { "type": "object", "additionalProperties": true, "required": [ "t", "requests", "tokens", "failed", "requestText", "tokenText", "failureRateText" ], "properties": { "t": { "type": "string" }, "requests": { "type": "integer" }, "tokens": { "type": "integer" }, "failed": { "type": "integer" }, "requestText": { "type": "string" }, "tokenText": { "type": "string" }, "failureRateText": { "type": "string" } } }, "MetricItem": { "type": "object", "additionalProperties": true, "required": [ "label", "value" ], "properties": { "label": { "type": "string" }, "value": { "type": "string" }, "detail": { "type": "string" } } }, "HealthItem": { "type": "object", "additionalProperties": true, "required": [ "kind", "tone", "title", "badge", "summary" ], "properties": { "kind": { "type": "string" }, "tone": { "type": "string" }, "title": { "type": "string" }, "badge": { "type": "string" }, "summary": { "type": "string" }, "detail": { "type": "string" }, "note": { "type": "string" } } }, "Health": { "type": "object", "additionalProperties": true, "required": [ "title", "state", "summary", "pill", "actions", "sources", "recentChanges", "actionCount" ], "properties": { "title": { "type": "string" }, "state": { "type": "string", "enum": [ "good", "warn", "bad", "unknown" ] }, "summary": { "type": "string" }, "pill": { "type": "string" }, "actionsTitle": { "type": "string" }, "sourcesTitle": { "type": "string" }, "recentChangesTitle": { "type": "string" }, "actions": { "type": "array", "items": { "$ref": "#/components/schemas/HealthItem" } }, "sources": { "type": "array", "items": { "$ref": "#/components/schemas/HealthItem" } }, "recentChanges": { "type": "array", "items": { "$ref": "#/components/schemas/HealthItem" } }, "actionCount": { "type": "integer", "minimum": 0 }, "sourceCounts": { "type": "object", "additionalProperties": true }, "sampledAt": { "type": "string" }, "source": { "type": "string" }, "sourceText": { "type": "string" }, "recommendations": { "type": "object", "additionalProperties": true } } } }, "securitySchemes": { "RefreshToken": { "type": "apiKey", "in": "header", "name": "X-Codex-Quota-Monitor-Refresh-Token", "description": "Per-process in-page token emitted in the dashboard HTML bootstrap for the default manual refresh action." }, "ManagementBearer": { "type": "http", "scheme": "bearer", "description": "Legacy mode: configured CPA management key used as a protected local action token." } } } }