API Reference

The canonical API specification is the interactive OpenAPI document served by AgentLattice itself. This page covers the conceptual layer that an OpenAPI spec cannot express: authentication patterns, idempotency semantics, response code subtleties, and behaviors that trip up developers in practice.

Authentication

All API requests require a Bearer token in the Authorization header:

Authorization: Bearer al_live_your_key_here

Keys are generated per agent in the AgentLattice dashboard. Each key is SHA-256 hashed at rest. The raw key is shown once at creation time. If you lose it, generate a new one.

Base URL and Content Type

Base URL:    https://www.agentlattice.io/api/v1
Content-Type: application/json

All request and response bodies are JSON. Endpoints that accept a body reject non-JSON content types with a 415 error.

Error Format

Every error response follows the same shape:

{
  "error": {
    "code": "POLICY_DENIED",
    "message": "Action denied by policy: production-safety"
  }
}

The code field is a stable machine-readable string. The message field is human-readable and may change between releases. Parse code, display message.

Idempotency

The API has two separate idempotency mechanisms. They serve different purposes and should not be confused.

Replay protection for actions. When submitting an action via POST /actions, include an X-AL-Event-ID HTTP header. If AgentLattice has already processed an action with the same event ID for this agent, it returns the original result instead of creating a duplicate audit event. Use this to make retries safe after network failures.

Upsert for outcome reports. When reporting an outcome via POST /report, the audit_event_id identifies which audit event you are reporting on. Calling report multiple times for the same audit_event_id overwrites the previous outcome with last-write-wins semantics. There is no conflict error. See Outcome Reporting for details on the silent overwrite behavior.

Endpoint Inventory

All 15 endpoints, grouped by domain. SDK method names link to their full documentation.

Core

Delegation

Policy Manifest

Both endpoints require a service key (Authorization: Bearer al_svc_...), not an agent API key. See Environment Promotion for the full GitOps workflow.

Introspection & Governance

Endpoints marked — in the TypeScript column are accessible via direct HTTP calls. The Python SDK has full coverage of all endpoints.

Key Behaviors

These are the behaviors that catch developers in integration. Read these before writing your first API call.

POST /actions returns 200 or 202

Most actions return 200 with an immediate policy decision (executed or denied). But if the action matches an approval-required policy, the response is 202 with status pending_approval. The action is not yet authorized. Your agent must wait for an operator to approve or deny it.

If your code only checks for 200, you will silently skip the approval flow. Handle both.

const res = await fetch("/api/v1/actions", { method: "POST", body, headers });

if (res.status === 200) {
  const { status, audit_event_id } = await res.json();
  // status is "executed" or "denied"
} else if (res.status === 202) {
  const { status, audit_event_id } = await res.json();
  // status is "requested" — poll or wait for webhook
}

GET /audit/verify is agent-authenticated, returns org-level data

The /audit/verify endpoint authenticates with the calling agent's API key (like all endpoints), but the verification result covers the entire workspace's audit hash chain, not just the calling agent's events. This is by design: chain integrity is a workspace-level property, and any authenticated agent should be able to verify it.

GET /policies/check is a dry run

/policies/check evaluates a hypothetical action against current policies without creating an audit event and without triggering an approval request. Use it to preview what would happen before committing to the action. The response shape matches /actions but no side effects occur.

Webhook management is MCP-only

There are no REST endpoints for creating, listing, or deleting webhook subscriptions. Webhook management is performed through MCP tools. This keeps the REST API focused on agent-to-platform communication while management operations go through the operator-facing MCP interface.

Circuit Breaker States

The circuit breaker governs an agent's operational status. These are the six possible states:

The GET /agent/status endpoint returns the current state and, for CALIBRATING agents, the calibration progress percentage.

Interactive Spec

The live OpenAPI specification is served at:

https://www.agentlattice.io/api/v1/openapi

This is the canonical, always-current source for request/response schemas, parameter types, and example payloads. Use it for code generation, Postman imports, or as a reference alongside this page.

The Python SDK (pip install agentlattice) has full Tier 2 parity. All methods listed above are available as both async and sync variants (e.g., await al.posture() or al.posture_sync()). See the Python SDK reference for usage examples.