> ## Documentation Index
> Fetch the complete documentation index at: https://docs.natural.com/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> When building application code, use `@naturalpay/sdk` for TypeScript or `naturalpay` for Python.
> When operating Natural directly for a user, use the payments MCP at `https://mcp.natural.com`.
> When searching Natural documentation, use the docs MCP at `https://docs.natural.com/mcp`.
> Use the Natural CLI for terminal and CI automation.
> Use REST only for unsupported languages or when the user explicitly requests raw HTTP.
> Start integration development and testing in the sandbox. Do not use production unless the user explicitly requests it.
> For sandbox requests that require `customerPartyId`, list customers first. Reuse only the intended fixture; otherwise create a customer.
> REST and SDK amounts use integer minor units. Payments MCP amounts use decimal strings with a required currency code.

# Manage your agents

> List and edit your agents

See every agent (`agt_*`) you have created, inspect one, rename it, or revoke it when it is done. For how agents fit with keys and limits, read the [Agents overview](/guides/concepts/agents).

<Snippet file="shared/prerequisites.mdx" />

<Snippet file="shared/mcp-callout.mdx" />

## List your agents

List every agent on your account with [`GET /agents`](/api-reference/agents/list-agents).

<CodeGroup>
  ```python Python theme={null}
  from naturalpay import Natural

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

  ```typescript TypeScript theme={null}
  import Natural from "@naturalpay/sdk";

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

  ```bash CLI theme={null}
  natural agents list
  ```

  ```text MCP theme={null}
  List my agents.
  ```

  ```bash cURL theme={null}
  curl https://api.natural.com/agents \
    -H "Authorization: Bearer $NATURAL_API_KEY"
  ```
</CodeGroup>

The response carries each agent with its `handle`, `status`, and `limits`:

<Snippet file="api-examples/agents.list.response.mdx" />

## Inspect one agent

Inspect one agent by ID with [`GET /agents/{agentId}`](/api-reference/agents/get-agent).

<CodeGroup>
  ```python Python theme={null}
  agent = client.agents.get("agt_019cd1798d637a4da75dce386343931d")
  ```

  ```typescript TypeScript theme={null}
  const agent = await client.agents.get({
    agentId: "agt_019cd1798d637a4da75dce386343931d",
  });
  ```

  ```bash CLI theme={null}
  natural agents get --agent-id agt_019cd1798d637a4da75dce386343931d
  ```

  ```text MCP theme={null}
  Show me my Procurement Agent.
  ```

  ```bash cURL theme={null}
  curl https://api.natural.com/agents/agt_019cd1798d637a4da75dce386343931d \
    -H "Authorization: Bearer $NATURAL_API_KEY"
  ```
</CodeGroup>

The response carries the agent:

<Snippet file="api-examples/agents.get.response.mdx" />

## Rename an agent

Rename an agent, change its description, or adjust its [limits](/guides/controls/limits), with [`PATCH /agents/{agentId}`](/api-reference/agents/update-agent). Set `limits` from a user session or party API key; an agent key cannot change its own limits. `limits: null` clears them.

<CodeGroup>
  ```python Python theme={null}
  import uuid

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

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

  ```bash CLI theme={null}
  natural agents update --agent-id agt_019cd1798d637a4da75dce386343931d \
    --name "Procurement Agent v2.1" \
    --description "Autonomous agent that pays contractors" \
    --idempotency-key "$(uuidgen)"
  ```

  ```bash cURL theme={null}
  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"
        }
      }
    }'
  ```
</CodeGroup>

The response carries the updated agent:

<Snippet file="api-examples/agents.update.response.mdx" />

## Revoke an agent

Revoke an agent with [`DELETE /agents/{agentId}`](/api-reference/agents/delete-agent). 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.

<CodeGroup>
  ```python Python theme={null}
  import uuid

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

  ```typescript TypeScript theme={null}
  await client.agents.remove({
    agentId: "agt_019cd1798d637a4da75dce386343931d",
    idempotencyKey: crypto.randomUUID(),
  });
  ```

  ```bash CLI theme={null}
  natural agents remove --agent-id agt_019cd1798d637a4da75dce386343931d \
    --idempotency-key "$(uuidgen)"
  ```

  ```bash cURL theme={null}
  curl -X DELETE https://api.natural.com/agents/agt_019cd1798d637a4da75dce386343931d \
    -H "Authorization: Bearer $NATURAL_API_KEY" \
    -H "Idempotency-Key: $(uuidgen)"
  ```
</CodeGroup>

The response carries the agent with `status` `REVOKED`:

<Snippet file="api-examples/agents.remove.response.mdx" />

## 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](/guides/agents/create-agent#issue-a-key).

### List keys

There is no get-by-id endpoint. List keys with [`GET /agent-keys`](/api-reference/agent-keys/list-agent-keys) (scope `api_keys.read`), optionally filtered by `agentId`.

<CodeGroup>
  ```python Python theme={null}
  keys = client.agent_keys.list(agent_id="agt_019cd1798d637a4da75dce386343931d")
  ```

  ```typescript TypeScript theme={null}
  const keys = await client.agentKeys.list({ agentId: "agt_019cd1798d637a4da75dce386343931d" });
  ```

  ```bash CLI theme={null}
  natural agent-keys list --agent-id agt_019cd1798d637a4da75dce386343931d
  ```

  ```bash cURL theme={null}
  curl "https://api.natural.com/agent-keys?agentId=agt_019cd1798d637a4da75dce386343931d" \
    -H "Authorization: Bearer $NATURAL_USER_TOKEN"
  ```
</CodeGroup>

### Rotate a key

Rotate with [`POST /agent-keys/{keyId}/rotate`](/api-reference/agent-keys/rotate-agent-key) 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.

<CodeGroup>
  ```python Python theme={null}
  import uuid

  rotated = client.agent_keys.rotate(
      key_id="agk_019cd1798d6d1353281cf4cdf5d20c8d",
      expires_in_seconds=86400,
      idempotency_key=str(uuid.uuid4()),
  )
  ```

  ```typescript TypeScript theme={null}
  const rotated = await client.agentKeys.rotate({
    keyId: "agk_019cd1798d6d1353281cf4cdf5d20c8d",
    expiresInSeconds: 86400,
    idempotencyKey: crypto.randomUUID(),
  });
  ```

  ```bash CLI theme={null}
  natural agent-keys rotate \
    --key-id agk_019cd1798d6d1353281cf4cdf5d20c8d \
    --expires-in-seconds 86400 \
    --idempotency-key "$(uuidgen)"
  ```

  ```bash cURL theme={null}
  curl -X POST https://api.natural.com/agent-keys/agk_019cd1798d6d1353281cf4cdf5d20c8d/rotate \
    -H "Authorization: Bearer $NATURAL_USER_TOKEN" \
    -H "Idempotency-Key: $(uuidgen)" \
    -H "Content-Type: application/json" \
    -d '{ "data": { "attributes": { "expiresInSeconds": 86400 } } }'
  ```
</CodeGroup>

### Revoke a key

Revoke with [`DELETE /agent-keys/{keyId}`](/api-reference/agent-keys/revoke-agent-key) 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.

<CodeGroup>
  ```python Python theme={null}
  import uuid

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

  ```typescript TypeScript theme={null}
  await client.agentKeys.revoke({
    keyId: "agk_019cd1798d6d1353281cf4cdf5d20c8d",
    idempotencyKey: crypto.randomUUID(),
  });
  ```

  ```bash CLI theme={null}
  natural agent-keys revoke \
    --key-id agk_019cd1798d6d1353281cf4cdf5d20c8d \
    --idempotency-key "$(uuidgen)"
  ```

  ```bash cURL theme={null}
  curl -X DELETE https://api.natural.com/agent-keys/agk_019cd1798d6d1353281cf4cdf5d20c8d \
    -H "Authorization: Bearer $NATURAL_USER_TOKEN" \
    -H "Idempotency-Key: $(uuidgen)"
  ```
</CodeGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.