API Reference

REST API endpoints for the LockStock platform

Gateway Endpoints

The d3cipher Gateway exposes these endpoints on port 4000.

GET /healthz
Liveness probe. Returns 200 if the gateway is up and the d3cipher cloud is reachable, 503 if degraded. No authentication required — returns only status and version, no operational telemetry. 
curl http://gateway-host:4000/healthz
# {"status": "ok", "version": "4.6.2"}
GET /metrics
Prometheus-compatible metrics: request count, rejection count, latency per agent. Requires the Gateway Key (lsk_gateway_*) via Authorization: Bearer header. Returns 401 without a valid key. 
curl http://gateway-host:4000/metrics \
  -H "Authorization: Bearer $(liberty show LOCKSTOCK_GATEWAY_KEY)"

Supported Paths

Every path below is stamped, encrypted, and forwarded through the governance middleware. Identify the agent via the X-D3cipher-Agent header (or set AGENT_ID on the container for a default).

Path Task Type Provider
POST /v1/chat/completions CHATCOMPLETION OpenAI, Ollama, any OpenAI-compatible
POST /v1/messages CHATCOMPLETION Anthropic (native Messages API)
POST /v1/completions COMPLETION OpenAI
POST /v1/embeddings EMBEDDING OpenAI
POST /v1/images/generations IMAGEGENERATION OpenAI (DALL-E)
POST /v1/audio/transcriptions TRANSCRIPTION OpenAI (Whisper)
POST /v1/audio/speech TEXTTOSPEECH OpenAI (TTS)
GET /v1/models — Passthrough (not stamped)

Request and response are stamped separately (e.g., CHATCOMPLETION on the way in, CHATCOMPLETIONRESPONSE on the way out), so the chain records both sides of every conversation.

Three Provider Modes

The gateway resolves which provider each agent uses (from server settings or environment variables) and selects the right proxy automatically. Different agents can use different providers through the same gateway.

Mode Client Speaks Upstream Translation
openai (default) OpenAI Chat API OpenAI, Ollama, any compatible None — dumb forward proxy
anthropic-native Anthropic Messages API Anthropic None — passthrough. Beta headers merged and forwarded.
anthropic OpenAI Chat API Anthropic OpenAI → Anthropic on request, Anthropic → OpenAI on response

Examples

OpenAI — POST /v1/chat/completions
curl http://gateway-host:4000/v1/chat/completions \
  -H "Authorization: Bearer sk-your-openai-key" \
  -H "X-D3cipher-Agent: customer-support-bot" \
  -H "Content-Type: application/json" \
  -d '{"model": "gpt-4", "messages": [{"role": "user", "content": "Hello"}]}'
Anthropic Native — POST /v1/messages
For agents configured as anthropic-native. The gateway forwards the Anthropic Messages API as-is, stamps the request, and merges any anthropic-beta headers with the server config. 
curl http://gateway-host:4000/v1/messages \
  -H "x-api-key: sk-ant-your-anthropic-key" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: prompt-caching-2024-07-31" \
  -H "X-D3cipher-Agent: research-assistant" \
  -H "Content-Type: application/json" \
  -d '{"model": "claude-sonnet-4-20250514", "max_tokens": 1024,
       "messages": [{"role": "user", "content": "Hello"}]}'
Anthropic via OpenAI format — POST /v1/chat/completions
For agents configured as anthropic (translation mode). Your client sends OpenAI format, the gateway translates to Anthropic Messages API on the way in, and translates back on the way out. Your code doesn't change. 
curl http://gateway-host:4000/v1/chat/completions \
  -H "Authorization: Bearer sk-ant-your-anthropic-key" \
  -H "X-D3cipher-Agent: sales-agent" \
  -H "Content-Type: application/json" \
  -d '{"model": "claude-sonnet-4-20250514", "messages": [{"role": "user", "content": "Hello"}]}'

Dashboard API

Authenticated with the Admin Key (lsk_admin_*) via Authorization: Bearer header.

GET /api/guard/fleet
List all agents with status, sequence depth, velocity, and risk scores.
GET /api/guard/audit-logs?agent_id=...&limit=50
Retrieve audit log entries. Filter by agent, date range, event type.
POST /api/guard/agent/{id}/token-budget
Set or update the token budget for an agent. Body: {"budget": 100000}
POST /api/guard/circuit-breaker/override
Manually lock or unlock an agent's circuit breaker. Body: {"agent_id": "...", "action": "unlock"}
POST /v1/agents/provision
Provision a new agent. Returns agent_id and genesis token. Body: {"agent_name": "my-agent", "authorized_tasks": ["all"], "upstream_provider": "openai"}
upstream_provider defaults to "openai". Options: openai, anthropic-native, anthropic.
POST /v1/agents/claim
Claim a provisioned agent by burning the genesis token. Creates the chain genesis block and binds the agent to this machine's hardware fingerprint. Body: {"genesis_token": "...", "hardware_fingerprint": "..."}

Agent-to-Agent Endpoints

Endpoints for verified agent collaboration. Agents authenticate each other using their cryptographic chain identity.

POST /api/a2a/task
Submit a task from one agent to another. Both agents must belong to the same account. The server verifies the sending agent's chain identity before delivery. Both chains record the interaction for audit purposes.
POST /api/a2a/cross-link
Complete an agent-to-agent handshake. The receiving agent confirms task receipt by referencing the sender's chain head, creating mutual non-repudiation.
GET /v1/verify/{agent_id}
Verify an agent's chain credential. Returns status: current, stale, frozen, or revoked. Supports ?tolerance=N for handshake tolerance windows. No authentication required (credential tier is public).
GET /v1/agents/{agent_id}/card
Per-agent identity card with live chain metadata, gateway URL, and capabilities. Used for agent discovery in multi-agent workflows.

HTTP Status Codes

200 OK
Request stamped and forwarded successfully.
401 Unauthorized
Missing or invalid gateway key on an authenticated endpoint (/metrics, /cppn/*). Pass the Gateway Key via Authorization: Bearer header.
403 Forbidden
Gateway key (lsk_gateway_*) used on an admin-only endpoint (those require lsk_admin_*), or hardware fingerprint mismatch (stamp from unauthorized machine). Admin keys work on all endpoints.
409 Conflict
Chain hash mismatch. The agent's prev_hash doesn't match the server's last_hash. This means the chain has forked — a duplicate agent, a replay attempt, or a cloned credential. The stamp is rejected and the action is blocked. Investigate immediately.
429 Too Many Requests
Agent is locked (circuit breaker tripped, token budget exhausted, or manual lock). Unlock from dashboard.
503 Service Unavailable
d3cipher cloud unreachable. Check network connectivity.

Need help? Email hello@d3cipher.ai or view the Gateway Quickstart