REST API Reference

Base URL: https://api.adjudon.com/api/v1

All responses follow this envelope:

{
  "success": true,
  "data": {}
}

On error:

{
  "success": false,
  "error": "Human-readable message",
  "code": "ERROR_CODE"
}

---

Traces

POST /traces

Ingest a decision trace. This is the primary SDK endpoint.

Authentication: X-API-Key: adj_agent_abc123...

Request body:

{
  "inputContext": {
    "prompt": "What is the capital of France?",
    "systemPrompt": "You are a helpful assistant."
  },
  "outputDecision": {
    "action": "llm_response",
    "text": "Paris is the capital of France."
  },
  "metadata": {
    "model": "gpt-4o",
    "latency_ms": 342
  },
  "agentId": "my-agent",
  "confidence": 0.92,
  "rationale": "High-confidence factual response"
}

Field	Type	Required	Description
inputContext.prompt	string	Yes	The input the agent received
inputContext.systemPrompt	string	No	System prompt used
outputDecision.action	string	Yes	Action type (e.g. llm_response, tool_call)
outputDecision.text	string	Yes	The agent's output text
metadata	object	No	Arbitrary key-value pairs
agentId	string	No	Override the agent ID from the API key scope
confidence	number	No	Override confidence (0.0–1.0)
rationale	string	No	Human-readable explanation of the decision

Optional headers:

Header	Description
Idempotency-Key	Prevent duplicate traces (TTL: 24 hours)
X-Adjudon-Version	Pin to a schema version (e.g. 2026-04-11)

Response codes:

Status	Code	Meaning
201	—	Trace approved
202	ADJ_FLAGGED_FOR_REVIEW	Trace flagged, routed to review queue
403	ADJ_BLOCKED_BY_POLICY	Trace blocked by policy
409	ADJ_DUPLICATE_REQUEST	Duplicate idempotency key

201 response:

{
  "success": true,
  "data": {
    "id": "trace_abc123",
    "status": "approved",
    "confidence": 0.92,
    "message": "Trace approved"
  }
}

---

GET /traces

List traces. Paginated.

Authentication: Authorization: Bearer <jwt>

Query parameters:

Parameter	Type	Description
agentId	string	Filter by agent
status	string	Filter by status (approved, flagged, blocked)
from	ISO date	Start of date range
to	ISO date	End of date range
page	number	Page number (default: 1)
limit	number	Items per page (default: 20, max: 100)

---

GET /traces/:id

Get a specific trace by ID.

Authentication: Authorization: Bearer <jwt>

---

Agents

GET /agents

List all agents in the organization.

Authentication: Authorization: Bearer <jwt> or X-API-Key

---

POST /agents

Create a new agent.

Authentication: Authorization: Bearer <jwt>

{
  "name": "Customer Support Bot",
  "description": "Handles tier-1 customer support queries"
}

---

GET /agents/:id

Get agent details including analytics.

Authentication: Authorization: Bearer <jwt>

---

PATCH /agents/:id

Update agent name or description.

Authentication: Authorization: Bearer <jwt>

---

DELETE /agents/:id

Delete an agent. Associated traces are retained.

Authentication: Authorization: Bearer <jwt>

---

POST /agents/:id/regenerate-key

Rotate the agent's API key. The old key is immediately invalidated.

Authentication: Authorization: Bearer <jwt>

Response:

{
  "success": true,
  "data": {
    "apiKey": "adj_agent_newkey..."
  }
}

---

Policies

GET /policies

List all active policies.

Authentication: Authorization: Bearer <jwt>

---

POST /policies

Create a policy.

Authentication: Authorization: Bearer <jwt>

{
  "name": "Block PII in outputs",
  "description": "Block any trace containing PII in the output",
  "outcome": "block",
  "conditions": [...]
}

---

PATCH /policies/:id

Update a policy.

Authentication: Authorization: Bearer <jwt>

---

DELETE /policies/:id

Delete a policy.

Authentication: Authorization: Bearer <jwt>

---

GET /policies/templates

Get pre-built policy templates.

Authentication: Authorization: Bearer <jwt>

---

Review Queue

GET /review-queue

List pending review items. Paginated.

Authentication: Authorization: Bearer <jwt>

Query parameters: agentId, status, assignedTo, page, limit

---

POST /review-queue/:id/decision

Submit a review decision for a specific item.

Authentication: Authorization: Bearer <jwt>

{
  "decision": "approve",
  "notes": "Reviewed and confirmed safe"
}

Valid decision values: approve, reject, escalate

---

POST /review-queue/bulk-decision

Submit the same decision for multiple items.

Authentication: Authorization: Bearer <jwt>

{
  "ids": ["item_1", "item_2", "item_3"],
  "decision": "approve"
}

---

Webhooks

GET /webhooks

List all webhooks.

Authentication: Authorization: Bearer <jwt>

---

POST /webhooks

Create a webhook.

Authentication: Authorization: Bearer <jwt> or X-API-Key

{
  "url": "https://your-server.com/adjudon-webhook",
  "events": ["review.completed", "trace.blocked"],
  "filterAgentId": "my-agent"
}

---

PATCH /webhooks/:id

Update a webhook URL or events.

Authentication: Authorization: Bearer <jwt>

---

DELETE /webhooks/:id

Delete a webhook.

Authentication: Authorization: Bearer <jwt> or X-API-Key

---

Audit Log

GET /audit

Get audit log entries. Paginated.

Authentication: Authorization: Bearer <jwt>

Query parameters: from, to, eventType, userId, page, limit

---

GET /audit/verify

Verify the integrity of the SHA-256 hash chain.

Authentication: Authorization: Bearer <jwt>

Response:

{
  "success": true,
  "data": {
    "valid": true,
    "totalEntries": 4821,
    "firstEntry": "2026-01-01T00:00:00.000Z",
    "lastEntry": "2026-04-13T12:00:00.000Z"
  }
}

---

OTEL

POST /otel/v1/traces

Ingest OTLP/HTTP spans. Non-GenAI spans are silently dropped.

Authentication: X-API-Key: adj_agent_abc123...

Content-Type: application/json (OTLP JSON format)

Response: OTLP-compatible partialSuccess format.

---

Health

GET /health

Health check. No authentication required. Always responds in under 100ms.

{
  "status": "ok",
  "timestamp": "2026-04-13T12:00:00.000Z"
}