openapi: 3.2.0
info:
  title: Axonflow Health 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 Health 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: Health
  description: Service health and readiness checks
paths:
  /health:
    get:
      tags:
      - Health
      summary: Health check
      description: 'Returns service health status. During startup, returns `status: starting`.

        Once fully initialized, returns `status: healthy`.


        This endpoint responds immediately even during initialization, allowing

        ECS/ALB health checks to pass while the service starts up.'
      operationId: healthCheck
      responses:
        '200':
          description: Service health status
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HealthResponse'
              examples:
                healthy:
                  summary: Healthy service
                  value:
                    status: healthy
                    service: axonflow-agent
                    timestamp: '2025-01-15T10:30:00Z'
                    version: 1.0.0
                starting:
                  summary: Service starting
                  value:
                    status: starting
                    service: axonflow-agent
                    timestamp: '2025-01-15T10:30:00Z'
                    version: 1.0.0
    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:
    SDKCompatInfo:
      type: object
      description: 'SDK version compatibility information. Each key in the maps below

        is one of `python` / `typescript` / `go` / `java` / `rust`. SDKs

        that find their own runtime version below

        `min_sdk_version[<their lang>]` log a one-time upgrade warning;

        below `recommended_sdk_version` is informational only.


        The examples below are the values this platform actually serves.

        They are not illustrative: a regression test compares them against

        platform/shared/sdkcompat, the single source of truth both /health

        planes read, so a stale example fails CI rather than misleading a

        reader.

        '
      properties:
        min_sdk_version:
          type: object
          additionalProperties:
            type: string
          description: 'Per-language minimum SDK version compatible with this

            platform. Pre-v4.8.0 platforms returned a bare string; SDKs

            v6.0.0+ accept either shape.

            '
          example:
            python: 8.0.0
            typescript: 8.0.0
            go: 8.0.0
            java: 8.0.0
            rust: 0.7.0
        recommended_sdk_version:
          type: object
          additionalProperties:
            type: string
          description: Per-language SDK version this platform was tested against.
          example:
            python: 9.4.0
            typescript: 9.4.0
            go: 9.4.0
            java: 9.4.0
            rust: 0.11.0
    PlatformCapability:
      type: object
      properties:
        name:
          type: string
          description: Capability identifier
          example: workflow_control
        since:
          type: string
          description: Platform version that introduced this capability
          example: 4.3.0
        description:
          type: string
          description: Human-readable description
          example: WCP workflow lifecycle management
    HealthResponse:
      type: object
      properties:
        status:
          type: string
          enum:
          - healthy
          - starting
          description: Service health status (the handler emits only these two)
        service:
          type: string
          example: axonflow-agent
        timestamp:
          type: string
          format: date-time
        version:
          type: string
          description: Platform version from AXONFLOW_VERSION env var
          example: 9.8.0
        tier:
          type: string
          description: License tier of the deployment (e.g. community, evaluation, enterprise)
        capabilities:
          type: array
          description: List of platform capabilities with the version that introduced them
          items:
            $ref: '#/components/schemas/PlatformCapability'
        sdk_compatibility:
          $ref: '#/components/schemas/SDKCompatInfo'
        plugin_compatibility:
          $ref: '#/components/schemas/PluginCompatInfo'
        upstream:
          type: object
          description: 'Whether the orchestrator has answered this agent since the

            process started (#4249 row 5681489141): `reached` from its first

            HTTP response of any status, `unreached` before. Until it is

            reached, a connection the orchestrator refuses is not counted

            against the client''s circuit breaker. Informational only:

            `status` and the HTTP code do not read it.

            '
          properties:
            orchestrator:
              type: string
              enum:
              - reached
              - unreached
    PluginCompatInfo:
      type: object
      description: 'Plugin version compatibility information. Mirrors `SDKCompatInfo`

        for the seven AxonFlow clients (`openclaw`, `claude-code`,

        `cursor`, `codex`, `claude-desktop`, `n8n`, `google-adk`). The first

        four read this from

        `/health` and warn when their runtime version is below

        `min_plugin_version[<their id>]`. Keys match the canonical plugin

        IDs the agent tracks in

        `integration_activation.go::knownIntegrations`.


        The examples below are the values this platform actually serves.

        They are not illustrative: a regression test compares them against

        platform/shared/plugincompat, the single source of truth both

        /health planes read, so a stale example fails CI rather than

        misleading a reader.

        '
      properties:
        min_plugin_version:
          type: object
          additionalProperties:
            type: string
          description: Per-plugin minimum version compatible with this platform.
          example:
            openclaw: 2.4.0
            claude-code: 1.4.0
            cursor: 1.4.0
            codex: 1.4.0
            claude-desktop: 0.2.0
            n8n: 1.2.0
            google-adk: 1.2.0
        recommended_plugin_version:
          type: object
          additionalProperties:
            type: string
          description: Per-plugin version this platform was tested against.
          example:
            openclaw: 2.9.1
            claude-code: 1.13.0
            cursor: 1.9.0
            codex: 1.9.0
            claude-desktop: 0.4.0
            n8n: 1.2.1
            google-adk: 1.3.1
    SDKCompatInfo_2:
      type: object
      properties:
        min_sdk_version:
          type: object
          description: 'Minimum SDK version compatible with this platform, keyed by SDK

            language (e.g. go, python, typescript, java, rust)

            '
          additionalProperties:
            type: string
          example:
            python: 8.0.0
            typescript: 8.0.0
            go: 8.0.0
            java: 8.0.0
            rust: 0.7.0
        recommended_sdk_version:
          type: object
          description: 'Recommended SDK version for full feature coverage, keyed by SDK

            language

            '
          additionalProperties:
            type: string
          example:
            python: 9.4.0
            typescript: 9.4.0
            go: 9.4.0
            java: 9.4.0
            rust: 0.11.0
    HealthResponse_2:
      type: object
      description: 'Besides the component booleans, the health body always carries the

        platform capability list (`capabilities`), the per-language SDK

        version pins (`sdk_compatibility`) and the per-plugin version pins

        (`plugin_compatibility`). The pin maps are additionalProperties-style

        maps keyed by SDK language / canonical plugin id; the exact key sets

        evolve per release and are not enumerated here.

        '
      properties:
        status:
          type: string
          enum:
          - healthy
          - starting
          - unhealthy
        service:
          type: string
        version:
          type: string
          description: 'Platform version, preferring the value baked into the binary at

            build time and falling back to AXONFLOW_VERSION for dev builds

            '
          example: 9.8.0
        timestamp:
          type: string
          format: date-time
        capabilities:
          type: array
          description: List of platform capabilities with the version that introduced them
          items:
            $ref: '#/components/schemas/PlatformCapability'
        sdk_compatibility:
          $ref: '#/components/schemas/SDKCompatInfo_2'
        plugin_compatibility:
          $ref: '#/components/schemas/PluginCompatInfo_2'
        components:
          type: object
          properties:
            policy_engine:
              type: boolean
            llm_router:
              type: boolean
            response_processor:
              type: boolean
            audit_logger:
              type: boolean
            workflow_engine:
              type: boolean
            planning_engine:
              type: boolean
            result_aggregator:
              type: boolean
        features:
          type: object
          properties:
            multi_agent_planning:
              type: boolean
    PluginCompatInfo_2:
      type: object
      description: 'Plugin version pins, mirroring SDKCompatInfo. Keys are the canonical

        plugin ids (openclaw, claude-code, cursor, codex, claude-desktop,

        n8n, google-adk). Versions below the minimum receive a

        downgrade-warning header on every governed call.

        '
      properties:
        min_plugin_version:
          type: object
          additionalProperties:
            type: string
          description: Per-plugin minimum version compatible with this platform.
          example:
            openclaw: 2.4.0
            claude-code: 1.4.0
            cursor: 1.4.0
            codex: 1.4.0
            claude-desktop: 0.2.0
            n8n: 1.2.0
            google-adk: 1.2.0
        recommended_plugin_version:
          type: object
          additionalProperties:
            type: string
          description: Per-plugin version this platform was tested against.
          example:
            openclaw: 2.9.1
            claude-code: 1.13.0
            cursor: 1.9.0
            codex: 1.9.0
            claude-desktop: 0.4.0
            n8n: 1.2.1
            google-adk: 1.3.1
    SDKCompatInfo_3:
      type: object
      properties:
        min_sdk_version:
          type: object
          description: 'Minimum SDK version compatible with this platform, keyed by SDK

            language (e.g. go, python, typescript, java, rust)

            '
          additionalProperties:
            type: string
          example:
            python: 8.0.0
            typescript: 8.0.0
            go: 8.0.0
            java: 8.0.0
            rust: 0.7.0
        recommended_sdk_version:
          type: object
          description: 'Recommended SDK version for full feature coverage, keyed by SDK

            language

            '
          additionalProperties:
            type: string
          example:
            python: 9.4.0
            typescript: 9.4.0
            go: 9.4.0
            java: 9.4.0
            rust: 0.11.0
    HealthResponse_3:
      type: object
      description: 'Besides the component booleans, the health body always carries the

        platform capability list (`capabilities`), the per-language SDK

        version pins (`sdk_compatibility`) and the per-plugin version pins

        (`plugin_compatibility`). The pin maps are additionalProperties-style

        maps keyed by SDK language / canonical plugin id; the exact key sets

        evolve per release and are not enumerated here.

        '
      properties:
        status:
          type: string
          enum:
          - healthy
          - starting
          - unhealthy
        service:
          type: string
        version:
          type: string
          description: 'Platform version, preferring the value baked into the binary at

            build time and falling back to AXONFLOW_VERSION for dev builds

            '
          example: 9.8.0
        timestamp:
          type: string
          format: date-time
        capabilities:
          type: array
          description: List of platform capabilities with the version that introduced them
          items:
            $ref: '#/components/schemas/PlatformCapability'
        sdk_compatibility:
          $ref: '#/components/schemas/SDKCompatInfo_3'
        plugin_compatibility:
          $ref: '#/components/schemas/PluginCompatInfo_3'
        components:
          type: object
          properties:
            policy_engine:
              type: boolean
            llm_router:
              type: boolean
            response_processor:
              type: boolean
            audit_logger:
              type: boolean
            workflow_engine:
              type: boolean
            planning_engine:
              type: boolean
            result_aggregator:
              type: boolean
        features:
          type: object
          properties:
            multi_agent_planning:
              type: boolean
    PluginCompatInfo_3:
      type: object
      description: 'Plugin version pins, mirroring SDKCompatInfo. Keys are the canonical

        plugin ids (openclaw, claude-code, cursor, codex, claude-desktop,

        n8n, google-adk). Versions below the minimum receive a

        downgrade-warning header on every governed call.

        '
      properties:
        min_plugin_version:
          type: object
          additionalProperties:
            type: string
          description: Per-plugin minimum version compatible with this platform.
          example:
            openclaw: 2.4.0
            claude-code: 1.4.0
            cursor: 1.4.0
            codex: 1.4.0
            claude-desktop: 0.2.0
            n8n: 1.2.0
            google-adk: 1.2.0
        recommended_plugin_version:
          type: object
          additionalProperties:
            type: string
          description: Per-plugin version this platform was tested against.
          example:
            openclaw: 2.9.1
            claude-code: 1.13.0
            cursor: 1.9.0
            codex: 1.9.0
            claude-desktop: 0.4.0
            n8n: 1.2.1
            google-adk: 1.3.1
  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(`<client-id>@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