AXIS Documentation / Integration / API Reference

API Reference

VerifiedBase URL: http://localhost:6543

Complete endpoint reference for the AXIS HTTP API. Unless noted, endpoints are unauthenticated in v1 (operator-token endpoints require X-AXIS-Operator-Token or Authorization: Bearer <token>).

POST /query — execute SQL through AXIS

Request

{
  "actor": "demo-ops",          // required: identity (unverified in v1)
  "app": "demo-batch",          // required
  "tenant": "acme",             // required
  "role": "app_ops",            // required
  "host": "localhost",          // required
  "env": "prod",                // required: shadow | staging | prod
  "sql": "UPDATE ...",          // required
  "session_id": "s-123",        // optional: prepared-statement session
  "approval_id": "ap-456",      // optional: retry after approval
  "execution_profile": "latency" // optional
}

Responses:

Status	Meaning	Body highlights
`200`	Allowed and executed (or preview/dry-run result)	`decision: ALLOW`, `execution_state`, `rows`, `fingerprint`, `policy_version`
`202`	REQUIRE_APPROVAL — no execution	`decision: REQUIRE_APPROVAL`, `approval_id`, `reason_code`, `approval_expires_at`
`403`	Blocked — no execution	`decision: BLOCK`, `reason_code`, `policy_version`, classification details
`4xx/5xx`	Controlled failure	Structured error: `error_code`, `message`, `error_id`

Query parameters supported on POST /query: mode (live, preview), sql (optional when body has SQL), idempotency_key. In preview mode AXIS returns classification + decision without executing (would_execute: false, audit_written: false).

Approvals

Endpoint	Auth	Behavior
`GET /approvals`	none	List approvals with filters (`status`, `env`, `app`, `actor`)
`GET /approvals/<approval_id>`	none	Single approval details: SQL, classification, status, expires_at, resolved_at
`POST /approvals/<approval_id>/resolve`	operator token	Immutable resolve: `{"decision": "approve"\|"reject", "note": "..."}`; writes evidence before response
`POST /approvals/purge`	operator token	Purge expired approvals

Policy lifecycle

Endpoint	Auth	Behavior
`GET /policy/status`	none	`loaded`, `policy_version`, path, rule count, `operator_auth_enabled`
`GET /policy/versions`	none	Version list with statuses (active / candidate / archived / rejected)
`POST /policy/validate`	none	Structural + semantic validation; warnings; no side effects
`POST /policy/diff`	none	Rule-level diff between versions
`POST /policy/dry-run`	none	Decision preview: SQL + context → decision, reason, fingerprint, rule trace
`POST /policy/candidates`	operator token	Create immutable candidate version
`POST /policy/activate`	operator token	Activate candidate (expected_hash must match)
`POST /policy/rollback`	operator token	Roll back to archived valid version

Audit & evidence

Endpoint	Auth	Behavior
`GET /audit`	none	List audit events (filter by event_type, fingerprint, actor, etc.)
`POST /audit/verify`	none	Hash-chain verification of a specified audit file
`POST /audit/evidence`	none	Range export: `bundle_type: axis.evidence_bundle.v1`, optional Ed25519 signature
`GET /audit/evidence/signing-public-key`	none	Public key for local verification of signed bundles
`GET /evidence/verify`	none	Full-chain integrity verification of the WAL

Runtime & operations

Endpoint	Behavior
`GET /health`	Liveness: `{"status": "ok", "version": "...", "uptime_seconds": N}`; non-ok on startup chain failure
`GET /runtime/stats`	Uptime, version, total requests, per-query-type counts, policy version, approvals pending/resolved, health check counter
`GET /logs`	Bounded in-memory operational log buffer (query params `level`, `source`, `limit`) — not durable proof

Control Plane API surface

The Control Plane proxies /api/axis/* server-side: health, logs, runtime/stats, approvals, policy status/versions, audit/evidence, and admin login. The browser never receives the backend URL or operator token.

Error shape

Errors are structured: {"error_code": "...", "message": "...", "error_id": "..."}. Common codes: invalid_json, empty_sql, multi_statement_rejected, parser_error, parser_unsupported_syntax, unsupported_sql_shape, unsafe_read_shape, rate_limit_exceeded, approval_not_found, approval_expired, approval_rejected, policy_not_loaded, db_connection_failed. See the Error Codes reference.