AxioRank Gateway API

openapi: 3.2.0
info:
  title: AxioRank Gateway API
  version: 1.0.0
  description: 'The runtime governance API behind every AxioRank SDK. Call it directly from any language. All requests authenticate with a bearer token and send/receive JSON.


    The SDKs (`@axiorank/sdk`, `axiorank` on PyPI) are thin wrappers over these endpoints. The canonical base path is `/api/v1`; the unversioned `/api/...` paths remain as aliases.'
  contact:
    name: AxioRank
    url: https://axiorank.com
servers:
- url: https://app.axiorank.com
  description: Production
security:
- bearerAuth: []
tags:
- name: Gateway
paths:
  /api/v1/gateway/tool-call:
    post:
      operationId: scoreToolCall
      summary: Score a tool call
      description: Inspect an outbound agent tool call, score its risk, apply your policies, and return a decision. Requires the `gateway:write` scope. When a `require_approval` policy fires the decision is `hold` and an `approvalId` is returned. Poll `GET /api/gateway/approvals/{approvalId}` for the resolution.
      security:
      - bearerAuth: []
      parameters:
      - name: Idempotency-Key
        in: header
        required: false
        schema:
          type: string
          maxLength: 255
        description: 'Optional. Safely retry a write: the first response for a given key is replayed on retries (24h TTL). A concurrent retry gets 409; reusing a key with a different body gets 422.'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ToolCallRequest'
      responses:
        '200':
          description: The governance decision.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ToolCallResponse'
        '400':
          description: Malformed request body.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Missing or invalid API key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '402':
          description: Workspace monthly usage quota exceeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: A request with this Idempotency-Key is already in progress.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Idempotency-Key was reused with a different request body.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Rate limited.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          headers:
            Retry-After:
              schema:
                type: integer
              description: Seconds to wait before retrying.
      tags:
      - Gateway
  /api/v1/gateway/approvals/{approvalId}:
    get:
      operationId: pollApproval
      summary: Poll a held tool call
      description: 'When a tool call returns `decision: "hold"`, poll this endpoint with the `approvalId` until a human resolves it. The server long-polls (~8s per request), so polling is cheap. Authenticate with the SAME agent key that made the call; another agent''s holds return an opaque 404.'
      security:
      - bearerAuth: []
      parameters:
      - name: approvalId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: The current approval state. `decision` stays `hold` while pending.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApprovalStatusResponse'
        '401':
          description: Missing or invalid API key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Unknown approval, or not owned by this agent.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      tags:
      - Gateway
  /api/v1/gateway/verify-card:
    post:
      operationId: verifyCard
      summary: Preflight an external agent/server
      description: Verify an external MCP server / A2A agent card before trusting it. Supply EITHER a `url` to fetch the card from OR an inline `document` (one is required). Returns the resolved identity (signature validity, key domain-binding), declared capabilities, auth, and a decision. Requires the `cards:verify` scope.
      security:
      - bearerAuth: []
      parameters:
      - name: Idempotency-Key
        in: header
        required: false
        schema:
          type: string
          maxLength: 255
        description: 'Optional. Safely retry a write: the first response for a given key is replayed on retries (24h TTL). A concurrent retry gets 409; reusing a key with a different body gets 422.'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/VerifyCardRequest'
      responses:
        '200':
          description: The preflight verdict.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CardVerifyResponse'
        '400':
          description: Malformed body, or neither `url` nor `document` supplied.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Missing or invalid API key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '402':
          description: Workspace monthly usage quota exceeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: A request with this Idempotency-Key is already in progress.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Idempotency-Key was reused with a different request body.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Rate limited.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      tags:
      - Gateway
  /api/v1/gateway/verify-request:
    post:
      operationId: verifyRequest
      summary: Verify an inbound agent request
      description: Verify an inbound agent request against a property's site key (bot management). The `axioGuard` middleware builds this call for you. Authenticate with an `axr_site_…` key (scope `inbound:verify`); the visiting agent's own HTTP Message Signature travels inside the body, not in this call's auth.
      security:
      - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InboundVerifyRequest'
      responses:
        '200':
          description: The inbound decision (`allow` | `challenge` | `block`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InboundVerifyResponse'
        '400':
          description: Malformed request body.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Missing or invalid site key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      tags:
      - Gateway
  /api/v1/gateway/token:
    post:
      operationId: exchangeToken
      summary: Exchange for a short-lived token
      description: 'Exchange a long-lived credential for a short-lived, scoped `axr_tok_…` token (tokens can only NARROW scopes, never widen them). Two grants: **key exchange**, present an `axr_live_`/`axr_test_` key in the `Authorization` header; **federated**, present a platform OIDC token as `subject_token` in the body (no AxioRank secret stored on the agent).'
      security:
      - bearerAuth: []
      - {}
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TokenExchangeRequest'
      responses:
        '200':
          description: The minted token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TokenResponse'
        '400':
          description: Malformed body or invalid `subject_token`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Missing or invalid credential.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Requested scopes are not permitted by the credential.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      tags:
      - Gateway
  /api/v1/gateway/mcp-tool-call:
    post:
      operationId: evaluateMcpToolCall
      summary: Verdict for a proxied MCP tools/call
      description: 'Lightweight verdict endpoint the local stdio shim (`@axiorank/mcp-gateway`) calls per `tools/call`. `server` is the registered server slug. `phase: "request"` inspects the call arguments; `phase: "result"` inspects the tool output and requires `resultText`. Requires the `gateway:write` scope.'
      security:
      - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/McpToolCallRequest'
      responses:
        '200':
          description: The verdict for this call.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/McpToolCallVerdict'
        '400':
          description: Malformed request body.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Missing or invalid API key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Unknown MCP server slug for this agent.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      tags:
      - Gateway
components:
  schemas:
    ErrorResponse:
      type: object
      properties:
        error:
          type: string
      required:
      - error
    InboundVerifyRequest:
      type: object
      properties:
        surfaceKind:
          default: website
          type: string
          enum:
          - website
          - http_api
          - mcp_server
          - a2a_agent
          - webhook
          - shopify
        operation:
          anyOf:
          - type: string
            maxLength: 512
          - type: 'null'
        method:
          anyOf:
          - type: string
            minLength: 1
            maxLength: 16
          - type: 'null'
        authority:
          anyOf:
          - type: string
            minLength: 1
            maxLength: 255
          - type: 'null'
        path:
          anyOf:
          - type: string
            minLength: 1
            maxLength: 2048
          - type: 'null'
        query:
          default: ''
          type: string
          maxLength: 4096
        userAgent:
          anyOf:
          - type: string
            maxLength: 2048
          - type: 'null'
        clientIp:
          anyOf:
          - type: string
            maxLength: 64
          - type: 'null'
        signatureInput:
          anyOf:
          - type: string
            maxLength: 8192
          - type: 'null'
        signature:
          anyOf:
          - type: string
            maxLength: 8192
          - type: 'null'
        signatureAgent:
          anyOf:
          - type: string
            maxLength: 2048
          - type: 'null'
        headers:
          default: {}
          type: object
          propertyNames:
            type: string
          additionalProperties:
            type: string
        bodySample:
          anyOf:
          - type: string
            maxLength: 65536
          - type: 'null'
        agentCard: {}
        agentCardUrl:
          anyOf:
          - type: string
            maxLength: 2048
          - type: 'null'
        authToken:
          anyOf:
          - type: string
            maxLength: 8192
          - type: 'null'
        governancePassport: {}
        reputationCredential: {}
    InboundVerifyResponse:
      type: object
      properties:
        decision:
          type: string
          enum:
          - allow
          - challenge
          - block
        reason:
          type: string
        risk:
          type: integer
          minimum: 0
          maximum: 100
        verification:
          type: object
          properties:
            status:
              type: string
              enum:
              - verified
              - unverified
              - spoofed
              - unknown
            method:
              type:
              - string
              - 'null'
            agentSlug:
              type:
              - string
              - 'null'
            agentLabel:
              type:
              - string
              - 'null'
            confidence:
              type: integer
              minimum: 0
              maximum: 100
              description: '0..100: cryptographic proof = 100, heuristic UA match = 40, etc.'
          required:
          - status
          - method
          - agentSlug
          - agentLabel
          - confidence
        enforced:
          type: boolean
          description: 'false under `monitor` posture: the verdict was computed + logged, not acted on.'
        signals:
          type: array
          items:
            $ref: '#/components/schemas/RiskSignal'
        requestId:
          type: string
      required:
      - decision
      - reason
      - risk
      - verification
      - enforced
      - signals
      - requestId
    ToolCallResponse:
      type: object
      properties:
        decision:
          type: string
          enum:
          - allow
          - deny
          - hold
        reason:
          type: string
        risk:
          type: integer
          minimum: 0
          maximum: 100
        auditLogId:
          type: string
        signals:
          type: array
          items:
            $ref: '#/components/schemas/RiskSignal'
        approvalId:
          type: string
          description: Present ONLY when decision is `hold`. Poll GET /api/gateway/approvals/{id}.
        ifc:
          type: boolean
          description: True when this workspace enforces information-flow control. The SDK uses it to decide whether to report untrusted tool results (phase="result") for taint tracking.
      required:
      - decision
      - reason
      - risk
      - auditLogId
      - signals
    McpToolCallRequest:
      type: object
      properties:
        server:
          type: string
          minLength: 1
          maxLength: 64
        tool:
          type: string
          minLength: 1
          maxLength: 200
        arguments:
          default: {}
          type: object
          propertyNames:
            type: string
          additionalProperties: {}
        phase:
          default: request
          type: string
          enum:
          - request
          - result
        resultText:
          type: string
          maxLength: 200000
        costUsd:
          type: number
          minimum: 0
          maximum: 1000000
        traceId:
          type: string
          format: uuid
          pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
        stepIndex:
          type: integer
          minimum: 0
          maximum: 100000
        sessionId:
          type: string
          format: uuid
          pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
        metadata:
          type: object
          propertyNames:
            type: string
            minLength: 1
            maxLength: 64
          additionalProperties:
            anyOf:
            - type: string
              maxLength: 256
            - type: number
            - type: boolean
        parentStepIndex:
          type: integer
          minimum: 0
          maximum: 100000
      required:
      - server
      - tool
    CardVerifyResponse:
      type: object
      properties:
        decision:
          type: string
          enum:
          - allow
          - review
          - deny
        reason:
          type: string
        risk:
          type: integer
          minimum: 0
          maximum: 100
        protocol:
          type: string
          description: Resolved protocol of the card (a2a, mcp, oauth, …).
        identity:
          type: object
          properties:
            name:
              type:
              - string
              - 'null'
            provider:
              type:
              - string
              - 'null'
            signed:
              type: boolean
            signatureValid:
              type:
              - boolean
              - 'null'
              description: true = verified · false = forged · null = unsigned / key unresolvable.
            keySource:
              type: string
              enum:
              - embedded
              - jwks
              - none
            keyDomainBound:
              type: boolean
            keyId:
              type:
              - string
              - 'null'
            sourceUrl:
              type: string
          required:
          - name
          - provider
          - signed
          - signatureValid
          - keySource
          - keyDomainBound
          - keyId
          - sourceUrl
        capabilities:
          type: object
          properties:
            count:
              type: integer
            sample:
              type: array
              items:
                type: object
                properties:
                  kind:
                    type: string
                  name:
                    type: string
                required:
                - kind
                - name
          required:
          - count
          - sample
        auth:
          type: object
          properties:
            schemes:
              type: array
              items:
                type: string
            protectedResource:
              type: boolean
          required:
          - schemes
          - protectedResource
        warnings:
          type: array
          items:
            type: string
        signals:
          type: array
          items:
            $ref: '#/components/schemas/RiskSignal'
        cardId:
          type: string
      required:
      - decision
      - reason
      - risk
      - protocol
      - identity
      - capabilities
      - auth
      - warnings
      - signals
      - cardId
    ToolCallRequest:
      type: object
      properties:
        tool:
          type: string
          minLength: 1
          maxLength: 200
        arguments:
          default: {}
          type: object
          propertyNames:
            type: string
          additionalProperties: {}
        phase:
          default: request
          type: string
          enum:
          - request
          - result
          - prompt
          - completion
        resultText:
          type: string
          maxLength: 200000
        promptText:
          type: string
          maxLength: 200000
        completionText:
          type: string
          maxLength: 200000
        context:
          type: string
          maxLength: 200000
        costUsd:
          type: number
          minimum: 0
          maximum: 1000000
        model:
          type: string
          minLength: 1
          maxLength: 200
        inputTokens:
          type: integer
          minimum: 0
          maximum: 100000000
        outputTokens:
          type: integer
          minimum: 0
          maximum: 100000000
        durationMs:
          type: integer
          minimum: 0
          maximum: 86400000
        intent:
          type: string
          minLength: 1
          maxLength: 1000
        taintHandle:
          type: string
          maxLength: 16384
        passport:
          type: boolean
        source:
          type: string
          enum:
          - sdk
          - mcp
          - coding-agent
          - browser-agent
        traceId:
          type: string
          format: uuid
          pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
        stepIndex:
          type: integer
          minimum: 0
          maximum: 100000
        sessionId:
          type: string
          format: uuid
          pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
        metadata:
          type: object
          propertyNames:
            type: string
            minLength: 1
            maxLength: 64
          additionalProperties:
            anyOf:
            - type: string
              maxLength: 256
            - type: number
            - type: boolean
        parentStepIndex:
          type: integer
          minimum: 0
          maximum: 100000
      required:
      - tool
    TokenExchangeRequest:
      type: object
      properties:
        grant_type:
          type: string
          enum:
          - api_key
          - federated
        subject_token:
          type: string
          minLength: 1
        ttl_seconds:
          type: integer
          exclusiveMinimum: 0
          maximum: 3600
        scopes:
          type: array
          items:
            type: string
      additionalProperties: false
    McpToolCallVerdict:
      type: object
      properties:
        decision:
          type: string
          enum:
          - allow
          - deny
          - hold
        reason:
          type: string
        risk:
          type: integer
          minimum: 0
          maximum: 100
        auditLogId:
          type: string
        signals:
          type: array
          items:
            $ref: '#/components/schemas/RiskSignal'
        enforced:
          type: boolean
          description: true when the call must NOT be forwarded as-is under `enforce` posture.
        approvalId:
          type: string
          description: Present when decision is `hold` under enforce.
      required:
      - decision
      - reason
      - risk
      - auditLogId
      - signals
      - enforced
    RiskSignal:
      type: object
      description: A redacted content-inspection finding that contributed to the risk score.
      properties:
        detector:
          type: string
          examples:
          - secret.aws_access_key
        category:
          type: string
          enum:
          - secret
          - pii
          - destructive
          - injection
          - egress
          - bot_spoof
          - rate_abuse
          - supply_chain
        severity:
          type: string
          enum:
          - low
          - medium
          - high
          - critical
        label:
          type: string
        points:
          type: integer
          description: Pre-diminishing-returns contribution, from severity.
        location:
          type: string
          examples:
          - body.env.AWS_SECRET
          - (tool_name)
        evidence:
          type: string
          description: Redacted evidence, safe to persist and display.
        critical:
          type: boolean
          description: A live secret / key / card was detected.
      required:
      - detector
      - category
      - severity
      - label
      - points
      - location
      - evidence
    ApprovalStatusResponse:
      type: object
      properties:
        status:
          type: string
          description: 'Approval state: `pending` while awaiting a human; `approved`/`denied` once resolved; `expired` on timeout.'
        decision:
          type: string
          enum:
          - allow
          - deny
          - hold
          description: '`hold` while still pending; resolves to `allow`/`deny`.'
        reason:
          type:
          - string
          - 'null'
        auditLogId:
          type:
          - string
          - 'null'
        resolvedBy:
          type:
          - string
          - 'null'
          description: Operator who resolved the hold, if any.
      required:
      - status
      - decision
    VerifyCardRequest:
      type: object
      properties:
        url:
          type: string
          maxLength: 2048
          format: uri
        document: {}
        protocol:
          type: string
          enum:
          - a2a
          - mcp
          - oauth
          - api-catalog
          - x402
          - acp
          - ucp
          - mpp
          - did
          - acp-comm
          - anp
          - agntcy-slim
          - authmd
          - ap2
          - content-permission
          - agntcy-directory
          - nlweb
          - ans
          - agent-skills
          - webmcp
          - nanda
          - vc
          - visa-tap
          - spiffe
          - agents-json
          - l402
          - oid4vci
          - authzen
          - mc-agent-pay
          - visa-intelligent-commerce
          - skyfire
          - nekuda
          - amex-agent-pay
          - paypal-agentic-checkout
    TokenResponse:
      type: object
      properties:
        token:
          type: string
          description: A short-lived `axr_tok_…` bearer token.
        token_type:
          type: string
          enum:
          - Bearer
        expires_at:
          type: string
          format: date-time
        expires_in:
          type: integer
          description: Lifetime in seconds.
        scopes:
          type: array
          items:
            type: string
      required:
      - token
      - token_type
      - expires_at
      - expires_in
      - scopes
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: 'An AxioRank API key (`axr_live_…` agent key or `axr_site_…` property key) or a short-lived token (`axr_tok_…`). Sent as `Authorization: Bearer <key>`. Scopes: `gateway:write`, `cards:verify`, `inbound:verify`, `logs:read`, `admin`.'