OpenAPI Specification
openapi: 3.1.1
info:
title: Natural Agent Keys Agents 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: Agents
description: Agent management
paths:
/agents:
post:
operationId: agents.create
summary: Create agent
description: Create an agent
tags:
- Agents
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
data:
type: object
properties:
attributes:
type: object
properties:
name:
type: string
minLength: 1
maxLength: 32
description: Agent display name.
description:
type: string
maxLength: 100
description: Agent description.
slug:
type: string
pattern: ^[a-z0-9][a-z0-9._]{1,28}[a-z0-9]$
description: Agent-specific part of the handle, such as support in @acme-support.
limits:
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
description: Agent spending limits. Agent credentials cannot set them.
walletId:
type: string
pattern: ^wal_[0-9a-f]{32}$
description: Wallet the agent is granted access to. Defaults to the party's default wallet when omitted.
required:
- name
additionalProperties: false
required:
- attributes
additionalProperties: false
required:
- data
additionalProperties: false
title: AgentCreateRequest
examples:
default:
summary: Default
value:
data:
attributes:
name: Carrier Payment Agent v2.1
description: Autonomous agent that pays delivery carriers
slug: carrier_payments
limits:
perTransaction: 100000
responses:
'201':
description: Successful Response
content:
application/json:
schema:
type: object
properties:
data:
type: object
properties:
type:
type: string
enum:
- agent
id:
type: string
pattern: ^agt_[0-9a-f]{32}$
description: Agent ID (agt_*).
attributes:
type: object
properties:
name:
type: string
description: Agent display name.
description:
anyOf:
- type: string
- type: 'null'
description: Agent description.
handle:
anyOf:
- type: string
- type: 'null'
description: Agent handle, such as @acme-support, or null if none is configured.
status:
enum:
- ACTIVE
- REVOKED
type: string
description: Agent status.
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: AgentOwnerLimits
- type: 'null'
description: Spend caps for actions this agent initiates on its owner's party.
createdAt:
anyOf:
- type: string
format: date-time
- type: 'null'
description: When this agent was created.
createdBy:
anyOf:
- type: string
- type: 'null'
description: User who created this agent (usr_*).
lastActiveAt:
anyOf:
- type: string
format: date-time
- type: 'null'
description: When the agent last authenticated, or null if it has never authenticated.
required:
- name
- description
- handle
- status
- limits
- createdAt
- createdBy
- lastActiveAt
additionalProperties: false
title: AgentAttributes
relationships:
type: object
properties:
party:
type: object
properties:
data:
type: object
properties:
type:
type: string
enum:
- party
id:
type: string
pattern: ^pty_[0-9a-f]{32}$
required:
- type
- id
additionalProperties: false
title: ResourceIdentifier
description: Related resource identifier.
required:
- data
additionalProperties: false
title: ToOneRelationship
description: Party that owns the agent.
required:
- party
additionalProperties: false
title: AgentRelationships
required:
- type
- id
- attributes
- relationships
additionalProperties: false
title: AgentResource
required:
- data
additionalProperties: false
title: AgentResponse
examples:
default:
summary: Default
value:
data:
type: agent
id: agt_3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f
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_550e8400e29b41d4a716446655440000
lastActiveAt: null
relationships:
party:
data:
type: party
id: pty_7c9e6679e29b41d4a716446655440001
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: Validation Error
content:
application/json:
schema:
type: object
# --- truncated at 32 KB (301 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/natural-ai/refs/heads/main/openapi/natural-ai-agents-api-openapi.yml