Manage your agents

See every agent you have created, inspect one, rename it, or revoke it when it is done.

List your agents

List every agent on your account with GET /agents.

from naturalpay import Natural

client = Natural()
agents = client.agents.list()

import Natural from "@naturalpay/sdk";

const client = new Natural();
const agents = await client.agents.list();

natural agents list

List my agents.

curl https://api.natural.com/agents \
  -H "Authorization: Bearer $NATURAL_API_KEY"

Inspect one agent

Inspect one agent by ID with GET /agents/{agentId}.

agent = client.agents.get("agt_019cd1798d637a4da75dce386343931d")

const agent = await client.agents.get({
  agentId: "agt_019cd1798d637a4da75dce386343931d",
});

natural agents get --agent-id agt_019cd1798d637a4da75dce386343931d

Show me my Procurement Agent.

curl https://api.natural.com/agents/agt_019cd1798d637a4da75dce386343931d \
  -H "Authorization: Bearer $NATURAL_API_KEY"

Rename an agent

Rename an agent, change its description, or adjust its limits, with PATCH /agents/{agentId}.

import uuid

agent = client.agents.update(
    "agt_019cd1798d637a4da75dce386343931d",
    idempotency_key=str(uuid.uuid4()),
    name="Procurement Agent v2.1",
    description="Autonomous agent that pays contractors",
)

const agent = await client.agents.update({
  agentId: "agt_019cd1798d637a4da75dce386343931d",
  idempotencyKey: crypto.randomUUID(),
  name: "Procurement Agent v2.1",
  description: "Autonomous agent that pays contractors",
});

natural agents update --agent-id agt_019cd1798d637a4da75dce386343931d \
  --name "Procurement Agent v2.1" \
  --description "Autonomous agent that pays contractors" \
  --idempotency-key "$(uuidgen)"

curl -X PATCH https://api.natural.com/agents/agt_019cd1798d637a4da75dce386343931d \
  -H "Authorization: Bearer $NATURAL_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "data": {
      "attributes": {
        "name": "Procurement Agent v2.1",
        "description": "Autonomous agent that pays contractors"
      }
    }
  }'

Revoke an agent

Revoke an agent with DELETE /agents/{agentId}. Its status becomes REVOKED and it stops moving money at once, but the record stays readable so its history survives.

import uuid

client.agents.remove(
    "agt_019cd1798d637a4da75dce386343931d",
    idempotency_key=str(uuid.uuid4()),
)

await client.agents.remove({
  agentId: "agt_019cd1798d637a4da75dce386343931d",
  idempotencyKey: crypto.randomUUID(),
});

natural agents remove --agent-id agt_019cd1798d637a4da75dce386343931d \
  --idempotency-key "$(uuidgen)"

curl -X DELETE https://api.natural.com/agents/agt_019cd1798d637a4da75dce386343931d \
  -H "Authorization: Bearer $NATURAL_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)"

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 with GET /agent-keys, optionally filtered by agent.

keys = client.agent_keys.list(agent_id="agt_019cd1798d637a4da75dce386343931d")

const keys = await client.agentKeys.list({ agentId: "agt_019cd1798d637a4da75dce386343931d" });

natural agent-keys list --agent-id agt_019cd1798d637a4da75dce386343931d

curl "https://api.natural.com/agent-keys?agentId=agt_019cd1798d637a4da75dce386343931d" \
  -H "Authorization: Bearer $NATURAL_USER_TOKEN"

Rotate a key

Rotate with POST /agent-keys/{keyId}/rotate to mint 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.

import uuid

rotated = client.agent_keys.rotate(
    key_id="agk_550e8400e29b41d4a716446655440000",
    data={"attributes": {"expiresInSeconds": 86400}},
    idempotency_key=str(uuid.uuid4()),
)

const rotated = await client.agentKeys.rotate({
  keyId: "agk_550e8400e29b41d4a716446655440000",
  data: { attributes: { expiresInSeconds: 86400 } },
  idempotencyKey: crypto.randomUUID(),
});

natural agent-keys rotate \
  --key-id agk_550e8400e29b41d4a716446655440000 \
  --expires-in-seconds 86400 \
  --idempotency-key "$(uuidgen)"

curl -X POST https://api.natural.com/agent-keys/agk_550e8400e29b41d4a716446655440000/rotate \
  -H "Authorization: Bearer $NATURAL_USER_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{ "data": { "attributes": { "expiresInSeconds": 86400 } } }'

Revoke a key

Revoke with DELETE /agent-keys/{keyId} to invalidate a key immediately. This cannot be undone, and other keys on the same agent keep working. Reach for it when a secret leaks or you are retiring one credential without archiving the agent.

import uuid

client.agent_keys.revoke(
    key_id="agk_550e8400e29b41d4a716446655440000",
    idempotency_key=str(uuid.uuid4()),
)

await client.agentKeys.revoke({
  keyId: "agk_550e8400e29b41d4a716446655440000",
  idempotencyKey: crypto.randomUUID(),
});

natural agent-keys revoke \
  --key-id agk_550e8400e29b41d4a716446655440000 \
  --idempotency-key "$(uuidgen)"

curl -X DELETE https://api.natural.com/agent-keys/agk_550e8400e29b41d4a716446655440000 \
  -H "Authorization: Bearer $NATURAL_USER_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)"

Overview

Common use cases

Products

Guides

List your agents

Inspect one agent

Rename an agent

Revoke an agent

Agent keys

List keys

Rotate a key

Revoke a key

​List your agents

​Inspect one agent

​Rename an agent

​Revoke an agent

​Agent keys

​List keys

​Rotate a key

​Revoke a key

List your agents

Inspect one agent

Rename an agent

Revoke an agent

Agent keys

List keys

Rotate a key

Revoke a key