OpenAPI Specification
openapi: 3.1.1
info:
title: Natural Agent Keys Approvals 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: Approvals
description: Approval review
paths:
/approvals:
get:
operationId: approvals.list
summary: List approvals
description: List approvals
tags:
- Approvals
parameters:
- name: limit
in: query
schema:
type: integer
minimum: 1
maximum: 100
default: 50
description: Maximum results per page.
allowEmptyValue: true
allowReserved: true
- name: status
in: query
schema:
enum:
- pending
- approved
- denied
- canceled
type: string
description: Approval status to filter by. Defaults to pending.
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:
- approval
id:
type: string
description: Approval ID (apr_*).
attributes:
type: object
properties:
status:
enum:
- pending
- approved
- denied
- canceled
type: string
description: Approval status.
target:
type: object
properties:
type:
enum:
- payment
- deposit
- withdrawal
type: string
description: Type of operation under approval.
id:
type: string
description: ID of the operation under approval.
required:
- type
- id
additionalProperties: false
description: Operation that needs approval.
payment:
anyOf:
- type: object
properties:
amount:
type: integer
description: Amount in cents.
currency:
type: string
description: Currency code.
required:
- amount
- currency
additionalProperties: false
- type: 'null'
description: Amount of the operation under review. Null when the underlying amount is unavailable.
reasons:
type: array
items:
anyOf:
- type: object
properties:
type:
type: string
enum:
- limitExceeded
limitType:
enum:
- perTransactionAmount
- dailyAmount
- monthlyAmount
type: string
description: Type of limit that was exceeded.
limitAmount:
type: integer
description: Configured limit amount in cents.
actualAmount:
type: integer
description: Amount that exceeded the limit, in cents.
currency:
type: string
description: Currency code.
required:
- type
- limitType
- limitAmount
- actualAmount
- currency
additionalProperties: false
description: Reasons this approval is under review.
customer:
anyOf:
- type: object
properties:
id:
type: string
pattern: ^pty_[0-9a-f]{32}$
description: Customer party (pty_*) whose wallet a delegated payment spends from.
name:
anyOf:
- type: string
- type: 'null'
description: Display name of the customer party, or null when unresolved.
required:
- id
- name
additionalProperties: false
- type: 'null'
description: Customer the agent is spending on behalf of, or null when the approval isn't a delegated payment.
createdAt:
type: string
description: When the approval was created.
updatedAt:
type: string
description: When the approval was last updated.
resolvedAt:
anyOf:
- type: string
- type: 'null'
description: When the approval was resolved.
required:
- status
- target
- payment
- reasons
- customer
- createdAt
- updatedAt
- resolvedAt
additionalProperties: false
required:
- type
- id
- attributes
additionalProperties: false
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
examples:
default:
summary: Default
value:
data:
- type: approval
id: apr_550e8400e29b41d4a716446655440000
attributes:
status: pending
target:
type: payment
id: pay_550e8400e29b41d4a716446655440001
payment:
amount: 500000
currency: USD
reasons:
- type: limitExceeded
limitType: perTransactionAmount
limitAmount: 250000
actualAmount: 500000
currency: USD
customer: null
createdAt: '2026-01-04T15:30:00.000Z'
updatedAt: '2026-01-04T15:30:00.000Z'
resolvedAt: null
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: 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: conflict
detail: The request conflicts with the current resource state.
status: '409'
meta:
supportId: req_a1b2c3d4e5f6
'422':
description: Validat
# --- truncated at 32 KB (238 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/natural-ai/refs/heads/main/openapi/natural-ai-approvals-api-openapi.yml