About the Natural API

The Natural API is REST-based and follows a simplified JSON:API structure. REST requests authenticate with a Natural API key in the Authorization: Bearer header. See Authentication. The same key works across the SDKs, the CLI, and MCP fallback paths. For AI hosts operating Natural for a user, prefer the MCP connector with OAuth.

Requests

To create or update a resource, wrap your fields in data.attributes. No type or id 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:

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

// PATCH /agents/{agentId}
{
  "data": {
    "attributes": {
      "name": "Carrier Payment Agent v3.0"
    }
  }
}

Responses

Responses follow the JSON:API specification. 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 (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:

{
  "data": {
    "type": "agent",
    "id": "agt_019cd1798d637a4da75dce386343931d",
    "attributes": {
      "name": "Carrier Payment Agent v2.1",
      "description": "Autonomous agent that pays delivery carriers",
      "handle": "@natural-carrier_payments",
      "status": "ACTIVE",
      "limits": {
        "perTransaction": 100000
      },
      "createdAt": "2026-01-04T15:30:00Z",
      "createdBy": "usr_019cd1798d657de5b5fed4198cb9fac0",
      "lastActiveAt": "2026-01-05T09:12:00Z"
    },
    "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:

{
  "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:00Z",
        "updatedAt": "2026-01-04T15:31:00Z",
        "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, which takes its agent as a request relationship.

To-one relationships

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

"sender": {
  "data": {
    "type": "party",
    "id": "pty_019cd1798d617f65a79cb965dda9eac3"
  }
}

A null value in data indicates the relationship is absent:

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

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

Overview

Agents

Customers

Payments

Transactions

Transfers

Payment Requests

Approvals

Limits

Parties

Party Invitations

Wallets

Wallet Access

External Accounts

API keys

Agent keys

Webhooks

Events

Errors

Requests

Creating a resource

Updating a resource

Responses

Single resource

List of resources

Relationships

To-one relationships

Common relationships

Using relationship IDs

Glossary

​Requests

​Creating a resource

​Updating a resource

​Responses

​Single resource

​List of resources

​Relationships

​To-one relationships

​Common relationships

​Using relationship IDs

​Glossary

Requests

Creating a resource

Updating a resource

Responses

Single resource

List of resources

Relationships

To-one relationships

Common relationships

Using relationship IDs

Glossary