Skip to main content

REST API Reference

The Adjudon REST API is JSON over HTTPS, served from https://api.adjudon.com in Frankfurt eu-central-1. Every endpoint authenticates, every response uses the same envelope, and every mutating endpoint accepts an Idempotency-Key header. Tested against API version v1.

Base URL​

https://api.adjudon.com

All requests go to this host. There is no regional fan-out, no customer-cloud variant, and no on-premise install. See Architecture for the residency picture.

Versioning​

The canonical prefix is /api/v1. Every response on a versioned endpoint carries X-Adjudon-API-Version: v1. The unversioned legacy prefix /api/* is a 12-month alias that returns Deprecation: true plus a Sunset: 2027-04-12 header per RFC 8594. New integrations should use /api/v1 exclusively.

Versioned response headers
HTTP/1.1 200 OK
X-Adjudon-API-Version: v1
Content-Type: application/json
Legacy response headers
HTTP/1.1 200 OK
Deprecation: true
Sunset: 2027-04-12
Link: <https://docs.adjudon.com/migration/api-v1>; rel="deprecation"

Authentication​

Every endpoint except /health requires a credential. The two key formats are adj_live_<64 hex> for workspace-level access and adj_agent_<48 hex> for per-agent ingestion. Pass the key on the Authorization header (Bearer <key>) or the X-API-Key header. See Authentication for the format, rotation, and leak-recovery procedure.

Response envelope​

Success
{ "success": true, "data": { /* resource-shaped */ } }
Failure
{ "success": false, "error": "Entry not found", "code": "NOT_FOUND" }

The code field is a stable machine identifier; the error string is for humans and may change for clarity. See Error Codes for the full taxonomy.

Conventions​

  • Content type. Requests and responses are application/json with UTF-8 encoding. The trace-ingestion endpoint and a small number of upload endpoints accept multipart/form-data — per-resource pages note where this applies.
  • Timestamps. All timestamps are ISO 8601 UTC strings (2026-05-06T10:14:22.317Z).
  • Identifiers. MongoDB ObjectIds are 24-character lowercase hex. Trace identifiers are prefixed strings (trace_<random>); chain hashes are 64-character lowercase hex.
  • Booleans, numbers. JSON-native (true / false, IEEE-754). Confidence scores are 0.0&ndash;1.0 floats.
  • Empty values. A field that is logically empty is null, not an empty string. Lists default to [], not null.

Resource map​

GroupResources
CoreTraces, Hash Chain, Audit, Policies, Reviews, Agents, Webhooks, Alerts, Auto-Approval, Notifications
ComplianceIncidents, FRIA, Compliance Mapping, Compliance Overview, Deployer Profile, Federated, Provenance, C2PA KMS, Privacy Budget, GPAI, CPI Feedback
Account & AuthAuth, SCIM, Organizations, Team, Onboarding, Billing, Usage
AnalyticsAnalytics, Reports, MCP Servers

Cross-cutting​

Versioning policy​

The code field is a stable contract: codes are added, never renamed without a 90-day deprecation notice in the Changelog. The error string is not part of the contract. The canonical /api/v1 prefix is stable until a /api/v2 ships; the legacy unversioned /api/* paths sunset on 2027-04-12.