HTTP API

HTTP API

Relevant source files

The following files were used as context for generating this wiki page:

• cmd/axis/degraded_contract_test.go
• cmd/axis/testdata/context_show_corrupt_state.golden
• cmd/axis/testdata/skills_corrupt_store.golden
• cmd/axis/testdata/status_turboquant_json.golden
• internal/api/degraded_contract_test.go
• internal/api/server.go
• internal/api/server_test.go
• internal/api/testdata/knowledge_corrupt_persistence.golden
• internal/api/testdata/knowledge_turboquant.golden
• internal/api/turboquant_contract_test.go
• internal/api/v2.go
• internal/mcp/testdata/cluster_snapshot_turboquant.golden
• internal/mcp/testdata/placement_decision_turboquant.golden
• internal/mcp/turboquant_contract_test.go
• internal/persist/recovery_test.go

The AXIS HTTP API provides a REST-like interface for interacting with the cluster daemon. It exposes the current cluster state, allows for task execution via the placement engine, and provides diagnostic endpoints for monitoring cluster health. The server supports both Unix domain sockets (default for local CLI communication) and TCP listeners.

Server Architecture and Lifecycle

The API server is initialized via ServeWithContext, which handles the lifecycle of the listener and provides graceful shutdown logic internal/api/server.go:115-178. By default, AXIS uses a Unix socket located at ~/.axis/axis.sock internal/api/server.go:30-33.

Data Flow and Dependency Injection

The server relies on the snapshotCache interface to access the latest ClusterSnapshot, Metadata, and Ledger without directly triggering expensive discovery processes unless requested internal/api/server.go:91-98.

Title: API Server Component Interaction

graph TD
    subgraph "API Server [internal/api]"
        ServeWithContext["ServeWithContext()"]
        Mux["http.ServeMux"]
        V1["v1 Handlers"]
        V2["v2 Handlers [v2Handlers]"]
    end

    subgraph "State Providers"
        Cache["snapshotCache (Interface)"]
        Daemon["Daemon Cache [internal/daemon]"]
        Ledger["Reservation Ledger [internal/reservation]"]
    end

    ServeWithContext --> Mux
    Mux --> V1
    Mux --> V2
    V1 --> Cache
    V2 --> Cache
    Cache -.-> Daemon
    Cache -.-> Ledger

Loading

Sources: internal/api/server.go:115-126, internal/api/server.go:91-98, internal/api/v2.go:35-37

Authentication

Authentication is implemented via a Bearer token mechanism in the withAuth middleware internal/api/server.go:180-206.

• Token Comparison: Uses subtle.ConstantTimeCompare to prevent timing attacks internal/api/server.go:199-202.
• Requirement: If a token is configured, all routes except /health and /healthz require the Authorization: Bearer <token> header internal/api/server.go:180-185, internal/api/server.go:209-223.

V1 API Routes (Legacy & Core)

The V1 routes provide the primary interface for high-level operations like execution and snapshot retrieval.

Route	Method	Description
/health	GET	Basic liveness check. Returns version and ready status internal/api/server.go:209-221.
/snapshot	GET	Returns the full ClusterSnapshot JSON internal/api/server.go:224-226.
/knowledge	GET	Aggregates ClusterKnowledge, LearnedSkills, and LearnedFailures internal/api/server.go:45-49.
/tools	GET	Returns available MCP-compatible tools (e.g., axis_execute) internal/api/server_test.go:138-154.
/run	POST	Triggers RunGuarded. Supports streaming NDJSON for execution logs internal/api/server.go:51-81.

Sources: internal/api/server.go:208-228, internal/api/server_test.go:120-154

V2 API Routes (Structured State)

V2 routes, managed by the v2Handlers struct, provide more granular access to cluster resources and support batch operations internal/api/v2.go:19-37.

Cluster and Node Inspection

• /v2/cluster: Returns a summary of the cluster, including healthy/degraded node counts and aggregate RAM/GPU totals internal/api/v2.go:47-58, internal/api/v2.go:60-97.
• /v2/nodes: Returns a list of all nodes with hardware facts and epistemic state internal/api/v2.go:99-110, internal/api/v2.go:112-160.
• /v2/nodes/{name}: Detailed facts for a specific node internal/api/v2.go:162-179.

Resource Management

• /v2/reservations:
  • GET: Lists active entries in the reservation.Ledger internal/api/v2.go:197-209.
  • POST: Manually creates a reservation (requires node and ram_mb) internal/api/v2.go:210-237.
• /v2/batch/place: Accepts multiple task requirements and returns a placement plan without executing internal/api/v2.go:31.

Diagnostics

• /v2/doctor: Triggers a diagnostic run to identify connectivity issues or resource exhaustion internal/api/v2.go:32.
• /v2/metrics: Exposes internal performance counters internal/api/v2.go:29.

Sources: internal/api/v2.go:19-33, internal/api/v2.go:47-97, internal/api/v2.go:181-237

Execution and Streaming

The /run endpoint facilitates guarded execution. It accepts a RunRequest containing a natural language description of the task internal/api/server.go:51-55.

Execution Flow

1. Intent Resolution: The request description is parsed into requirements.
2. Placement: The engine selects the best node based on the snapshot.
3. Guarded Run: execution.RunGuarded is called internal/api/server.go:106.
4. Output: Results are returned in a RunResponse containing execution IDs, exit codes, and resource observations (Peak RAM, Wall Time) internal/api/server.go:57-81.

Title: Execution Request Mapping

sequenceDiagram
    participant Client
    participant Server as internal/api/server.go
    participant Guard as execution.RunGuarded
    participant Ledger as reservation.Ledger

    Client->>Server: POST /run {description: "..."}
    Server->>Guard: Invoke with context
    Guard->>Ledger: Request Reservation
    Ledger-->>Guard: Reservation Granted
    Guard->>Client: Stream NDJSON (Progress)
    Guard-->>Server: Final RunResponse
    Server->>Client: 200 OK {RunResponse}

Loading

Sources: internal/api/server.go:51-81, internal/api/server.go:106

Diagnostic and Knowledge Endpoints

The Doctor Endpoint

The /v2/doctor route performs a comprehensive check of the cluster's health. It validates:

• Snapshot freshness.
• SSH connectivity to remote nodes.
• Local persistence integrity (e.g., checking for quarantined/corrupt state.json files) internal/api/degraded_contract_test.go:26-57.

Knowledge and TurboQuant

The /knowledge endpoint provides the AI Advisory layer with the necessary context for decision making. This includes TurboQuant capabilities, which indicate if a node supports optimized LLM inference (e.g., Apple Silicon unified memory or specific llama.cpp backends) internal/api/testdata/knowledge_turboquant.golden:36-48.

Sources: internal/api/v2.go:32, internal/api/degraded_contract_test.go:59-98, internal/api/testdata/knowledge_turboquant.golden:1-76

---