> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://natural.ferndocs.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://natural.ferndocs.com/_mcp/server.

# REST API

The Natural REST API lives at `https://api.natural.co`. Authenticate with a Bearer token in the `Authorization` header.

> **Note**
>
> Agents and coding assistants should prefer the [MCP server](/guides/platform/mcp) when an MCP-aware host runs the agent, the [CLI](/guides/platform/cli) for terminal/CI workflows, and the official [SDKs](/guides/platform/sdks) for application runtimes. Use direct HTTP only for explicit low-level integrations, unsupported SDK gaps, or infrastructure work where REST is required.

## Authentication

Include your API key in the `Authorization` header:

```bash
curl https://api.natural.co/agents \
  -H "Authorization: Bearer sk_ntl_prod_..."
```

## Request format

To create or update a resource, wrap your fields in `data.attributes`:

```json
{
  "data": {
    "attributes": {
      "amount": 500000,
      "currency": "USD",
      "counterparty": "vendor@example.com",
      "description": "Payment for Q4 work"
    }
  }
}
```

## Response format

Responses follow a JSON:API-inspired structure:

```json
{
  "data": {
    "type": "payment",
    "id": "pay_019cd1798d647b8ca12def456789abcd",
    "attributes": {
      "amount": 500000,
      "currency": "USD",
      "status": "COMPLETED"
    },
    "relationships": {
      "sourceParty": {
        "data": { "type": "party", "id": "pty_..." }
      }
    }
  }
}
```

## Pagination

List endpoints use cursor-based pagination:

```json
{
  "data": [...],
  "meta": {
    "pagination": {
      "hasMore": true,
      "nextCursor": "cursor_abc123"
    }
  }
}
```

Pass `?cursor=cursor_abc123` to fetch the next page.

## Idempotency

All write operations accept an `Idempotency-Key` header. If you retry a request with the same key, Natural returns the original response without re-executing the operation.

```bash
curl -X POST https://api.natural.co/payments \
  -H "Authorization: Bearer $NATURAL_API_TOKEN" \
  -H "Idempotency-Key: unique-key-here" \
  -H "Content-Type: application/json" \
  -d '{"data": {"attributes": {...}}}'
```

## Full reference

See the [API Reference](/api-reference) for complete endpoint documentation with request/response schemas.