Agents API

The Agents API lets you register agents, retrieve agent details, update configuration, and manage agent state programmatically.

Base URL

https://amp.nomotic.ai/api/v1/agents

All requests require an Authorization header with your API key:

Authorization: Bearer nm_live_your_key_here

List agents

GET /api/v1/agents

Returns all agents in your organization. Optional query parameters:

status — filter by status: active, inactive, retired.

zone — filter by zone: sandbox, staging, production.

limit — number of results per page (default 20, max 100).

cursor — pagination cursor from the previous response.

Get agent

GET /api/v1/agents/{agent_id}

Returns full details for a single agent including certificate, archetype, trust score, last evaluation timestamp, and configuration.

Register agent

POST /api/v1/agents

Request body:

json

{
  "name": "customer-support-agent",
  "description": "Handles customer support queries",
  "zone": "sandbox",
  "archetype": "customer-support",
  "metadata": {
    "team": "support",
    "version": "1.0.0"
  }
}

Returns the new agent including its ID and certificate details.

Update agent

PATCH /api/v1/agents/{agent_id}

Accepts any subset of the registration fields. Returns the updated agent.

Update agent zone

POST /api/v1/agents/{agent_id}/promote

Request body: { "zone": "staging" } or { "zone": "production" }.

Promoting to production triggers a governance verification check. If the agent does not meet the threshold, the response includes the reason and the promotion is not applied.

Retire agent

POST /api/v1/agents/{agent_id}/retire

Revokes the agent’s certificate and sets its status to Retired. The audit trail is preserved.

Response format

All responses follow a consistent shape:

json

{
  "id": "agent_abc123",
  "name": "customer-support-agent",
  "status": "active",
  "zone": "sandbox",
  "archetype": "customer-support",
  "trust_score": 0.847,
  "created_at": "2026-04-01T10:00:00Z",
  "last_evaluated_at": "2026-04-11T14:30:00Z"
}