agt_*) you have created, inspect one, rename it, or revoke it when it is done. For every field and status of an agent, see The Agent object.
Before you start, connect Natural to your agent or create an API key. See Start here. Setup takes a couple of minutes; the MCP path needs no API key.
If an MCP host is operating Natural for you, use the MCP example. The linked API reference has
per-language samples and a playground.
List your agents
List every agent on your account withGET /agents.
handle, status, and limits:
Inspect one agent
Inspect one agent by ID withGET /agents/{agentId}.
Rename an agent
Rename an agent, change its description, or adjust its limits, withPATCH /agents/{agentId}. Set limits from a user session or party API key; an agent key cannot change its own limits. limits: null clears them.
Revoke an agent
Revoke an agent withDELETE /agents/{agentId}. Its status becomes REVOKED and it stops moving money at once, but the record stays readable so its history survives. Revoking also revokes every customer authorization the agent holds and cancels its pending invitations.
status REVOKED:
Manage agent keys
An agent key (ak_ntl_*) is a credential bound to one agent. Your dashboard lists keys on the agent detail page; over the API, use the agent-keys endpoints below. Issue a new key when you create an agent.
List keys
There is no get-by-id endpoint. List keys withGET /agent-keys (scope apiKeys.read), optionally filtered by agentId.
Rotate a key
Rotate withPOST /agent-keys/{keyId}/rotate to issue a fresh secret on the same agent. Set a grace period so running workloads can pick up the new key before the old one stops working. The new secret is again shown once. Rotate and revoke from a user session, as when issuing; $NATURAL_USER_TOKEN in the cURL examples is that session credential, the same one natural login stores for the CLI. expiresInSeconds runs from 0 (immediate) to 86400.
Revoke a key
Revoke withDELETE /agent-keys/{keyId} to invalidate a key immediately. This cannot be undone, and other keys on the same agent keep working. Use it when a secret leaks or you retire one credential without revoking the agent.