REST API | Natural Docs

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

Agents and coding assistants should prefer the MCP server when an MCP-aware host runs the agent, the CLI for terminal/CI workflows, and the official 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:

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:

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

Response format

Responses follow a JSON:API-inspired structure:

{
  "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:

{
  "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.

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 for complete endpoint documentation with request/response schemas.