openapi: 3.2.0 info: title: Axonflow Circuit Breaker API version: 11.1.0 contact: name: AxonFlow Support url: https://getaxonflow.com/support license: name: Business Source License 1.1 url: https://github.com/getaxonflow/axonflow/blob/main/LICENSE description: 'Operations tagged Circuit Breaker across 2 of this provider''s published API definitions: axonflow-agent-api.yaml, axonflow-agent-openapi.yml. Each path carries the servers of the definition it was published in.' servers: - url: https://agent.getaxonflow.com description: Production (SaaS) - url: https://axonflow.example.com description: Self-hosted deployment (agent single entry point, ADR-024) - url: http://localhost:8080 description: Local Development tags: - name: Circuit Breaker description: 'Emergency circuit breaker for AI operations (EU AI Act Article 14). Instantly halt AI operations with two-person deactivation requirement.' paths: /api/v1/circuit-breaker/trip: post: tags: - Circuit Breaker summary: Trip circuit breaker (emergency stop) description: 'Immediately halt matching AI operations for the organization (EU AI Act Article 14). Also exposed as the alias `POST /api/v1/emergency-stop`. Identity comes from headers stamped by the auth middleware: `X-Org-ID` (falls back to `X-Tenant-ID`) selects the org; `X-User-ID` is **required** for the Article 14 audit trail (400 when missing). `X-User-Email` is recorded when present. **Enterprise only** — community builds register no circuit-breaker routes (404).' operationId: tripCircuitBreaker parameters: - $ref: '#/components/parameters/LicenseKey' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CircuitBreakerTripRequest' responses: '201': description: Circuit tripped — matching requests are now blocked content: application/json: schema: type: object properties: success: type: boolean data: type: object properties: circuit_id: type: string state: type: string scope: type: string scope_id: type: string tripped_at: type: string format: date-time expires_at: type: string format: date-time message: type: string '400': description: Missing X-Org-ID/X-User-ID header, invalid JSON, invalid scope, or missing scope_id for a non-global scope content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' servers: - url: https://agent.getaxonflow.com description: Production (SaaS) - url: https://axonflow.example.com description: Self-hosted deployment (agent single entry point, ADR-024) - url: http://localhost:8080 description: Local Development /api/v1/circuit-breaker/reset: post: tags: - Circuit Breaker summary: Reset circuit breaker (release emergency stop) description: 'Release an emergency stop and resume normal operations. Also exposed as the alias `POST /api/v1/emergency-stop/release`. Requires `X-Org-ID` (or `X-Tenant-ID`) and `X-User-ID` headers (400 when missing). **Enterprise only.**' operationId: resetCircuitBreaker parameters: - $ref: '#/components/parameters/LicenseKey' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CircuitBreakerResetRequest' responses: '200': description: Circuit reset — normal operations resumed content: application/json: schema: type: object properties: success: type: boolean data: type: object properties: scope: type: string scope_id: type: string state: type: string example: closed message: type: string '400': description: Missing X-Org-ID/X-User-ID header or invalid JSON content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' servers: - url: https://agent.getaxonflow.com description: Production (SaaS) - url: https://axonflow.example.com description: Self-hosted deployment (agent single entry point, ADR-024) - url: http://localhost:8080 description: Local Development /api/v1/circuit-breaker/check: post: tags: - Circuit Breaker summary: Check whether a request would be allowed description: 'Evaluates the caller''s scope hierarchy (global → tenant → client → policy) and reports whether an open circuit would block the request. Read-only; does not mutate circuit state. **Enterprise only.**' operationId: checkCircuitBreaker parameters: - $ref: '#/components/parameters/LicenseKey' requestBody: required: true content: application/json: schema: type: object properties: tenant_id: type: string client_id: type: string policy_id: type: string responses: '200': description: Check result (allowed, or blocked with the tripping circuit's details) content: application/json: schema: type: object properties: success: type: boolean data: type: object properties: allowed: type: boolean circuit_id: type: string description: Present only when blocked scope: type: string scope_id: type: string reason: type: string tripped_by: type: string tripped_at: type: string format: date-time expires_at: type: string format: date-time comment: type: string '400': description: Missing X-Org-ID header or invalid JSON content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' servers: - url: https://agent.getaxonflow.com description: Production (SaaS) - url: https://axonflow.example.com description: Self-hosted deployment (agent single entry point, ADR-024) - url: http://localhost:8080 description: Local Development /api/v1/emergency-stop: post: tags: - Circuit Breaker summary: Emergency stop (alias of circuit-breaker trip) description: 'Clearer Article 14 naming for `POST /api/v1/circuit-breaker/trip` — identical handler, request body, and responses. **Enterprise only.**' operationId: emergencyStop parameters: - $ref: '#/components/parameters/LicenseKey' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CircuitBreakerTripRequest' responses: '201': description: Emergency stop activated (see the trip endpoint for the body shape) '400': $ref: '#/components/responses/BadRequest' servers: - url: https://agent.getaxonflow.com description: Production (SaaS) - url: https://axonflow.example.com description: Self-hosted deployment (agent single entry point, ADR-024) - url: http://localhost:8080 description: Local Development /api/v1/emergency-stop/release: post: tags: - Circuit Breaker summary: Release emergency stop (alias of circuit-breaker reset) description: 'Clearer Article 14 naming for `POST /api/v1/circuit-breaker/reset` — identical handler, request body, and responses. **Enterprise only.**' operationId: emergencyStopRelease parameters: - $ref: '#/components/parameters/LicenseKey' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CircuitBreakerResetRequest' responses: '200': description: Emergency stop released (see the reset endpoint for the body shape) '400': $ref: '#/components/responses/BadRequest' servers: - url: https://agent.getaxonflow.com description: Production (SaaS) - url: https://axonflow.example.com description: Self-hosted deployment (agent single entry point, ADR-024) - url: http://localhost:8080 description: Local Development /api/v1/circuit-breaker/status: get: tags: - Circuit Breaker summary: Get circuit breaker status description: 'Returns all active (open) circuits for the organization. Uses X-Org-ID header for org identification.' operationId: getCircuitBreakerStatus parameters: - $ref: '#/components/parameters/LicenseKey' responses: '200': description: Active circuit breaker circuits content: application/json: schema: type: object properties: success: type: boolean data: type: object properties: active_circuits: type: array items: $ref: '#/components/schemas/CircuitBreaker' count: type: integer emergency_stop_active: type: boolean '400': $ref: '#/components/responses/BadRequest' servers: - url: https://agent.getaxonflow.com description: Production (SaaS) - url: https://axonflow.example.com description: Self-hosted deployment (agent single entry point, ADR-024) - url: http://localhost:8080 description: Local Development /api/v1/circuit-breaker/history: get: tags: - Circuit Breaker summary: Get circuit breaker history description: 'Returns circuit breaker trip/reset history for audit trail. Ordered by creation time descending.' operationId: getCircuitBreakerHistory parameters: - $ref: '#/components/parameters/LicenseKey' - name: limit in: query schema: type: integer minimum: 1 maximum: 100 default: 50 responses: '200': description: Circuit breaker history content: application/json: schema: type: object properties: success: type: boolean data: type: object properties: history: type: array items: $ref: '#/components/schemas/CircuitBreaker' count: type: integer '400': $ref: '#/components/responses/BadRequest' servers: - url: https://agent.getaxonflow.com description: Production (SaaS) - url: https://axonflow.example.com description: Self-hosted deployment (agent single entry point, ADR-024) - url: http://localhost:8080 description: Local Development /api/v1/circuit-breaker/config: get: tags: - Circuit Breaker summary: Get circuit breaker config description: 'Returns effective circuit breaker configuration. If tenant_id is provided, returns tenant-specific overrides merged with global defaults. Otherwise returns global defaults.' operationId: getCircuitBreakerConfig parameters: - $ref: '#/components/parameters/LicenseKey' - name: tenant_id in: query schema: type: string description: Optional tenant ID for tenant-specific config responses: '200': description: Effective circuit breaker configuration content: application/json: schema: type: object properties: success: type: boolean data: $ref: '#/components/schemas/CircuitBreakerConfigResponse' '400': $ref: '#/components/responses/BadRequest' put: tags: - Circuit Breaker summary: Update per-tenant circuit breaker config description: 'Creates or updates per-tenant circuit breaker threshold overrides. Null fields fall back to global defaults.' operationId: updateCircuitBreakerConfig parameters: - $ref: '#/components/parameters/LicenseKey' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CircuitBreakerConfigUpdate' responses: '200': description: Config updated '400': $ref: '#/components/responses/BadRequest' servers: - url: https://agent.getaxonflow.com description: Production (SaaS) - url: https://axonflow.example.com description: Self-hosted deployment (agent single entry point, ADR-024) - url: http://localhost:8080 description: Local Development /api/v1/circuit-breaker/notifications: get: tags: - Circuit Breaker summary: List notification configs description: Returns all circuit breaker notification configs for the organization. operationId: listCircuitBreakerNotifications parameters: - $ref: '#/components/parameters/LicenseKey' responses: '200': description: Notification configs content: application/json: schema: type: object properties: success: type: boolean data: type: object properties: notifications: type: array items: $ref: '#/components/schemas/CircuitBreakerNotificationConfig' count: type: integer '400': description: Missing X-Org-ID header content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' post: tags: - Circuit Breaker summary: Create notification config description: 'Create a notification channel for circuit breaker auto-trip events. Supports webhook (HMAC-signed), Slack (Block Kit), and PagerDuty (Events API v2).' operationId: createCircuitBreakerNotification parameters: - $ref: '#/components/parameters/LicenseKey' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CircuitBreakerNotificationCreate' responses: '201': description: Notification config created '400': $ref: '#/components/responses/BadRequest' servers: - url: https://agent.getaxonflow.com description: Production (SaaS) - url: https://axonflow.example.com description: Self-hosted deployment (agent single entry point, ADR-024) - url: http://localhost:8080 description: Local Development /api/v1/circuit-breaker/notifications/{id}: put: tags: - Circuit Breaker summary: Update notification config operationId: updateCircuitBreakerNotification parameters: - $ref: '#/components/parameters/LicenseKey' - name: id in: path required: true schema: type: string requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CircuitBreakerNotificationUpdate' responses: '200': description: Notification config updated '404': description: Notification config not found delete: tags: - Circuit Breaker summary: Delete notification config operationId: deleteCircuitBreakerNotification parameters: - $ref: '#/components/parameters/LicenseKey' - name: id in: path required: true schema: type: string responses: '200': description: Notification config deleted '404': description: Notification config not found servers: - url: https://agent.getaxonflow.com description: Production (SaaS) - url: https://axonflow.example.com description: Self-hosted deployment (agent single entry point, ADR-024) - url: http://localhost:8080 description: Local Development components: schemas: CircuitBreakerConfigUpdate: type: object required: - tenant_id properties: tenant_id: type: string error_threshold: type: - integer - 'null' violation_threshold: type: - integer - 'null' window_seconds: type: - integer - 'null' default_timeout_seconds: type: - integer - 'null' max_timeout_seconds: type: - integer - 'null' enable_auto_recovery: type: - boolean - 'null' CircuitBreakerTripRequest: type: object description: 'Request body for trip / emergency-stop. Org and user identity come from the `X-Org-ID` (or `X-Tenant-ID`) and `X-User-ID` headers, not the body. Source of truth: `platform/agent/circuitbreaker/handler.go` (TripRequest). ' properties: scope: type: string enum: - global - tenant - client - policy default: global description: Blast radius of the stop scope_id: type: string description: Required for non-global scopes (tenant/client/policy ID) reason: type: string enum: - manual - policy_violation - risk_level - error_rate default: manual comment: type: string description: Free-text audit-trail comment duration_minutes: type: integer description: Auto-expire after N minutes; 0 or omitted = indefinite CircuitBreakerNotificationConfig: type: object properties: id: type: string org_id: type: string tenant_id: type: string type: type: string enum: - webhook - slack - pagerduty url: type: string secret: type: string description: Masked in GET responses active: type: boolean created_at: type: string format: date-time updated_at: type: string format: date-time CircuitBreakerResetRequest: type: object description: 'Request body for reset / emergency-stop release. Org and user identity come from headers, not the body. Source of truth: `platform/agent/circuitbreaker/handler.go` (ResetRequest). ' properties: scope: type: string enum: - global - tenant - client - policy default: global scope_id: type: string comment: type: string description: Free-text audit-trail comment CircuitBreakerNotificationUpdate: type: object properties: type: type: string enum: - webhook - slack - pagerduty url: type: string secret: type: string tenant_id: type: string active: type: boolean CircuitBreakerConfigResponse: type: object properties: source: type: string enum: - global - tenant description: Whether config is global defaults or tenant-specific error_threshold: type: integer description: Number of errors in window to trigger auto-trip violation_threshold: type: integer description: Number of policy violations in window to trigger auto-trip window_seconds: type: integer description: Sliding window duration for counting events default_timeout_seconds: type: integer description: How long a circuit stays open before auto-recovery max_timeout_seconds: type: integer description: Maximum allowed circuit timeout enable_auto_recovery: type: boolean description: Whether open circuits automatically close after timeout tenant_id: type: string description: Tenant ID (present when source is tenant) overrides: type: object description: Tenant-specific override values (present when source is tenant) CircuitBreaker: type: object description: 'A circuit record as returned by the status and history endpoints. Source of truth: `platform/agent/circuitbreaker/circuit_breaker.go` (Circuit). ' properties: id: type: string scope: type: string enum: - global - tenant - client - policy scope_id: type: string org_id: type: string state: type: string enum: - closed - open - half_open description: "- closed: Normal operation\n- open: circuit tripped — matching requests are blocked\n- half_open: testing recovery — limited requests allowed\n (auto-recovery transition; can appear in status/history)\n" trip_reason: type: string enum: - manual - policy_violation - risk_level - error_rate tripped_by: type: string tripped_by_email: type: string trip_comment: type: string tripped_at: type: string format: date-time expires_at: type: string format: date-time description: Auto-expiry time when the trip carried a duration; absent for indefinite trips reset_by: type: string reset_at: type: string format: date-time error_count: type: integer violation_count: type: integer created_at: type: string format: date-time updated_at: type: string format: date-time ErrorResponse: type: object description: 'Handler-written error envelope. Note the agent has a second error envelope for middleware-written errors (see JSONError) — clients should tolerate both shapes on 4xx/5xx. ' properties: success: type: boolean example: false error: type: string description: Error message CircuitBreakerNotificationCreate: type: object required: - type - url properties: type: type: string enum: - webhook - slack - pagerduty url: type: string description: Webhook URL, Slack incoming webhook URL, or PagerDuty override URL secret: type: string description: HMAC secret for webhooks, or PagerDuty routing key tenant_id: type: string description: Optional tenant filter for notifications active: type: boolean default: true responses: BadRequest: description: Invalid request body or parameters content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: success: false error: Invalid request body parameters: LicenseKey: name: Authorization in: header required: true description: 'OAuth2-style Basic authentication header. Format: `Basic base64(clientId:clientSecret)` - `clientId`: Your organization identifier (required) - `clientSecret`: Authentication credential (optional for community mode) Not required when `DEPLOYMENT_MODE=community`. ' schema: type: string example: Basic bXktb3JnOkFYT04tVjIteHh4 securitySchemes: BasicAuth: type: http scheme: basic description: "OAuth2-style Basic authentication using `clientId:clientSecret` credentials.\n\n**Header format:** `Authorization: Basic base64(clientId:clientSecret)`\n\n- `clientId` (required): Your organization/client identifier\n- `clientSecret` (optional): Authentication credential. Optional for community/self-hosted mode.\n\n**Example:**\n```bash\n# With clientSecret (enterprise)\ncurl -H \"Authorization: Basic $(echo -n 'my-org:AXON-V2-xxx' | base64)\" ...\n\n# Without clientSecret (community mode)\ncurl -H \"Authorization: Basic $(echo -n 'my-org:' | base64)\" ...\n```\n\n## Per-user identity behind a shared credential\n\nThis credential authenticates an ORGANIZATION or client, not a person.\nBehind one such credential can sit many human principals, each\noptionally forwarding a **per-user token** that proves who they are.\nWhere that token is read depends on the envelope: the `user_token`\nfield of the request body on `POST /api/v1/decide` and the four MCP\nREST routes, and the `X-User-Token` header on the MCP-server JSON-RPC\nplane. The two spellings are deliberately not interchangeable.\n\n**A presented per-user token that fails to validate is a refused\naccess attempt, not a legacy caller** (`401`, audited\n`user_token_rejected`). It is never downgraded to a shared service\nidentity, so revocation, expiry, algorithm pinning and signature\nchecks take effect on every plane that reads one.\n\n**Whether presenting a token is REQUIRED is a per-organization\nposture, `require_user_token`, and it is off by default (#3476).**\nWith it off, an enterprise caller that presents no token at all is\nserved under a synthetic org-scoped service identity\n(`@axonflow.local`, role `service`), which is the correct\nanswer for an infrastructure gateway acting as a Policy Enforcement\nPoint with no end-user token to forward. With it on, that caller is\nrefused at AUTHENTICATION, before any policy is evaluated (`401`,\naudited `user_token_required`).\n\nThe posture exists because a policy that names a PERSON - a\nprincipal-scoped constraint or permission in the organization's typed\ndocument (PRD v11 §1.6) - is only meaningful if a caller cannot CHOOSE\nto arrive without an identity: with the posture off such a policy\nstill applies to everyone who presents a token, but a caller can\ndecline to present one and be decided as the credential\n(`subject_type=Client`). Governance segments (ADR-060) decide on no\nagent route since v11.0.0 (#4253). Two levers set it, and an explicit\nper-organization row wins over the deployment-wide default in EITHER\ndirection:\n\n- `organizations.require_user_token`, per organization, default\n `false`.\n- `AXONFLOW_REQUIRE_USER_TOKEN`, deployment-wide, default `false`.\n\nA posture change takes up to one cache window to become live\n(`AXONFLOW_REQUIRE_USER_TOKEN_TTL_SECONDS`, default 60 seconds,\nclamped to `[5, 600]`). A posture that cannot be READ resolves to\nREQUIRED rather than not-required, so a database outage cannot\nquietly switch the control off; a genuinely absent organization row\nis not a read failure and falls through to the deployment default.\n\n`POST /v1/chat/completions` is outside this guarantee: it mirrors\nOpenAI's wire shape and carries no per-user token field at all, so it\nkeeps the synthetic-identity fallback regardless of the posture.\nCommunity and community-SaaS deployments never reach any of the above.\n" InternalServiceID: type: apiKey in: header name: X-Internal-Service-ID description: 'Internal-service (operator lane) credential — **part one of two**. Must be sent together with `X-Internal-Service-Token`; either header alone is not a credential. This is the HMAC identity the Orchestrator and the Enterprise customer-portal use to call agent endpoints without holding a customer license. `apiAuthMiddleware` lifts both headers (plus an optional `X-Tenant-ID` scope) into `AuthHints` (`internalServiceHints` in `platform/agent/auth.go`) and `Authenticate()` validates them before any mode-specific auth (`platform/agent/authenticator.go:120-155`). Value: the service id, `orchestrator-internal`. ⚠️ An invalid or expired token is **not** an error by itself — it falls through to the deployment''s normal auth (`platform/agent/authenticator.go:153-154`). Send the internal-service headers on their own: paired with an `Authorization: Basic` header, a stale token silently yields a *tenant*-scoped answer that looks like a successful operator call. ' InternalServiceToken: type: apiKey in: header name: X-Internal-Service-Token description: 'Internal-service (operator lane) credential — **part two of two**. Must be sent together with `X-Internal-Service-ID`. Format: `AXON-INTERNAL-{unix_ts}-{sig}`, where `sig` is the first 16 hex characters of HMAC-SHA256 over `orchestrator-internal:{unix_ts}` keyed with `AXONFLOW_INTERNAL_SERVICE_SECRET`. Validated by `platform/shared/serviceauth` within a 5-minute clock-skew window, so it must be re-minted per session. See `technical-docs/runbooks/RUNBOOK_CONNECTOR_CONFIGURATION.md` for the exact minting snippet. ' x-refined-from: - axonflow-agent-api.yaml - axonflow-agent-openapi.yml