OpenAPI Specification
openapi: 3.1.1
info:
title: Natural Agent Keys Customers API
version: 0.2.0
description: 'Natural''s payments API for autonomous agents.
**Base URL:** `https://api.natural.com`
AI agents, including coding agents, should prefer the hosted MCP server at `https://mcp.natural.com` when an MCP-aware host runs the agent, the Natural CLI for terminal/CI workflows, and the official SDKs for application runtimes they own. Use direct HTTP only for explicit low-level integrations, unsupported SDK gaps, or infrastructure work where REST is required.
For support: support@natural.com'
servers:
- url: https://api.natural.com
description: Production
tags:
- name: Customers
description: Customer management
paths:
/customers:
get:
operationId: customers.list
summary: List customers
description: List customers who have authorized an agent to act for them
tags:
- Customers
parameters:
- name: cursor
in: query
schema:
type: string
maxLength: 1024
description: Cursor from the previous page.
allowEmptyValue: true
allowReserved: true
- name: limit
in: query
schema:
type: integer
minimum: 1
maximum: 100
default: 20
description: Maximum results per page.
allowEmptyValue: true
allowReserved: true
- name: status
in: query
schema:
enum:
- active
- revoked
- all
type: string
default: active
description: Filter by connection state. Active returns any non-revoked connection (including suspended and expired). Revoked returns customers whose access was revoked. All returns both.
allowEmptyValue: true
allowReserved: true
- name: X-Agent-ID
in: header
required: false
schema:
anyOf:
- type: string
maxLength: 36
pattern: ^agt_[0-9a-f]{32}$
- type: 'null'
description: Agent (agt_*) to attribute this request to when authenticating with a party API key; omit for agent keys and agent-scoped OAuth grants, which already carry agent identity.
- name: X-Instance-ID
in: header
required: false
schema:
anyOf:
- type: string
maxLength: 1024
- type: 'null'
description: Caller-chosen identifier for the agent run, session, or conversation, required when an agent moves money.
responses:
'200':
description: Successful Response
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
type: object
properties:
type:
type: string
enum:
- customer
id:
type: string
pattern: ^pty_[0-9a-f]{32}$
description: Customer party ID (pty_*).
attributes:
type: object
properties:
name:
type: string
description: Customer name.
email:
anyOf:
- type: string
- type: 'null'
description: Email address.
avatarUrl:
anyOf:
- type: string
format: uri
- type: 'null'
description: Public avatar URL, or null if none is set.
createdAt:
anyOf:
- type: string
format: date-time
- type: 'null'
description: When the customer was created.
delegation:
type: object
properties:
id:
type: string
pattern: ^dlg_[0-9a-f]{32}$
description: Delegation ID (dlg_*).
status:
enum:
- ACTIVE
- SUSPENDED
- REVOKED
- EXPIRED
type: string
description: Delegation status.
permissions:
type: array
items:
type: string
description: Granted permissions.
createdAt:
type: string
format: date-time
description: When the customer was connected.
revokedAt:
anyOf:
- type: string
format: date-time
- type: 'null'
description: When access was revoked, or null if not revoked.
required:
- id
- status
- permissions
- createdAt
- revokedAt
additionalProperties: false
title: CustomerDelegation
description: Delegation details.
agents:
type: array
items:
type: object
properties:
id:
type: string
pattern: ^agt_[0-9a-f]{32}$
description: Agent ID (agt_*).
name:
anyOf:
- type: string
- type: 'null'
description: Agent name.
handle:
anyOf:
- type: string
- type: 'null'
description: The agent's composed public handle (@namespace-slug), or null when it has none.
status:
type: string
description: Connection status.
permissions:
type: array
items:
type: string
description: Permissions this agent holds.
limits:
anyOf:
- type: object
properties:
perTransaction:
anyOf:
- type: integer
exclusiveMinimum: 0
- type: 'null'
description: Per-transaction spending limit in cents, or null for no limit.
perDay:
anyOf:
- type: integer
exclusiveMinimum: 0
- type: 'null'
description: Daily spending limit in cents, or null for no limit.
perMonth:
anyOf:
- type: integer
exclusiveMinimum: 0
- type: 'null'
description: Monthly spending limit in cents, or null for no limit.
additionalProperties: false
title: ConnectedAgentLimits
- type: 'null'
description: Spending limits in cents (per-transaction, daily, monthly) for this agent.
required:
- id
- name
- handle
- status
- permissions
- limits
additionalProperties: false
title: CustomerConnectedAgent
description: Connected agents.
required:
- name
- email
- avatarUrl
- createdAt
- delegation
- agents
additionalProperties: false
title: CustomerActiveAttributes
required:
- type
- id
- attributes
additionalProperties: false
title: CustomerActiveResource
description: Customer connection, including revoked connections when requested.
meta:
type: object
properties:
pagination:
type: object
properties:
hasMore:
type: boolean
description: Whether more results are available.
nextCursor:
anyOf:
- type: string
- type: 'null'
description: Cursor for the next page, or null when there are no more results.
required:
- hasMore
- nextCursor
additionalProperties: false
title: PaginationMeta
required:
- pagination
additionalProperties: false
required:
- data
- meta
additionalProperties: false
title: CustomerListResponse
examples:
default:
summary: Default
value:
data:
- id: pty_4a8c9823f39c42a5b817556766551112
type: customer
attributes:
name: Acme Co
email: ops@acme.com
avatarUrl: https://static.natural.com/avatars/acme-co.png
createdAt: '2026-01-04T15:30:00.000Z'
delegation:
id: dlg_550e8400e29b41d4a716446655440000
status: ACTIVE
permissions:
- payments.read
createdAt: '2026-01-10T12:00:00.000Z'
revokedAt: null
agents:
- id: agt_3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f
name: Invoice Agent
handle: '@acme-invoice'
status: ACTIVE
permissions:
- payments.read
limits:
perTransaction: 100000
perDay: 500000
perMonth: 2000000
meta:
pagination:
hasMore: false
nextCursor: null
headers:
X-RateLimit-Limit:
description: Maximum requests allowed per window.
schema:
type: integer
X-RateLimit-Remaining:
description: Requests remaining in current window.
schema:
type: integer
X-RateLimit-Reset:
description: Unix timestamp when rate limit resets.
schema:
type: integer
'400':
description: Validation Error
content:
application/json:
schema:
type: object
properties:
errors:
type: array
minItems: 1
items:
type: object
properties:
code:
type: string
description: Stable lower-snake-case public error code.
detail:
type: string
description: Safe user-facing error detail.
status:
type: string
description: HTTP status code as a string.
source:
type: object
description: Location of the invalid request value.
properties:
pointer:
type: string
description: JSON Pointer to the invalid request value.
parameter:
type: string
description: Name of the invalid query parameter.
header:
type: string
description: Name of the invalid request header.
additionalProperties: false
meta:
type: object
description: Additional error context, including support and provider details when available.
properties:
supportId:
type: string
description: Request/support ID for troubleshooting.
connectionStatus:
type: string
enum:
- login_required
- disconnected
description: External account connection state when the error is repairable by relinking.
provider:
type: object
description: Provider error details, when available.
properties:
name:
type: string
enum:
- plaid
description: Provider that returned the underlying error.
errorCode:
type: string
description: Provider error code, when available.
errorType:
type: string
description: Provider error type, when available.
requestId:
type: string
description: Provider request ID for troubleshooting.
required:
- name
additionalProperties: false
required:
- supportId
additionalProperties: false
required:
- code
- detail
- status
- meta
additionalProperties: false
required:
- errors
additionalProperties: false
examples:
default:
summary: Default
value:
errors:
- code: invalid_value
detail: The information you entered isn't valid. Please check it and try again.
status: '400'
meta:
supportId: req_a1b2c3d4e5f6
'401':
description: Unauthorized
content:
application/json:
schema:
type: object
properties:
errors:
type: array
minItems: 1
items:
type: object
properties:
code:
type: string
description: Stable lower-snake-case public error code.
detail:
type: string
description: Safe user-facing error detail.
status:
type: string
description: HTTP status code as a string.
source:
type: object
description: Location of the invalid request value.
properties:
pointer:
type: string
description: JSON Pointer to the invalid request value.
parameter:
type: string
description: Name of the invalid query parameter.
header:
type: string
description: Name of the invalid request header.
additionalProperties: false
meta:
type: object
description: Additional error context, including support and provider details when available.
properties:
supportId:
type: string
description: Request/support ID for troubleshooting.
connectionStatus:
type: string
enum:
- login_required
- disconnected
description: External account connection state when the error is repairable by relinking.
provider:
type: object
description: Provider error details, when available.
properties:
name:
type: string
enum:
- plaid
description: Provider that returned the underlying error.
errorCode:
type: string
description: Provider error code, when available.
errorType:
type: string
description: Provider error type, when available.
requestId:
type: string
description: Provider request ID for troubleshooting.
required:
- name
additionalProperties: false
required:
- supportId
additionalProperties: false
required:
- code
- detail
- status
- meta
additionalProperties: false
required:
- errors
additionalProperties: false
examples:
default:
summary: Default
value:
errors:
- code: unauthenticated
detail: Authentication is required.
status: '401'
meta:
supportId: req_a1b2c3d4e5f6
'403':
description: Forbidden
content:
application/json:
schema:
type: object
properties:
errors:
type: array
minItems: 1
items:
type: object
properties:
code:
type: string
description: Stable lower-snake-case public error code.
detail:
type: string
description: Safe user-facing error detail.
status:
type: string
description: HTTP status code as a string.
source:
type: object
description: Location of the invalid request value.
properties:
pointer:
type: string
description: JSON Pointer to the invalid request value.
parameter:
type: string
description: Name of the invalid query parameter.
header:
type: string
description: Name of the invalid request header.
additionalProperties: false
meta:
type: object
description: Additional error context, including support and provider details when available.
properties:
supportId:
type: string
description: Request/support ID for troubleshooting.
connectionStatus:
type: string
enum:
- login_required
- disconnected
description: External account connection state when the error is repairable by relinking.
provider:
type: object
description: Provider error details, when available.
properties:
name:
type: string
enum:
- plaid
description: Provider that returned the underlying error.
errorCode:
type: string
description: Provider error code, when available.
errorType:
type: string
description: Provider error type, when available.
requestId:
type: string
description: Provider request ID for troubleshooting.
required:
- name
additionalProperties: false
required:
- supportId
additionalProperties: false
required:
- code
- detail
- status
- meta
additionalProperties: false
required:
- errors
additionalProperties: false
examples:
default:
summary: Default
value:
errors:
- code: forbidden
detail: You do not have permission to perform this action.
status: '403'
meta:
supportId: req_a1b2c3d4e5f6
'404':
description: Not Found. Returned when the resource does not exist, or when it exists but is not accessible to your account. The two cases are intentionally indistinguishable, so that resource IDs cannot be enumerated by probing.
content:
application/json:
schema:
type: object
properties:
errors:
type: array
minItems: 1
items:
type: object
properties:
code:
type: string
description: Stable lower-snake-case public error code.
detail:
type: string
description: Safe user-facing error detail.
status:
type: string
description: HTTP status code as a string.
source:
type: object
description: Location of the invalid request value.
properties:
pointer:
type: string
description: JSON Pointer to the invalid request value.
parameter:
type: string
description: Name of the invalid query parameter.
header:
type: string
description: Name of the invalid request header.
additionalProperties: false
meta:
type: object
description: Additional error context, including support and provider details when available.
properties:
supportId:
type: string
description: Request/support ID for troubleshooting.
connectionStatus:
type: string
enum:
- login_required
- disconnected
description: External account connection state when the error is repairable by relinking.
provider:
type: object
description: Provider error details, when available.
properties:
name:
type: string
enum:
- plaid
description: Provider that returned the underlying error.
errorCode:
type: string
description: Provider error code, when available.
errorType:
type: string
description: Provider error type, when available.
requestId:
type: string
description: Provider request ID for troubleshooting.
required:
- name
additionalProperties: false
required:
- supportId
additionalProperties: false
required:
- code
- detail
- status
- meta
additionalProperties: false
required:
- errors
additionalProperties: false
examples:
default:
summary: Default
value:
errors:
- code: not_found
detail: The requested resource was not found.
status: '404'
meta:
supportId: req_a1b2c3d4e5f6
'409':
description: Conflict
content:
application/json:
schema:
type: object
properties:
errors:
type: array
minItems: 1
items:
type: object
properties:
code:
type: string
description: Stable lower-snake-case public error code.
detail:
type: string
description: Safe user-facing error detail.
status:
type: string
description: HTTP status code as a string.
source:
type: object
description: Location of the invalid request value.
properties:
pointer:
type: string
description: JSON Pointer to the invalid request value.
parameter:
type: string
description: Name of the invalid query parameter.
header:
type: string
description: Name of the invalid request header.
additionalProperties: false
meta:
type: object
description: Additional error context, including support and provider details when available.
properties:
supportId:
type: string
description: Request/support ID for troubleshooting.
connectionStatus:
type: string
enum:
- login_required
- disconnected
description: External account connection state when the error is repairable by relinking.
provider:
type: object
description: Provide
# --- truncated at 32 KB (388 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/natural-ai/refs/heads/main/openapi/natural-ai-customers-api-openapi.yml