> ## 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.

# About the Natural API

> Understanding the structure of Natural API requests and responses

The Natural API is REST-based and follows a simplified [JSON:API](https://jsonapi.org/) structure.

REST requests authenticate with a Natural API key in the `Authorization: Bearer` header. See [Authentication](/api-reference/authentication). The same key works in the [SDKs](/guides/platform/sdks), the [CLI](/guides/platform/cli), and as an MCP fallback. For AI hosts operating Natural for a user, prefer [MCP](/guides/platform/mcp) with OAuth.

## Requests

To create or update a resource, wrap your fields in `data.attributes`. Omit `type` and `id`: the endpoint implies the type and Natural assigns the ID.

### Creating a resource

Send a `POST` request with a `data` object containing `attributes`:

```json theme={null}
// POST /payments
{
  "data": {
    "attributes": {
      "amount": 500000,
      "currency": "USD",
      "counterparty": {
        "type": "email",
        "value": "carrier@example.com"
      },
      "customerPartyId": "pty_019cd1798d617f65a79cb965dda9eac3",
      "description": "Payment for Q4 2025 development work"
    }
  }
}
```

### Updating a resource

To update a resource, send a `PATCH` request with only the fields you want to change inside `attributes`. Omitted fields remain unchanged.

```json theme={null}
// PATCH /agents/{agentId}
{
  "data": {
    "attributes": {
      "name": "Carrier Payment Agent v3.0"
    }
  }
}
```

## Responses

Responses follow the [JSON:API specification](https://jsonapi.org/). A response contains a single resource or a list of resources, and each resource has:

* **`type`**: A string identifying the kind of resource (e.g., `"agent"`, `"payment"`, `"transaction"`)
* **`id`**: A unique [prefixed identifier](/api-reference/IDs) (e.g., `agt_019cd179...`, `pay_019cd179...`)
* **`attributes`**: The resource's data fields
* **`relationships`** *(optional)*: Links to related resources

### Single resource

Responses for a single resource wrap the resource in a `data` object:

```json theme={null}
{
  "data": {
    "type": "agent",
    "id": "agt_019cd1798d637a4da75dce386343931d",
    "attributes": {
      "name": "Carrier Payment Agent v2.1",
      "description": "Autonomous agent that pays delivery carriers",
      "tags": {},
      "handle": "@natural-carrier_payments",
      "status": "ACTIVE",
      "limits": {
        "perTransaction": 100000
      },
      "createdAt": "2026-01-04T15:30:00.000Z",
      "createdBy": "usr_019cd1798d657de5b5fed4198cb9fac0",
      "lastActiveAt": "2026-01-05T09:12:00.000Z"
    },
    "relationships": {
      "party": {
        "data": {
          "type": "party",
          "id": "pty_019cd1798d617f65a79cb965dda9eac3"
        }
      }
    }
  }
}
```

### List of resources

List endpoints return an array of resources in `data`, with pagination metadata in `meta`:

```json theme={null}
{
  "data": [
    {
      "type": "transaction",
      "id": "txn_019cd1798d6672a7b828eee780291b72",
      "attributes": {
        "amount": 100000,
        "currency": "USD",
        "status": "COMPLETED",
        "transactionType": "payment",
        "direction": "OUTBOUND",
        "description": "Payment for Q4 2025 development work",
        "createdAt": "2026-01-04T15:30:00.000Z",
        "updatedAt": "2026-01-04T15:31:00.000Z",
        "expectedAvailableAt": null
      },
      "relationships": {
        "sourceParty": {
          "data": { "type": "party", "id": "pty_019cd1798d617f65a79cb965dda9eac3" }
        },
        "destinationParty": {
          "data": { "type": "party", "id": "pty_019cd1798d627ad9bc302511c4f2c115" }
        }
      }
    }
  ],
  "meta": {
    "pagination": {
      "hasMore": false,
      "nextCursor": null
    }
  }
}
```

Use the `nextCursor` value from `meta.pagination` to fetch subsequent pages.

## Relationships

Relationships connect resources to each other without nesting the full related resource. Each relationship contains a `data` object with the related resource's `type` and `id`.

Relationships appear in **responses**. In requests, reference related resources by including their ID directly in `attributes` (e.g., `customerPartyId`); the one exception is [`POST /agent-keys`](/api-reference/agent-keys/create-agent-key), which takes its agent as a request relationship.

### To-one relationships

A to-one relationship links to a single related resource:

```json theme={null}
"sender": {
  "data": {
    "type": "party",
    "id": "pty_019cd1798d617f65a79cb965dda9eac3"
  }
}
```

A `null` value in `data` indicates the relationship is absent:

```json theme={null}
"sourceParty": {
  "data": null
}
```

### Common relationships

| Relationship | Description | Found on |
| - | - | - |
| `party` | Owning party | Agents, Wallets |
| `sender` | Party that initiated the payment | Payments |
| `recipient` | Recipient party for the payment | Payments |
| `senderAgent` | Agent that sent the payment | Payments |
| `recipientAgent` | Agent that received the payment | Payments |
| `transaction` | Ledger entry for the payment | Payments |
| `paymentRequest` | Request the payment fulfilled | Payments |
| `sourceParty` | Originating party | Transactions |
| `destinationParty` | Receiving party | Transactions |
| `payment` | Payment that produced the transaction | Transactions |
| `cardPayment` | Card payment that produced the transaction | Transactions |
| `transfer` | Transfer that produced the transaction | Transactions |
| `wallet` | Wallet the entry posted to | Transactions |

### Using relationship IDs

Use the `type` and `id` from a relationship to fetch the related resource. For example, if a payment response includes:

```json theme={null}
"relationships": {
  "recipient": {
    "data": { "type": "party", "id": "pty_019cd1798d617f65a79cb965dda9eac3" }
  }
}
```

You can look up the party using its ID in a subsequent request.

## Glossary

* **Resource**: An entity in the Natural API, such as a payment, agent, or transaction.
* **Attribute**: A piece of information about a resource (e.g., `status`, `amount`, `createdAt`).
* **Relationship**: A link from one resource to another, represented by `type` and `id`.


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