Agents

An Agent is one logical AI agent registered to your organisation — a customer-support bot, a credit-underwriting model, a diagnostic-imaging triage. Each agent carries its own API key (adj_agent_<48-hex>), its own policy overrides, its own status-health rollup, and (Phase 2) its own CycloneDX 1.7 ML-BOM. The agent record is what the traceId → agentId → organizationId isolation chain (Cardinal Rule 1) hangs from on every ingested decision. Tested against API version v1. JWT auth on every endpoint; mutations require the admin or owner role.

The Agent object

Field	Type	Required	Description
_id / id	string	yes	MongoDB ObjectId
name	string	yes	Operator-readable name; max 100 characters
description	string	no	Free-form context; max 500 characters
apiKey	string	yes	Hashed server-side; never returned by GET
apiKeyPrefix	string	no	Last 8 characters of the raw key, safe for display
apiKeyAgentScope	string	no	Immutable snapshot of name at key-creation time; used by the auth middleware to scope the key
status	enum	no	healthy (default), degraded, critical — auto-rolled by trace ingestion
isActive	boolean	no	true by default; false excludes the agent from analytics rollups
policies	object	no	Per-agent policy overrides (see below)
lastActive	string (ISO 8601)	no	Last observed trace ingestion
modelMetadata	object	no	Phase 2 ML-BOM source-of-truth; see below
organizationId / workspaceId	string	yes	Tenancy scope (Cardinal Rule 1: chains never mix across tenants)
createdAt / updatedAt	string (ISO 8601)	no	Standard timestamps

policies sub-document

Field	Type	Default	Description
strictMode	boolean	false	Stricter Confidence-Engine thresholds
logPayloads	boolean	true	Persist inputContext/outputDecision (still PII-scrubbed)
piiMasking	boolean	true	Apply the additional PII scrubber pass
autoBlockAnomalies	boolean	false	Engine-flagged anomalies auto-block (vs. only flag)
confidenceThreshold	number	0.8	Per-agent override of the Confidence-Engine cut-off
maxRequestsPerMinute	number	600	Per-agent rate limit
timeoutMs	number	5000	Per-agent ingestion timeout

modelMetadata (Phase 2 — ML-BOM)

CycloneDX 1.7 ML-BOM source-of-truth. Populated when you want machine-readable model accountability per agent. Fields: provider, model, version, license, riskClass, purpose, trainingDataSummary, datasets[] (each: name, uri, license, sha256, description), lastBomDigest, lastBomGeneratedAt. Adjudon never stores the training data itself — only opaque references.

Endpoints

GET     /api/v1/agents
POST    /api/v1/agents
GET     /api/v1/agents/:id
PATCH   /api/v1/agents/:id
DELETE  /api/v1/agents/:id
POST    /api/v1/agents/:id/regenerate-key

GET     /api/v1/agents/:id/versions
GET     /api/v1/agents/:id/analytics
PATCH   /api/v1/agents/:id/policies

GET     /api/v1/agents/:id/ml-bom
POST    /api/v1/agents/:id/ml-bom/refresh

GET     /api/v1/agents/onboarding/draft
PATCH   /api/v1/agents/:id/onboarding
POST    /api/v1/agents/:id/onboarding/complete
DELETE  /api/v1/agents/:id/onboarding

Create an agent

POST /api/v1/agents

Body field	Required	Description
name	yes	Trimmed; max 100 characters
description	no	Trimmed; max 500 characters
onboarding	no	Truthy starts the agent in onboardingProgress.currentStep: 1

curl

curl -X POST https://api.adjudon.com/api/v1/agents \
  -H "Authorization: Bearer $ADJUDON_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "underwriter-v1", "description": "Credit decline screening" }'

Response (201 Created):

{
  "success": true,
  "data": {
    "_id":             "65b1f2c4...",
    "name":            "underwriter-v1",
    "apiKey":          "adj_agent_<48-hex-shown-once>",
    "apiKeyPrefix":    "...a3f9c2d1",
    "status":          "healthy",
    "createdAt":       "2026-05-06T10:14:22.317Z"
  }
}

The raw apiKey appears once on the create response. Subsequent GET responses return the agent without the key (only the apiKeyPrefix). Lose it and you rotate via POST /:id/regenerate-key. Errors: 400 ADJ_VALIDATION_FAILED, 401, 403 (role), 500 INTERNAL_ERROR.

List, get, update, delete

curl — list

curl https://api.adjudon.com/api/v1/agents \
  -H "Authorization: Bearer $ADJUDON_API_KEY"

curl — get one

curl https://api.adjudon.com/api/v1/agents/65b1f2c4 \
  -H "Authorization: Bearer $ADJUDON_API_KEY"

curl — update name + description

curl -X PATCH https://api.adjudon.com/api/v1/agents/65b1f2c4 \
  -H "Authorization: Bearer $ADJUDON_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "underwriter-v2", "description": "Updated 2026-Q2" }'

DELETE is a soft-delete via softDelete plugin: the row stays in the database; subsequent GET responses exclude it; the agent.delete audit-log entry remains by Cardinal Rule 5.

Errors per endpoint: 401, 403 (role on mutations), 404 NOT_FOUND, 400 ADJ_VALIDATION_FAILED (over-length name/description), 500.

Regenerate the API key

POST /api/v1/agents/:id/regenerate-key

Mints a new adj_agent_<48-hex> key, invalidates the old one immediately, and writes a agent.regenerate_key audit-log entry. The new raw key is returned once on this response.

curl

curl -X POST https://api.adjudon.com/api/v1/agents/65b1f2c4/regenerate-key \
  -H "Authorization: Bearer $ADJUDON_API_KEY"

Errors: 401, 404 NOT_FOUND, 500.

Update agent policies

PATCH /api/v1/agents/:id/policies

Update one or more fields of the policies sub-document (strictMode, logPayloads, piiMasking, autoBlockAnomalies, confidenceThreshold, maxRequestsPerMinute, timeoutMs). Omitted fields keep their current values.

curl

curl -X PATCH https://api.adjudon.com/api/v1/agents/65b1f2c4/policies \
  -H "Authorization: Bearer $ADJUDON_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "confidenceThreshold": 0.9, "autoBlockAnomalies": true }'

Errors: 401, 404, 500.

Versions and analytics

GET /api/v1/agents/:id/versions
GET /api/v1/agents/:id/analytics

/versions returns a chronological list of agentVersion strings seen across the agent's traces; useful for surfacing model-pin drift in the dashboard. /analytics returns aggregate counters (total traces, blocked, flagged, approved) for the agent's lifetime.

ML-BOM (CycloneDX 1.7)

GET   /api/v1/agents/:id/ml-bom
POST  /api/v1/agents/:id/ml-bom/refresh

Returns the CycloneDX 1.7 ML-BOM JSON for the agent — provider, model, version, training-data references, BOM URN, and SHA-256 digest. Generated on demand from modelMetadata. The refresh endpoint recomputes and persists the digest after a metadata change. Errors: 401, 403 (role on refresh), 404 NOT_FOUND, 500.

Onboarding draft endpoints

GET     /api/v1/agents/onboarding/draft
PATCH   /api/v1/agents/:id/onboarding
POST    /api/v1/agents/:id/onboarding/complete
DELETE  /api/v1/agents/:id/onboarding

Persistent state for the dashboard's three-step agent-onboarding wizard (Name & Description → Pick Integration → Connect & Verify). GET /onboarding/draft returns the user's resumable draft or { agent: null } — no auto-create on read. Designed for dashboard use; SDK consumers create agents directly via POST /agents and skip this surface.

Common gotchas

• apiKey is shown once. On create and on regenerate-key, the raw key appears in the response body. Subsequent GET calls return only the apiKeyPrefix (last 8 characters). Store the raw key in a secret manager at the moment of creation; rotate via regenerate-key if lost.
• apiKeyAgentScope is immutable. A renamed agent keeps its original apiKeyAgentScope. The auth middleware uses this snapshot to scope the key, so existing keys keep working when you rename an agent.
• Soft-delete is the default. A deleted agent is invisible to GET but persists in the database; the audit-log entry remains. There is no restore endpoint — recreate.
• Onboarding draft is dashboard-scoped. The four onboarding endpoints power the wizard UI and are not part of the typical SDK integration path.
• Idempotency. The Idempotency-Key middleware is wired only on POST /traces today; create / regenerate-key on this resource do not auto-receive idempotency keys.

See also

• Authentication — the adj_agent_* key format and rotation procedure
• Traces API — the ingestion path every agent calls
• Policies API — org-level policies (per-agent overrides live in this resource's policies sub-document)
• Error Codes — the full error taxonomy
• Audit Log API — where agent.create, agent.regenerate_key, and agent.delete events land