openapi: 3.2.0 info: title: Axonflow Metrics 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 Metrics across 4 of this provider''s published API definitions: axonflow-agent-api.yaml, axonflow-orchestrator-api.yaml, axonflow-agent-openapi.yml, axonflow-orchestrator-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 - url: https://orchestrator.getaxonflow.com description: Production (SaaS) - url: http://localhost:8081 description: Local Development tags: - name: Metrics description: Performance monitoring and observability paths: /metrics: get: tags: - Metrics summary: Get performance metrics description: 'Returns real-time performance metrics including: - Request counts (total, success, failed, blocked) - Latency percentiles (P50, P95, P99) - Per-stage timing (auth, policy, network) - Request type breakdown - Connector metrics' operationId: getMetrics responses: '200': description: Performance metrics content: application/json: schema: $ref: '#/components/schemas/MetricsResponse' 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 /prometheus: get: tags: - Metrics summary: Prometheus metrics endpoint description: Returns metrics in Prometheus exposition format for scraping operationId: getPrometheusMetrics responses: '200': description: Prometheus metrics content: text/plain: schema: type: string example: '# HELP axonflow_agent_requests_total Total requests # TYPE axonflow_agent_requests_total counter axonflow_agent_requests_total{status="success"} 1234 ' 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/metrics: get: tags: - Metrics summary: Get detailed metrics description: Returns detailed metrics from the metrics collector operationId: getDetailedMetrics responses: '200': description: Detailed metrics content: application/json: schema: type: object servers: - url: https://orchestrator.getaxonflow.com description: Production (SaaS) - url: http://localhost:8081 description: Local Development components: schemas: MetricsResponse: type: object properties: agent_metrics: type: object properties: uptime_seconds: type: number total_requests: type: integer success_requests: type: integer failed_requests: type: integer blocked_requests: type: integer success_rate: type: number description: Success rate percentage rps: type: number description: Requests per second error_rate_per_sec: type: number p50_ms: type: number description: 50th percentile latency p95_ms: type: number description: 95th percentile latency p99_ms: type: number description: 99th percentile latency avg_latency_ms: type: number auth_p99_ms: type: number description: Authentication stage P99 latency static_policy_eval_p99_ms: type: number description: Static policy evaluation P99 latency network_p99_ms: type: number description: Network (Agent to Orchestrator) P99 latency health: type: object properties: status: type: string enum: - healthy - degraded - unhealthy healthy: type: boolean consecutive_errors: type: integer up: type: integer description: Always 1 if service is responding request_types: type: object additionalProperties: type: object properties: total_requests: type: integer success_requests: type: integer p99_ms: type: number connectors: type: object additionalProperties: type: object properties: total_requests: type: integer success_rate: type: number p99_ms: type: number timestamp: type: string format: date-time MetricsResponse_2: type: object properties: orchestrator_metrics: type: object properties: uptime_seconds: type: number total_requests: type: integer success_requests: type: integer failed_requests: type: integer blocked_requests: type: integer success_rate: type: number rps: type: number error_rate_per_sec: type: number dynamic_policy_eval_p50_ms: type: number dynamic_policy_eval_p95_ms: type: number dynamic_policy_eval_p99_ms: type: number llm_routing_p50_ms: type: number llm_routing_p95_ms: type: number llm_routing_p99_ms: type: number health: type: object properties: up: type: integer consecutive_errors: type: integer request_types: type: object additionalProperties: type: object providers: type: object additionalProperties: type: object properties: total_calls: type: integer success_calls: type: integer failed_calls: type: integer total_tokens: type: integer total_cost: type: number p99_ms: type: number timestamp: type: string format: date-time MetricsResponse_3: type: object properties: orchestrator_metrics: type: object properties: uptime_seconds: type: number total_requests: type: integer success_requests: type: integer failed_requests: type: integer blocked_requests: type: integer success_rate: type: number rps: type: number error_rate_per_sec: type: number dynamic_policy_eval_p50_ms: type: number dynamic_policy_eval_p95_ms: type: number dynamic_policy_eval_p99_ms: type: number llm_routing_p50_ms: type: number llm_routing_p95_ms: type: number llm_routing_p99_ms: type: number health: type: object properties: up: type: integer consecutive_errors: type: integer request_types: type: object additionalProperties: type: object providers: type: object additionalProperties: type: object properties: total_calls: type: integer success_calls: type: integer failed_calls: type: integer total_tokens: type: integer total_cost: type: number p99_ms: type: number timestamp: type: string format: date-time 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. ' basicAuth: type: http scheme: basic description: OAuth2-style client credentials (clientId:clientSecret) BearerAuth: type: http scheme: bearer bearerFormat: JWT description: Enterprise JWT token (see /scripts/generate-jwt.sh) x-refined-from: - axonflow-agent-api.yaml - axonflow-orchestrator-api.yaml - axonflow-agent-openapi.yml - axonflow-orchestrator-openapi.yml