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

# 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. We use JSON:API to specify how our servers should respond to requests, and use a modified structure described below in order to specify how
requests should be made to our servers.

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

## Requests

To create or update a resource, wrap your fields in `data.attributes`. No `type`, `id`, or `relationships` needed — the type is inferred from the endpoint and the ID is assigned by the server.

### Creating a resource

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

```json theme={null}
// POST /api/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 /api/agents/{agentId}
{
  "data": {
    "attributes": {
      "name": "Carrier Payment Agent v3.0"
    }
  }
}
```

## Responses

Responses follow the [JSON:API specification](https://jsonapi.org/). Resources may be singular or be comprised of lists, and each resource in a response 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",
      "status": "ACTIVE",
      "createdAt": "2026-01-04T15:30:00Z",
      "createdBy": "usr_019cd1798d657de5b5fed4198cb9fac0",
      "updatedAt": "2026-01-04T15:30:00Z",
      "updatedBy": "usr_019cd1798d657de5b5fed4198cb9fac0"
    },
    "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",
        "createdAt": "2026-01-04T15:30:00Z"
      },
      "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 only in **responses**. In requests, reference related resources by including their ID directly in `attributes` (e.g., `customerPartyId`).

### To-one relationships

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

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

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

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

### Common relationships

| Relationship       | Description                            | Found on                |
| ------------------ | -------------------------------------- | ----------------------- |
| `party`            | Owning party                           | Agents, Wallet Balances |
| `sender`           | Party that initiated the payment       | Payments                |
| `recipient`        | Recipient party for the payment        | Payments                |
| `sourceParty`      | Originating party                      | Transactions            |
| `destinationParty` | Receiving party                        | Transactions            |
| `payment`          | Payment that produced the transaction  | Transactions            |
| `transfer`         | Transfer that produced the transaction | 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": {
  "customerParty": {
    "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`.