{ "servers": [ { "url": "https://api.natural.co", "description": "Production" } ], "components": { "securitySchemes": { "HTTPBearer": { "type": "http", "scheme": "bearer" } }, "schemas": { "ComplianceSessionStatusResponse": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "description": "Compliance verification session ID" }, "type": { "description": "Resource type", "type": "string", "enum": [ "complianceSessionStatus" ] }, "attributes": { "type": "object", "properties": { "programId": { "type": "string", "description": "Compliance program identifier" }, "programVersionId": { "type": "string", "description": "Compliance program version identifier" }, "status": { "enum": [ "UNSPECIFIED", "NOT_READY", "READY", "PENDING", "MET", "DENIED", "ACTION_NEEDED", "DEPRECATED" ], "type": "string", "description": "Current compliance case status" }, "requirements": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique requirement identifier" }, "key": { "type": "string", "description": "Stable requirement key" }, "description": { "type": "string", "description": "Human-readable requirement description" } }, "required": [ "id", "key", "description" ], "additionalProperties": false }, "description": "Requirements currently attached to this compliance case" } }, "required": [ "programId", "programVersionId", "status", "requirements" ], "additionalProperties": false, "description": "Compliance session status attributes" } }, "required": [ "id", "type", "attributes" ], "additionalProperties": false } }, "required": [ "data" ], "additionalProperties": false }, "PartyComplianceStatusResponse": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$", "description": "Party ID (pty_xxx) being verified" }, "type": { "description": "Resource type", "type": "string", "enum": [ "partyComplianceStatus" ] }, "attributes": { "type": "object", "properties": { "programCode": { "type": "string", "description": "Compliance program code" }, "caseStatus": { "enum": [ "UNSPECIFIED", "NOT_READY", "READY", "PENDING", "MET", "DENIED", "ACTION_NEEDED", "DEPRECATED" ], "type": "string", "description": "Current compliance case status" }, "displayState": { "enum": [ "verified", "underReview", "inProgress", "documentsRequired", "rejected" ], "type": "string", "description": "Customer-facing verification state" }, "title": { "type": "string", "description": "User-friendly title for the current state" }, "message": { "type": "string", "description": "User-friendly message explaining the current state" }, "canProceed": { "type": "boolean", "description": "Whether the party can proceed with platform features" }, "requirementsDue": { "type": "array", "items": { "type": "string" }, "description": "Requirement keys that still need user action or review" } }, "required": [ "programCode", "caseStatus", "displayState", "title", "message", "canProceed", "requirementsDue" ], "additionalProperties": false, "description": "Party compliance status attributes" } }, "required": [ "id", "type", "attributes" ], "additionalProperties": false } }, "required": [ "data" ], "additionalProperties": false }, "TransactionLimits": { "type": "object", "properties": { "perTransaction": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0 }, { "type": "null" } ], "description": "Positive per-transaction limit in cents. null means no per-transaction limit." } }, "additionalProperties": false, "title": "TransactionLimits" } } }, "info": { "title": "Natural API", "version": "0.2.0", "description": "Natural's payments API for autonomous agents.\n\n**Base URL:** `https://api.natural.co`\n\nAgents and coding assistants should prefer the hosted MCP server at `https://mcp.natural.co` 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.\n\nFor support: support@natural.co" }, "openapi": "3.1.1", "paths": { "/agents": { "post": { "operationId": "agents.create", "summary": "Create agent", "description": "Create an agent for your party.", "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": 100, "description": "Agent display name" }, "description": { "type": "string", "description": "Agent description" }, "limits": { "type": "object", "properties": { "perTransaction": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0 }, { "type": "null" } ], "description": "Positive per-transaction limit in cents. null means no per-transaction limit." }, "perDay": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0 }, { "type": "null" } ], "description": "Positive daily (UTC) spend cap in cents. null means no daily limit." }, "perMonth": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0 }, { "type": "null" } ], "description": "Positive calendar-month (UTC) spend cap in cents. null means no monthly limit." } }, "additionalProperties": false, "description": "Optional spend caps (per-transaction/daily/monthly) for the agent. AGENT actors may create sibling agents but must not set the limits that gate them: supplying `limits` as an AGENT actor fails with 403." }, "walletId": { "type": "string", "pattern": "^wal_[0-9a-f]{32}$", "description": "Wallet the agent is granted access to. When omitted, launch behavior currently uses the party default wallet." } }, "required": [ "name" ], "additionalProperties": false, "description": "Agent creation attributes" } }, "required": [ "attributes" ], "additionalProperties": false, "description": "Resource object" } }, "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", "limits": { "perTransaction": 100000 } } } } } } } } }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "description": "Resource type", "type": "string", "enum": [ "agent" ] }, "id": { "type": "string", "pattern": "^agt_[0-9a-f]{32}$", "description": "Resource ID" }, "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 composed from the owning party's handle and the agent slug (e.g. \"@acme/bot\"), or null when either part is unclaimed" }, "status": { "enum": [ "ACTIVE", "REVOKED" ], "type": "string", "description": "Agent status" }, "limits": { "anyOf": [ { "type": "object", "properties": { "perTransaction": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0 }, { "type": "null" } ], "description": "Positive per-transaction limit in cents. null means no per-transaction limit." }, "perDay": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0 }, { "type": "null" } ], "description": "Positive daily (UTC) spend cap in cents. null means no daily limit." }, "perMonth": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0 }, { "type": "null" } ], "description": "Positive calendar-month (UTC) spend cap in cents. null means no monthly limit." } }, "additionalProperties": false, "title": "AgentOwnerLimits" }, { "type": "null" } ], "description": "Spend caps for actions this agent initiates on its owner's party. null = no limits. Stored as Policies(scope=Agent(id)) in the policy service." }, "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_*)" } }, "required": [ "name", "description", "handle", "status", "limits", "createdAt", "createdBy" ], "additionalProperties": false, "title": "AgentAttributes", "description": "Resource attributes" }, "relationships": { "type": "object", "properties": { "party": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "description": "Resource 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", "description": "Resource relationships" } }, "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" }, "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "A request value is invalid.", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "email: Invalid email address", "status": "422", "source": { "pointer": "/data/attributes/email" }, "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "428": { "description": "Precondition Required", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "mfa_required", "detail": "MFA verification required", "status": "428", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "429": { "description": "Too Many Requests", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "rate_limited", "detail": "Too many requests. Please try again later.", "status": "429", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying", "schema": { "type": "integer" } }, "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" } } } }, "500": { "description": "Internal Server 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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "server_error", "detail": "Something went wrong.", "status": "500", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "501": { "description": "Not Implemented", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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_implemented", "detail": "This operation is not available.", "status": "501", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "502": { "description": "Bad Gateway", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "bad_gateway", "detail": "We couldn't complete that request because one of Natural's services returned an unexpected response. Please try again.", "status": "502", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "503": { "description": "Service Unavailable", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "service_unavailable", "detail": "The service is temporarily unavailable.", "status": "503", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } } }, "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Unique key for idempotent request handling. If a request with the same key was already processed, the original response is returned." }, { "name": "X-Agent-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "description": "Agent ID (agt_xxx) identifying which agent is making the request." }, { "name": "X-Instance-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 1024 }, { "type": "null" } ] }, "description": "Required when X-Agent-ID is present. Session or conversation ID for agent observability." } ] }, "get": { "operationId": "agents.list", "summary": "List agents", "description": "List agents in your party.", "tags": [ "Agents" ], "parameters": [ { "name": "status", "in": "query", "schema": { "enum": [ "ACTIVE", "REVOKED" ], "type": "string", "description": "Filter by status" }, "allowEmptyValue": true, "allowReserved": true }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50, "description": "Maximum number of agents to return" }, "allowEmptyValue": true, "allowReserved": true }, { "name": "cursor", "in": "query", "schema": { "type": "string", "description": "Cursor for the next page" }, "allowEmptyValue": true, "allowReserved": true }, { "name": "X-Agent-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "description": "Agent ID (agt_xxx) identifying which agent is making the request." }, { "name": "X-Instance-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 1024 }, { "type": "null" } ] }, "description": "Required when X-Agent-ID is present. Session or conversation ID for agent observability." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "type": { "description": "Resource type", "type": "string", "enum": [ "agent" ] }, "id": { "type": "string", "pattern": "^agt_[0-9a-f]{32}$", "description": "Resource ID" }, "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 composed from the owning party's handle and the agent slug (e.g. \"@acme/bot\"), or null when either part is unclaimed" }, "status": { "enum": [ "ACTIVE", "REVOKED" ], "type": "string", "description": "Agent status" }, "limits": { "anyOf": [ { "type": "object", "properties": { "perTransaction": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0 }, { "type": "null" } ], "description": "Positive per-transaction limit in cents. null means no per-transaction limit." }, "perDay": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0 }, { "type": "null" } ], "description": "Positive daily (UTC) spend cap in cents. null means no daily limit." }, "perMonth": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0 }, { "type": "null" } ], "description": "Positive calendar-month (UTC) spend cap in cents. null means no monthly limit." } }, "additionalProperties": false, "title": "AgentOwnerLimits" }, { "type": "null" } ], "description": "Spend caps for actions this agent initiates on its owner's party. null = no limits. Stored as Policies(scope=Agent(id)) in the policy service." }, "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_*)" } }, "required": [ "name", "description", "handle", "status", "limits", "createdAt", "createdBy" ], "additionalProperties": false, "title": "AgentAttributes", "description": "Resource attributes" }, "relationships": { "type": "object", "properties": { "party": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "description": "Resource 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", "description": "Resource relationships" } }, "required": [ "type", "id", "attributes", "relationships" ], "additionalProperties": false, "title": "AgentResource" } }, "meta": { "type": "object", "properties": { "pagination": { "type": "object", "properties": { "hasMore": { "type": "boolean" }, "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "hasMore", "nextCursor" ], "additionalProperties": false, "title": "PaginationMeta" } }, "required": [ "pagination" ], "additionalProperties": false } }, "required": [ "data", "meta" ], "additionalProperties": false, "title": "AgentListResponse" }, "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" }, "relationships": { "party": { "data": { "type": "party", "id": "pty_7c9e6679e29b41d4a716446655440001" } } } } ], "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "A request value is invalid.", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "email: Invalid email address", "status": "422", "source": { "pointer": "/data/attributes/email" }, "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "428": { "description": "Precondition Required", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "mfa_required", "detail": "MFA verification required", "status": "428", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "429": { "description": "Too Many Requests", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "rate_limited", "detail": "Too many requests. Please try again later.", "status": "429", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying", "schema": { "type": "integer" } }, "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" } } } }, "500": { "description": "Internal Server 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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "server_error", "detail": "Something went wrong.", "status": "500", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "501": { "description": "Not Implemented", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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_implemented", "detail": "This operation is not available.", "status": "501", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "502": { "description": "Bad Gateway", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "bad_gateway", "detail": "We couldn't complete that request because one of Natural's services returned an unexpected response. Please try again.", "status": "502", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "503": { "description": "Service Unavailable", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "service_unavailable", "detail": "The service is temporarily unavailable.", "status": "503", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } } }, "security": [ { "HTTPBearer": [] } ] } }, "/agents/{agentId}": { "get": { "operationId": "agents.get", "summary": "Get agent", "description": "Get agent details by its unique ID.", "tags": [ "Agents" ], "parameters": [ { "name": "agentId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^agt_[0-9a-f]{32}$", "description": "Agent ID" } }, { "name": "X-Agent-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "description": "Agent ID (agt_xxx) identifying which agent is making the request." }, { "name": "X-Instance-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 1024 }, { "type": "null" } ] }, "description": "Required when X-Agent-ID is present. Session or conversation ID for agent observability." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "description": "Resource type", "type": "string", "enum": [ "agent" ] }, "id": { "type": "string", "pattern": "^agt_[0-9a-f]{32}$", "description": "Resource ID" }, "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 composed from the owning party's handle and the agent slug (e.g. \"@acme/bot\"), or null when either part is unclaimed" }, "status": { "enum": [ "ACTIVE", "REVOKED" ], "type": "string", "description": "Agent status" }, "limits": { "anyOf": [ { "type": "object", "properties": { "perTransaction": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0 }, { "type": "null" } ], "description": "Positive per-transaction limit in cents. null means no per-transaction limit." }, "perDay": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0 }, { "type": "null" } ], "description": "Positive daily (UTC) spend cap in cents. null means no daily limit." }, "perMonth": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0 }, { "type": "null" } ], "description": "Positive calendar-month (UTC) spend cap in cents. null means no monthly limit." } }, "additionalProperties": false, "title": "AgentOwnerLimits" }, { "type": "null" } ], "description": "Spend caps for actions this agent initiates on its owner's party. null = no limits. Stored as Policies(scope=Agent(id)) in the policy service." }, "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_*)" } }, "required": [ "name", "description", "handle", "status", "limits", "createdAt", "createdBy" ], "additionalProperties": false, "title": "AgentAttributes", "description": "Resource attributes" }, "relationships": { "type": "object", "properties": { "party": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "description": "Resource 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", "description": "Resource relationships" } }, "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" }, "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "A request value is invalid.", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "email: Invalid email address", "status": "422", "source": { "pointer": "/data/attributes/email" }, "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "428": { "description": "Precondition Required", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "mfa_required", "detail": "MFA verification required", "status": "428", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "429": { "description": "Too Many Requests", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "rate_limited", "detail": "Too many requests. Please try again later.", "status": "429", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying", "schema": { "type": "integer" } }, "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" } } } }, "500": { "description": "Internal Server 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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "server_error", "detail": "Something went wrong.", "status": "500", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "501": { "description": "Not Implemented", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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_implemented", "detail": "This operation is not available.", "status": "501", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "502": { "description": "Bad Gateway", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "bad_gateway", "detail": "We couldn't complete that request because one of Natural's services returned an unexpected response. Please try again.", "status": "502", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "503": { "description": "Service Unavailable", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "service_unavailable", "detail": "The service is temporarily unavailable.", "status": "503", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } } }, "security": [ { "HTTPBearer": [] } ] }, "patch": { "operationId": "agents.update", "summary": "Update agent", "description": "Update an agent's mutable fields. Changing `slug` (the agent handle segment) requires a non-delegated user session on an active, verified party; renaming or clearing a slug releases the previous value into a 14-day hold.", "tags": [ "Agents" ], "parameters": [ { "name": "agentId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^agt_[0-9a-f]{32}$", "description": "Agent ID" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Unique key for idempotent request handling. If a request with the same key was already processed, the original response is returned." }, { "name": "X-Agent-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "description": "Agent ID (agt_xxx) identifying which agent is making the request." }, { "name": "X-Instance-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 1024 }, { "type": "null" } ] }, "description": "Required when X-Agent-ID is present. Session or conversation ID for agent observability." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "attributes": { "type": "object", "properties": { "name": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 100 }, { "type": "null" } ], "description": "Updated name for the agent" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Updated description" }, "slug": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 64 }, { "type": "null" } ], "description": "Agent handle slug (the segment after the party namespace in \"@namespace/slug\"). A string sets or renames it, null clears it, omitted leaves it unchanged; empty string is rejected (use null to clear instead). Renaming or clearing releases the previous slug into a 14-day hold. Requires a non-delegated user session on an active, verified party; other actors receive a 403." }, "limits": { "anyOf": [ { "type": "object", "properties": { "perTransaction": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0 }, { "type": "null" } ], "description": "Positive per-transaction limit in cents. null means no per-transaction limit." }, "perDay": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0 }, { "type": "null" } ], "description": "Positive daily (UTC) spend cap in cents. null means no daily limit." }, "perMonth": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0 }, { "type": "null" } ], "description": "Positive calendar-month (UTC) spend cap in cents. null means no monthly limit." } }, "additionalProperties": false, "title": "AgentOwnerLimits" }, { "type": "null" } ], "description": "Spend caps. When present the object is a full replacement: a null or omitted field clears that window's cap. null clears every cap; omitted leaves limits unchanged. AGENT actors must not change the limits that gate them: supplying `limits` as an AGENT actor fails with 403." } }, "additionalProperties": false, "title": "AgentUpdateAttributes", "description": "Agent update attributes" } }, "required": [ "attributes" ], "additionalProperties": false, "description": "Resource object" } }, "required": [ "data" ], "additionalProperties": false, "title": "AgentUpdateRequest" }, "examples": { "default": { "summary": "Default", "value": { "data": { "attributes": { "name": "Carrier Payment Agent v3.0", "description": "Autonomous agent that pays delivery carriers with enhanced fraud detection" } } } } } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "description": "Resource type", "type": "string", "enum": [ "agent" ] }, "id": { "type": "string", "pattern": "^agt_[0-9a-f]{32}$", "description": "Resource ID" }, "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 composed from the owning party's handle and the agent slug (e.g. \"@acme/bot\"), or null when either part is unclaimed" }, "status": { "enum": [ "ACTIVE", "REVOKED" ], "type": "string", "description": "Agent status" }, "limits": { "anyOf": [ { "type": "object", "properties": { "perTransaction": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0 }, { "type": "null" } ], "description": "Positive per-transaction limit in cents. null means no per-transaction limit." }, "perDay": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0 }, { "type": "null" } ], "description": "Positive daily (UTC) spend cap in cents. null means no daily limit." }, "perMonth": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0 }, { "type": "null" } ], "description": "Positive calendar-month (UTC) spend cap in cents. null means no monthly limit." } }, "additionalProperties": false, "title": "AgentOwnerLimits" }, { "type": "null" } ], "description": "Spend caps for actions this agent initiates on its owner's party. null = no limits. Stored as Policies(scope=Agent(id)) in the policy service." }, "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_*)" } }, "required": [ "name", "description", "handle", "status", "limits", "createdAt", "createdBy" ], "additionalProperties": false, "title": "AgentAttributes", "description": "Resource attributes" }, "relationships": { "type": "object", "properties": { "party": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "description": "Resource 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", "description": "Resource relationships" } }, "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" }, "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "A request value is invalid.", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "email: Invalid email address", "status": "422", "source": { "pointer": "/data/attributes/email" }, "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "428": { "description": "Precondition Required", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "mfa_required", "detail": "MFA verification required", "status": "428", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "429": { "description": "Too Many Requests", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "rate_limited", "detail": "Too many requests. Please try again later.", "status": "429", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying", "schema": { "type": "integer" } }, "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" } } } }, "500": { "description": "Internal Server 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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "server_error", "detail": "Something went wrong.", "status": "500", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "501": { "description": "Not Implemented", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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_implemented", "detail": "This operation is not available.", "status": "501", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "502": { "description": "Bad Gateway", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "bad_gateway", "detail": "We couldn't complete that request because one of Natural's services returned an unexpected response. Please try again.", "status": "502", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "503": { "description": "Service Unavailable", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "service_unavailable", "detail": "The service is temporarily unavailable.", "status": "503", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } } }, "security": [ { "HTTPBearer": [] } ] }, "delete": { "operationId": "agents.remove", "summary": "Delete agent", "description": "Delete an agent. Deleting an agent revokes it and cleans up active access.", "tags": [ "Agents" ], "parameters": [ { "name": "agentId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^agt_[0-9a-f]{32}$", "description": "Agent ID" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Unique key for idempotent request handling. If a request with the same key was already processed, the original response is returned." }, { "name": "X-Agent-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "description": "Agent ID (agt_xxx) identifying which agent is making the request." }, { "name": "X-Instance-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 1024 }, { "type": "null" } ] }, "description": "Required when X-Agent-ID is present. Session or conversation ID for agent observability." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "description": "Resource type", "type": "string", "enum": [ "agent" ] }, "id": { "type": "string", "pattern": "^agt_[0-9a-f]{32}$", "description": "Resource ID" }, "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 composed from the owning party's handle and the agent slug (e.g. \"@acme/bot\"), or null when either part is unclaimed" }, "status": { "enum": [ "ACTIVE", "REVOKED" ], "type": "string", "description": "Agent status" }, "limits": { "anyOf": [ { "type": "object", "properties": { "perTransaction": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0 }, { "type": "null" } ], "description": "Positive per-transaction limit in cents. null means no per-transaction limit." }, "perDay": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0 }, { "type": "null" } ], "description": "Positive daily (UTC) spend cap in cents. null means no daily limit." }, "perMonth": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0 }, { "type": "null" } ], "description": "Positive calendar-month (UTC) spend cap in cents. null means no monthly limit." } }, "additionalProperties": false, "title": "AgentOwnerLimits" }, { "type": "null" } ], "description": "Spend caps for actions this agent initiates on its owner's party. null = no limits. Stored as Policies(scope=Agent(id)) in the policy service." }, "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_*)" } }, "required": [ "name", "description", "handle", "status", "limits", "createdAt", "createdBy" ], "additionalProperties": false, "title": "AgentAttributes", "description": "Resource attributes" }, "relationships": { "type": "object", "properties": { "party": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "description": "Resource 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", "description": "Resource relationships" } }, "required": [ "type", "id", "attributes", "relationships" ], "additionalProperties": false, "title": "AgentResource" }, "meta": { "type": "object", "properties": { "deleted": { "const": true, "description": "Indicates the resource was deleted" } }, "required": [ "deleted" ], "additionalProperties": false, "title": "DeletedMeta" } }, "required": [ "data", "meta" ], "additionalProperties": false, "title": "AgentRevokeResponse" }, "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": "REVOKED", "limits": { "perTransaction": 100000 }, "createdAt": "2026-01-04T15:30:00Z", "createdBy": "usr_550e8400e29b41d4a716446655440000" }, "relationships": { "party": { "data": { "type": "party", "id": "pty_7c9e6679e29b41d4a716446655440001" } } } }, "meta": { "deleted": true } } } } } }, "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "A request value is invalid.", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "email: Invalid email address", "status": "422", "source": { "pointer": "/data/attributes/email" }, "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "428": { "description": "Precondition Required", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "mfa_required", "detail": "MFA verification required", "status": "428", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "429": { "description": "Too Many Requests", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "rate_limited", "detail": "Too many requests. Please try again later.", "status": "429", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying", "schema": { "type": "integer" } }, "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" } } } }, "500": { "description": "Internal Server 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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "server_error", "detail": "Something went wrong.", "status": "500", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "501": { "description": "Not Implemented", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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_implemented", "detail": "This operation is not available.", "status": "501", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "502": { "description": "Bad Gateway", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "bad_gateway", "detail": "We couldn't complete that request because one of Natural's services returned an unexpected response. Please try again.", "status": "502", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "503": { "description": "Service Unavailable", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "service_unavailable", "detail": "The service is temporarily unavailable.", "status": "503", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } } }, "security": [ { "HTTPBearer": [] } ] } }, "/agents/{agentId}/customers": { "post": { "operationId": "agents.createCustomer", "summary": "Invite agent's customers", "description": "Invite one or more of your customers to authorize this agent to act for them.", "tags": [ "Agents" ], "parameters": [ { "name": "agentId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^agt_[0-9a-f]{32}$", "description": "Agent ID" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Unique key for idempotent request handling. If a request with the same key was already processed, the original response is returned." }, { "name": "X-Agent-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "description": "Agent ID (agt_xxx) identifying which agent is making the request." }, { "name": "X-Instance-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 1024 }, { "type": "null" } ] }, "description": "Required when X-Agent-ID is present. Session or conversation ID for agent observability." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "attributes": { "type": "object", "properties": { "recipients": { "type": "array", "minItems": 1, "items": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "email" ] }, "value": { "type": "string", "format": "email", "description": "Email address" } }, "required": [ "type", "value" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "phone" ] }, "value": { "type": "string", "description": "Phone number in E.164 format" } }, "required": [ "type", "value" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "party_id" ] }, "value": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$", "description": "Natural party ID (pty_*)" } }, "required": [ "type", "value" ], "additionalProperties": false } ], "title": "CustomerInvitationRecipient" }, "description": "Customer recipients to invite" }, "permissions": { "type": "array", "minItems": 1, "items": { "enum": [ "payments.read", "payments.create", "external_accounts.create", "wallets.read", "wallets.update", "party.read", "party.update" ], "type": "string" }, "description": "Permissions to request" }, "limits": { "type": "object", "properties": { "perTransaction": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0 }, { "type": "null" } ], "description": "Per-transaction cap, integer cents (USD)." } }, "additionalProperties": false, "description": "Optional per-transaction limit" }, "expiresAt": { "type": "string", "format": "date-time", "description": "Optional explicit expiry timestamp; server defaults to 7 days" }, "tags": { "type": "object", "propertyNames": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[a-zA-Z0-9_]+$" }, "additionalProperties": { "type": "string", "minLength": 1, "maxLength": 256 }, "description": "Tags applied to every invitation in this request" } }, "required": [ "recipients", "permissions" ], "additionalProperties": false, "description": "Agent-customer creation attributes" } }, "required": [ "attributes" ], "additionalProperties": false, "description": "Resource object" } }, "required": [ "data" ], "additionalProperties": false, "title": "CreateAgentCustomerRequest" }, "examples": { "default": { "summary": "Default", "value": { "data": { "attributes": { "recipients": [ { "type": "email", "value": "ops@example.com" }, { "type": "phone", "value": "+14155550123" }, { "type": "party_id", "value": "pty_4a8c9823f39c42a5b817556766551112" } ], "permissions": [ "payments.create", "payments.read" ], "limits": { "perTransaction": 100000 }, "expiresAt": "2026-01-18T12:00:00.000Z", "tags": { "campaign": "q3_reactivation" } } } } } } } } }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "type": { "description": "Resource type", "type": "string", "enum": [ "customerInvitation" ] }, "id": { "type": "string", "pattern": "^adi_[0-9a-f]{32}$", "description": "Customer invitation ID (adi_*)" }, "attributes": { "type": "object", "properties": { "recipient": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "email" ] }, "value": { "type": "string", "format": "email", "description": "Email address" } }, "required": [ "type", "value" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "phone" ] }, "value": { "type": "string", "description": "Phone number in E.164 format" } }, "required": [ "type", "value" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "party_id" ] }, "value": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$", "description": "Natural party ID (pty_*)" } }, "required": [ "type", "value" ], "additionalProperties": false } ], "title": "CustomerInvitationRecipient", "description": "Recipient identifier used to create the invitation" }, "url": { "type": "string", "format": "uri", "description": "Shareable URL where the recipient reviews and accepts the invitation. Also sent in the invitation email; for phone invitations, deliver it yourself." }, "status": { "enum": [ "ACTIVE", "PENDING", "ACCEPTED", "DECLINED", "EXPIRED", "CANCELED", "REVOKED" ], "type": "string", "description": "Current invitation status" }, "permissions": { "type": "array", "items": { "type": "string" }, "description": "Permissions requested for this agent invitation" }, "limits": { "anyOf": [ { "type": "object", "properties": { "perTransaction": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0 }, { "type": "null" } ], "description": "Per-transaction cap, integer cents (USD)." } }, "additionalProperties": false, "title": "AgentLimitsSpec" }, { "type": "null" } ], "description": "Requested per-agent customer limits" }, "tags": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" }, "description": "Custom metadata tags. Visible to any party authorized to read the resource." }, "expiresAt": { "type": "string", "description": "When this invitation expires" }, "createdAt": { "type": "string", "description": "When this invitation was created" }, "updatedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "When this invitation was last updated" } }, "required": [ "recipient", "url", "status", "permissions", "limits", "tags", "expiresAt", "createdAt", "updatedAt" ], "additionalProperties": false, "title": "AgentCustomerInvitationAttributes", "description": "Invitation attributes" }, "relationships": { "type": "object", "properties": { "agent": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "description": "Resource type", "type": "string", "enum": [ "agent" ] }, "id": { "type": "string", "pattern": "^agt_[0-9a-f]{32}$", "description": "Agent ID (agt_*)" }, "attributes": { "type": "object", "properties": { "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Agent display name" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Agent description" }, "status": { "enum": [ "ACTIVE", "REVOKED" ], "type": "string", "description": "Agent status" } }, "required": [ "name", "description", "status" ], "additionalProperties": false, "description": "Agent attributes" } }, "required": [ "type", "id", "attributes" ], "additionalProperties": false, "title": "EmbeddedAgentDetailsResource" } }, "required": [ "data" ], "additionalProperties": false, "description": "Agent attached to this invitation" }, "customerParty": { "type": "object", "properties": { "data": { "anyOf": [ { "type": "object", "properties": { "type": { "description": "Resource 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" }, { "type": "null" } ] } }, "required": [ "data" ], "additionalProperties": false, "title": "NullableToOneRelationship", "description": "Customer party when the recipient is an existing party or once the invitation is accepted" } }, "required": [ "agent", "customerParty" ], "additionalProperties": false, "title": "AgentCustomerInvitationRelationships", "description": "Related agent and customer party" } }, "required": [ "type", "id", "attributes", "relationships" ], "additionalProperties": false, "title": "AgentCustomerInvitationResource" }, "description": "Created customer invitation resources" }, "meta": { "type": "object", "properties": { "emailFailures": { "type": "array", "items": { "type": "string" }, "description": "Invitation IDs whose welcome-email send failed. Invitations are still persisted; use the resend-email flow to retry." } }, "required": [ "emailFailures" ], "additionalProperties": false, "description": "Batch invitation metadata" } }, "required": [ "data", "meta" ], "additionalProperties": false, "title": "AgentCustomerBatchResponse" }, "examples": { "default": { "summary": "Default", "value": { "data": [ { "type": "customerInvitation", "id": "adi_550e8400e29b41d4a716446655440000", "attributes": { "recipient": { "type": "email", "value": "ops@example.com" }, "url": "https://www.natural.co/connect/adi_550e8400e29b41d4a716446655440000", "status": "PENDING", "permissions": [ "payments.create", "payments.read" ], "limits": { "perTransaction": 100000 }, "tags": { "campaign": "q3_reactivation" }, "expiresAt": "2026-01-18T12:00:00.000Z", "createdAt": "2026-01-11T12:00:00.000Z", "updatedAt": "2026-01-11T12:00:00.000Z" }, "relationships": { "agent": { "data": { "type": "agent", "id": "agt_3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f", "attributes": { "name": "Carrier Payment Agent", "description": "Autonomous agent that pays delivery carriers", "status": "ACTIVE" } } }, "customerParty": { "data": null } } } ], "meta": { "emailFailures": [] } } } } } }, "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "A request value is invalid.", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "email: Invalid email address", "status": "422", "source": { "pointer": "/data/attributes/email" }, "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "428": { "description": "Precondition Required", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "mfa_required", "detail": "MFA verification required", "status": "428", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "429": { "description": "Too Many Requests", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "rate_limited", "detail": "Too many requests. Please try again later.", "status": "429", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying", "schema": { "type": "integer" } }, "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" } } } }, "500": { "description": "Internal Server 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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "server_error", "detail": "Something went wrong.", "status": "500", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "501": { "description": "Not Implemented", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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_implemented", "detail": "This operation is not available.", "status": "501", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "502": { "description": "Bad Gateway", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "bad_gateway", "detail": "We couldn't complete that request because one of Natural's services returned an unexpected response. Please try again.", "status": "502", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "503": { "description": "Service Unavailable", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "service_unavailable", "detail": "The service is temporarily unavailable.", "status": "503", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } } }, "security": [ { "HTTPBearer": [] } ] }, "get": { "operationId": "agents.listCustomers", "summary": "List agent's customers", "description": "List the customers who have an active, accepted authorization for this agent.", "tags": [ "Agents" ], "parameters": [ { "name": "agentId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^agt_[0-9a-f]{32}$", "description": "Agent ID" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 }, "allowEmptyValue": true, "allowReserved": true }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" }, "allowEmptyValue": true, "allowReserved": true }, { "name": "X-Agent-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "description": "Agent ID (agt_xxx) identifying which agent is making the request." }, { "name": "X-Instance-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 1024 }, { "type": "null" } ] }, "description": "Required when X-Agent-ID is present. Session or conversation ID for agent observability." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "type": { "description": "Resource type", "type": "string", "enum": [ "customer" ] }, "id": { "type": "string", "description": "Customer party ID when known; otherwise the lowercased customer email" }, "attributes": { "type": "object", "properties": { "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Customer party display name, when known" }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Customer email, when known" }, "status": { "enum": [ "ACTIVE", "PENDING", "ACCEPTED", "DECLINED", "EXPIRED", "CANCELED", "REVOKED" ], "type": "string", "description": "Current agent-customer relationship status" }, "permissions": { "type": "array", "items": { "type": "string" }, "description": "Permissions granted or requested for this agent" }, "limits": { "anyOf": [ { "type": "object", "properties": { "perTransaction": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0 }, { "type": "null" } ], "description": "Per-transaction cap, integer cents (USD)." } }, "additionalProperties": false, "title": "AgentLimitsSpec" }, { "type": "null" } ], "description": "Per-agent customer transaction limits" }, "createdAt": { "type": "string", "description": "When this agent-customer relationship was created" }, "updatedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "When this agent-customer relationship was last updated" } }, "required": [ "name", "email", "status", "permissions", "limits", "createdAt", "updatedAt" ], "additionalProperties": false, "title": "AgentCustomerAttributes", "description": "Customer party and current access attributes" }, "relationships": { "type": "object", "properties": { "agent": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "description": "Resource type", "type": "string", "enum": [ "agent" ] }, "id": { "type": "string", "pattern": "^agt_[0-9a-f]{32}$", "description": "Agent ID (agt_*)" }, "attributes": { "type": "object", "properties": { "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Agent display name" } }, "required": [ "name" ], "additionalProperties": false, "description": "Agent attributes" } }, "required": [ "type", "id", "attributes" ], "additionalProperties": false, "title": "EmbeddedAgentResource" } }, "required": [ "data" ], "additionalProperties": false, "description": "Agent attached to this customer" } }, "required": [ "agent" ], "additionalProperties": false, "title": "AgentCustomerRelationships", "description": "Related agent details" } }, "required": [ "type", "id", "attributes", "relationships" ], "additionalProperties": false, "title": "AgentCustomerResource" } }, "meta": { "type": "object", "properties": { "pagination": { "type": "object", "properties": { "hasMore": { "type": "boolean" }, "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "hasMore", "nextCursor" ], "additionalProperties": false, "title": "PaginationMeta" } }, "required": [ "pagination" ], "additionalProperties": false } }, "required": [ "data", "meta" ], "additionalProperties": false, "title": "AgentCustomerListResponse" }, "examples": { "default": { "summary": "Default", "value": { "data": [ { "type": "customer", "id": "pty_4a8c9823f39c42a5b817556766551112", "attributes": { "name": "Acme Co", "email": "ops@example.com", "status": "ACTIVE", "permissions": [ "payments.create", "payments.read" ], "limits": { "perTransaction": 100000 }, "createdAt": "2026-01-11T12:00:00.000Z", "updatedAt": "2026-01-11T12:00:00.000Z" }, "relationships": { "agent": { "data": { "type": "agent", "id": "agt_3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f", "attributes": { "name": "Carrier Payment Agent" } } } } } ], "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "A request value is invalid.", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "email: Invalid email address", "status": "422", "source": { "pointer": "/data/attributes/email" }, "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "428": { "description": "Precondition Required", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "mfa_required", "detail": "MFA verification required", "status": "428", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "429": { "description": "Too Many Requests", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "rate_limited", "detail": "Too many requests. Please try again later.", "status": "429", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying", "schema": { "type": "integer" } }, "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" } } } }, "500": { "description": "Internal Server 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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "server_error", "detail": "Something went wrong.", "status": "500", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "501": { "description": "Not Implemented", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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_implemented", "detail": "This operation is not available.", "status": "501", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "502": { "description": "Bad Gateway", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "bad_gateway", "detail": "We couldn't complete that request because one of Natural's services returned an unexpected response. Please try again.", "status": "502", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "503": { "description": "Service Unavailable", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "service_unavailable", "detail": "The service is temporarily unavailable.", "status": "503", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } } }, "security": [ { "HTTPBearer": [] } ] } }, "/agents/{agentId}/customers/{customerId}": { "delete": { "operationId": "agents.removeCustomer", "summary": "Revoke agent's customer access", "description": "Revoke this agent's access to act for a single customer.", "tags": [ "Agents" ], "parameters": [ { "name": "agentId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^agt_[0-9a-f]{32}$", "description": "Agent ID" } }, { "name": "customerId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$", "description": "Customer party ID" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Unique key for idempotent request handling. If a request with the same key was already processed, the original response is returned." }, { "name": "X-Agent-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "description": "Agent ID (agt_xxx) identifying which agent is making the request." }, { "name": "X-Instance-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 1024 }, { "type": "null" } ] }, "description": "Required when X-Agent-ID is present. Session or conversation ID for agent observability." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "description": "Resource type", "type": "string", "enum": [ "customer" ] }, "id": { "type": "string", "description": "Customer party ID when known; otherwise the lowercased customer email" }, "attributes": { "type": "object", "properties": { "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Customer party display name, when known" }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Customer email, when known" }, "status": { "enum": [ "ACTIVE", "PENDING", "ACCEPTED", "DECLINED", "EXPIRED", "CANCELED", "REVOKED" ], "type": "string", "description": "Current agent-customer relationship status" }, "permissions": { "type": "array", "items": { "type": "string" }, "description": "Permissions granted or requested for this agent" }, "limits": { "anyOf": [ { "type": "object", "properties": { "perTransaction": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0 }, { "type": "null" } ], "description": "Per-transaction cap, integer cents (USD)." } }, "additionalProperties": false, "title": "AgentLimitsSpec" }, { "type": "null" } ], "description": "Per-agent customer transaction limits" }, "createdAt": { "type": "string", "description": "When this agent-customer relationship was created" }, "updatedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "When this agent-customer relationship was last updated" } }, "required": [ "name", "email", "status", "permissions", "limits", "createdAt", "updatedAt" ], "additionalProperties": false, "title": "AgentCustomerAttributes", "description": "Customer party and current access attributes" }, "relationships": { "type": "object", "properties": { "agent": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "description": "Resource type", "type": "string", "enum": [ "agent" ] }, "id": { "type": "string", "pattern": "^agt_[0-9a-f]{32}$", "description": "Agent ID (agt_*)" }, "attributes": { "type": "object", "properties": { "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Agent display name" } }, "required": [ "name" ], "additionalProperties": false, "description": "Agent attributes" } }, "required": [ "type", "id", "attributes" ], "additionalProperties": false, "title": "EmbeddedAgentResource" } }, "required": [ "data" ], "additionalProperties": false, "description": "Agent attached to this customer" } }, "required": [ "agent" ], "additionalProperties": false, "title": "AgentCustomerRelationships", "description": "Related agent details" } }, "required": [ "type", "id", "attributes", "relationships" ], "additionalProperties": false, "title": "AgentCustomerResource" }, "meta": { "type": "object", "properties": { "deleted": { "const": true, "description": "Indicates the resource was deleted" } }, "required": [ "deleted" ], "additionalProperties": false, "title": "DeletedMeta" } }, "required": [ "data", "meta" ], "additionalProperties": false, "title": "AgentCustomerRemoveResponse" }, "examples": { "default": { "summary": "Default", "value": { "data": { "type": "customer", "id": "pty_4a8c9823f39c42a5b817556766551112", "attributes": { "name": "Acme Co", "email": "ops@example.com", "status": "REVOKED", "permissions": [ "payments.create", "payments.read" ], "limits": { "perTransaction": 100000 }, "createdAt": "2026-01-11T12:00:00.000Z", "updatedAt": "2026-01-11T12:00:00.000Z" }, "relationships": { "agent": { "data": { "type": "agent", "id": "agt_3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f", "attributes": { "name": "Carrier Payment Agent" } } } } }, "meta": { "deleted": true } } } } } }, "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "A request value is invalid.", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "email: Invalid email address", "status": "422", "source": { "pointer": "/data/attributes/email" }, "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "428": { "description": "Precondition Required", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "mfa_required", "detail": "MFA verification required", "status": "428", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "429": { "description": "Too Many Requests", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "rate_limited", "detail": "Too many requests. Please try again later.", "status": "429", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying", "schema": { "type": "integer" } }, "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" } } } }, "500": { "description": "Internal Server 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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "server_error", "detail": "Something went wrong.", "status": "500", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "501": { "description": "Not Implemented", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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_implemented", "detail": "This operation is not available.", "status": "501", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "502": { "description": "Bad Gateway", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "bad_gateway", "detail": "We couldn't complete that request because one of Natural's services returned an unexpected response. Please try again.", "status": "502", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "503": { "description": "Service Unavailable", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "service_unavailable", "detail": "The service is temporarily unavailable.", "status": "503", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } } }, "security": [ { "HTTPBearer": [] } ] } }, "/agents/invitations": { "get": { "operationId": "agents.listInvitations", "summary": "List agent invitations", "description": "List the pending agent invitations you've sent.", "tags": [ "Agents" ], "parameters": [ { "name": "status", "in": "query", "schema": { "type": "array", "items": { "enum": [ "PENDING", "ACCEPTED", "DECLINED", "EXPIRED", "CANCELED" ], "type": "string" } }, "style": "deepObject", "explode": true, "allowEmptyValue": true, "allowReserved": true }, { "name": "customerEmail", "in": "query", "schema": { "type": "string", "format": "email" }, "allowEmptyValue": true, "allowReserved": true }, { "name": "agentId", "in": "query", "schema": { "type": "string", "pattern": "^agt_[0-9a-f]{32}$" }, "allowEmptyValue": true, "allowReserved": true }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 }, "allowEmptyValue": true, "allowReserved": true }, { "name": "cursor", "in": "query", "schema": { "type": "string" }, "allowEmptyValue": true, "allowReserved": true }, { "name": "X-Agent-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "description": "Agent ID (agt_xxx) identifying which agent is making the request." }, { "name": "X-Instance-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 1024 }, { "type": "null" } ] }, "description": "Required when X-Agent-ID is present. Session or conversation ID for agent observability." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "type": { "description": "Resource type", "type": "string", "enum": [ "agentDelegationInvitation" ] }, "id": { "type": "string", "pattern": "^adi_[0-9a-f]{32}$", "description": "Invitation ID" }, "attributes": { "type": "object", "properties": { "developerName": { "type": "string", "description": "Developer name" }, "email": { "type": "string", "description": "Recipient email" }, "phone": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Recipient phone" }, "url": { "type": "string", "format": "uri", "description": "Shareable URL where the recipient reviews and accepts the invitation. Also sent in the invitation email; for phone invitations, deliver it yourself." }, "agentName": { "type": "string", "description": "Agent name" }, "permissions": { "type": "array", "items": { "type": "string" }, "description": "Permissions granted on accept" }, "limits": { "anyOf": [ { "type": "object", "properties": { "perTransaction": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0 }, { "type": "null" } ], "description": "Per-transaction cap, integer cents (USD)." } }, "additionalProperties": false, "title": "AgentLimitsSpec" }, { "type": "null" } ], "description": "Transaction limits" }, "status": { "enum": [ "PENDING", "ACCEPTED", "DECLINED", "EXPIRED", "CANCELED" ], "type": "string", "description": "Invitation status" }, "effectiveStatus": { "enum": [ "PENDING", "ACCEPTED", "DECLINED", "EXPIRED", "CANCELED" ], "type": "string", "description": "Resolved status, accounting for expiry" }, "expiresAt": { "type": "string", "description": "When the invitation expires" }, "acceptedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "When the invitation was accepted" }, "declinedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "When the invitation was declined" }, "cancelReason": { "anyOf": [ { "enum": [ "AGENT_RETIRED", "DEVELOPER_RETIRED", "DEVELOPER_REVOKED" ], "type": "string" }, { "type": "null" } ], "description": "Reason for cancellation" }, "tags": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" }, "description": "Custom metadata tags. Visible to any party authorized to read the resource." }, "createdAt": { "type": "string", "description": "When the invitation was created" }, "updatedAt": { "type": "string", "description": "When the invitation was last updated" } }, "required": [ "developerName", "email", "phone", "url", "agentName", "permissions", "limits", "status", "effectiveStatus", "expiresAt", "acceptedAt", "declinedAt", "cancelReason", "tags", "createdAt", "updatedAt" ], "additionalProperties": false, "title": "AgentDelegationInvitationAttributes", "description": "Invitation details" }, "relationships": { "type": "object", "properties": { "agent": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "description": "Resource type", "type": "string", "enum": [ "agent" ] }, "id": { "type": "string", "pattern": "^agt_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier" } }, "required": [ "data" ], "additionalProperties": false, "title": "ToOneRelationship", "description": "The invited agent" }, "customerParty": { "type": "object", "properties": { "data": { "anyOf": [ { "type": "object", "properties": { "type": { "description": "Resource 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" }, { "type": "null" } ] } }, "required": [ "data" ], "additionalProperties": false, "title": "NullableToOneRelationship", "description": "Customer party the invitation was accepted on (null until accept)" } }, "required": [ "agent", "customerParty" ], "additionalProperties": false, "description": "Related resources" } }, "required": [ "type", "id", "attributes", "relationships" ], "additionalProperties": false, "title": "AgentDelegationInvitationResource" } }, "meta": { "type": "object", "properties": { "pagination": { "type": "object", "properties": { "hasMore": { "type": "boolean" }, "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "hasMore", "nextCursor" ], "additionalProperties": false, "title": "PaginationMeta" } }, "required": [ "pagination" ], "additionalProperties": false } }, "required": [ "data", "meta" ], "additionalProperties": false, "title": "AgentDelegationInvitationsListResponse" }, "examples": { "default": { "summary": "Default", "value": { "data": [ { "type": "agentDelegationInvitation", "id": "adi_550e8400e29b41d4a716446655440000", "attributes": { "developerName": "Acme Inc", "email": "ops@customer.com", "phone": null, "url": "https://www.natural.co/connect/adi_550e8400e29b41d4a716446655440000", "agentName": "Invoice Agent", "permissions": [ "payments.read" ], "limits": { "perTransaction": 100000 }, "status": "PENDING", "effectiveStatus": "PENDING", "expiresAt": "2026-01-12T10:15:00.000Z", "acceptedAt": null, "declinedAt": null, "cancelReason": null, "tags": { "campaign": "q3_reactivation" }, "createdAt": "2026-01-05T10:15:00.000Z", "updatedAt": "2026-01-05T10:15:00.000Z" }, "relationships": { "agent": { "data": { "type": "agent", "id": "agt_3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f" } }, "customerParty": { "data": 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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "A request value is invalid.", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "email: Invalid email address", "status": "422", "source": { "pointer": "/data/attributes/email" }, "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "428": { "description": "Precondition Required", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "mfa_required", "detail": "MFA verification required", "status": "428", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "429": { "description": "Too Many Requests", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "rate_limited", "detail": "Too many requests. Please try again later.", "status": "429", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying", "schema": { "type": "integer" } }, "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" } } } }, "500": { "description": "Internal Server 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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "server_error", "detail": "Something went wrong.", "status": "500", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "501": { "description": "Not Implemented", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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_implemented", "detail": "This operation is not available.", "status": "501", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "502": { "description": "Bad Gateway", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "bad_gateway", "detail": "We couldn't complete that request because one of Natural's services returned an unexpected response. Please try again.", "status": "502", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "503": { "description": "Service Unavailable", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "service_unavailable", "detail": "The service is temporarily unavailable.", "status": "503", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } } }, "security": [ { "HTTPBearer": [] } ] } }, "/agents/invitations/{id}": { "delete": { "operationId": "agents.revokeInvitation", "summary": "Revoke a pending agent invitation", "description": "Cancel a single pending agent invitation you've sent before it's accepted.", "tags": [ "Agents" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^adi_[0-9a-f]{32}$", "description": "Invitation ID (adi_*)" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Unique key for idempotent request handling. If a request with the same key was already processed, the original response is returned." }, { "name": "X-Agent-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "description": "Agent ID (agt_xxx) identifying which agent is making the request." }, { "name": "X-Instance-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 1024 }, { "type": "null" } ] }, "description": "Required when X-Agent-ID is present. Session or conversation ID for agent observability." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "description": "Resource type", "type": "string", "enum": [ "agentDelegationInvitation" ] }, "id": { "type": "string", "pattern": "^adi_[0-9a-f]{32}$", "description": "Invitation ID" }, "attributes": { "type": "object", "properties": { "developerName": { "type": "string", "description": "Developer name" }, "email": { "type": "string", "description": "Recipient email" }, "phone": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Recipient phone" }, "url": { "type": "string", "format": "uri", "description": "Shareable URL where the recipient reviews and accepts the invitation. Also sent in the invitation email; for phone invitations, deliver it yourself." }, "agentName": { "type": "string", "description": "Agent name" }, "permissions": { "type": "array", "items": { "type": "string" }, "description": "Permissions granted on accept" }, "limits": { "anyOf": [ { "type": "object", "properties": { "perTransaction": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0 }, { "type": "null" } ], "description": "Per-transaction cap, integer cents (USD)." } }, "additionalProperties": false, "title": "AgentLimitsSpec" }, { "type": "null" } ], "description": "Transaction limits" }, "status": { "enum": [ "PENDING", "ACCEPTED", "DECLINED", "EXPIRED", "CANCELED" ], "type": "string", "description": "Invitation status" }, "effectiveStatus": { "enum": [ "PENDING", "ACCEPTED", "DECLINED", "EXPIRED", "CANCELED" ], "type": "string", "description": "Resolved status, accounting for expiry" }, "expiresAt": { "type": "string", "description": "When the invitation expires" }, "acceptedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "When the invitation was accepted" }, "declinedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "When the invitation was declined" }, "cancelReason": { "anyOf": [ { "enum": [ "AGENT_RETIRED", "DEVELOPER_RETIRED", "DEVELOPER_REVOKED" ], "type": "string" }, { "type": "null" } ], "description": "Reason for cancellation" }, "tags": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" }, "description": "Custom metadata tags. Visible to any party authorized to read the resource." }, "createdAt": { "type": "string", "description": "When the invitation was created" }, "updatedAt": { "type": "string", "description": "When the invitation was last updated" } }, "required": [ "developerName", "email", "phone", "url", "agentName", "permissions", "limits", "status", "effectiveStatus", "expiresAt", "acceptedAt", "declinedAt", "cancelReason", "tags", "createdAt", "updatedAt" ], "additionalProperties": false, "title": "AgentDelegationInvitationAttributes", "description": "Invitation details" }, "relationships": { "type": "object", "properties": { "agent": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "description": "Resource type", "type": "string", "enum": [ "agent" ] }, "id": { "type": "string", "pattern": "^agt_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier" } }, "required": [ "data" ], "additionalProperties": false, "title": "ToOneRelationship", "description": "The invited agent" }, "customerParty": { "type": "object", "properties": { "data": { "anyOf": [ { "type": "object", "properties": { "type": { "description": "Resource 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" }, { "type": "null" } ] } }, "required": [ "data" ], "additionalProperties": false, "title": "NullableToOneRelationship", "description": "Customer party the invitation was accepted on (null until accept)" } }, "required": [ "agent", "customerParty" ], "additionalProperties": false, "description": "Related resources" } }, "required": [ "type", "id", "attributes", "relationships" ], "additionalProperties": false, "title": "AgentDelegationInvitationResource" }, "meta": { "type": "object", "properties": { "deleted": { "const": true, "description": "Indicates the resource was deleted" } }, "required": [ "deleted" ], "additionalProperties": false, "title": "DeletedMeta" } }, "required": [ "data", "meta" ], "additionalProperties": false, "title": "RevokeInvitationResponse" }, "examples": { "default": { "summary": "Default", "value": { "data": { "type": "agentDelegationInvitation", "id": "adi_550e8400e29b41d4a716446655440000", "attributes": { "developerName": "Acme Inc", "email": "ops@customer.com", "phone": null, "url": "https://www.natural.co/connect/adi_550e8400e29b41d4a716446655440000", "agentName": "Invoice Agent", "permissions": [ "payments.read" ], "limits": { "perTransaction": 100000 }, "status": "CANCELED", "effectiveStatus": "CANCELED", "expiresAt": "2026-01-12T10:15:00.000Z", "acceptedAt": null, "declinedAt": null, "cancelReason": "DEVELOPER_REVOKED", "tags": { "campaign": "q3_reactivation" }, "createdAt": "2026-01-05T10:15:00.000Z", "updatedAt": "2026-01-05T10:20:00.000Z" }, "relationships": { "agent": { "data": { "type": "agent", "id": "agt_3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f" } }, "customerParty": { "data": null } } }, "meta": { "deleted": true } } } } } }, "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "A request value is invalid.", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "email: Invalid email address", "status": "422", "source": { "pointer": "/data/attributes/email" }, "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "428": { "description": "Precondition Required", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "mfa_required", "detail": "MFA verification required", "status": "428", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "429": { "description": "Too Many Requests", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "rate_limited", "detail": "Too many requests. Please try again later.", "status": "429", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying", "schema": { "type": "integer" } }, "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" } } } }, "500": { "description": "Internal Server 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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "server_error", "detail": "Something went wrong.", "status": "500", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "501": { "description": "Not Implemented", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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_implemented", "detail": "This operation is not available.", "status": "501", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "502": { "description": "Bad Gateway", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "bad_gateway", "detail": "We couldn't complete that request because one of Natural's services returned an unexpected response. Please try again.", "status": "502", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "503": { "description": "Service Unavailable", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "service_unavailable", "detail": "The service is temporarily unavailable.", "status": "503", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } } }, "security": [ { "HTTPBearer": [] } ] } }, "/customers": { "get": { "operationId": "customers.list", "summary": "List customers", "description": "List customers who have delegated access to your agents.", "tags": [ "Customers" ], "parameters": [ { "name": "cursor", "in": "query", "schema": { "type": "string", "description": "Cursor for pagination" }, "allowEmptyValue": true, "allowReserved": true }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20, "description": "Maximum number of results" }, "allowEmptyValue": true, "allowReserved": true }, { "name": "X-Agent-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "description": "Agent ID (agt_xxx) identifying which agent is making the request." }, { "name": "X-Instance-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 1024 }, { "type": "null" } ] }, "description": "Required when X-Agent-ID is present. Session or conversation ID for agent observability." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "type": { "description": "Resource type", "type": "string", "enum": [ "customer" ] }, "id": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$", "description": "Customer party ID" }, "attributes": { "type": "object", "properties": { "name": { "type": "string", "description": "Customer name" }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Email address" }, "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" }, "status": { "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" } }, "required": [ "id", "status", "permissions", "createdAt" ], "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" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Agent name" }, "status": { "type": "string", "description": "Connection status" }, "permissions": { "type": "array", "items": { "type": "string" }, "description": "Permissions this agent holds" }, "limits": { "anyOf": [ { "$ref": "#/components/schemas/TransactionLimits" }, { "type": "null" } ], "description": "Transaction limits for this agent" } }, "required": [ "id", "name", "status", "permissions", "limits" ], "additionalProperties": false, "title": "CustomerConnectedAgent" }, "description": "Connected agents" } }, "required": [ "name", "email", "createdAt", "delegation", "agents" ], "additionalProperties": false, "title": "CustomerActiveAttributes", "description": "Customer attributes" } }, "required": [ "type", "id", "attributes" ], "additionalProperties": false, "title": "CustomerActiveResource", "description": "An active customer." } }, "meta": { "type": "object", "properties": { "pagination": { "type": "object", "properties": { "hasMore": { "type": "boolean" }, "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "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", "createdAt": "2026-01-04T15:30:00.000Z", "delegation": { "id": "dlg_550e8400e29b41d4a716446655440000", "status": "ACTIVE", "permissions": [ "payments.read" ], "createdAt": "2026-01-10T12:00:00.000Z" }, "agents": [ { "id": "agt_3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f", "name": "Invoice Agent", "status": "ACTIVE", "permissions": [ "payments.read" ], "limits": { "perTransaction": 100000 } } ] } } ], "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "A request value is invalid.", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "email: Invalid email address", "status": "422", "source": { "pointer": "/data/attributes/email" }, "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "428": { "description": "Precondition Required", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "mfa_required", "detail": "MFA verification required", "status": "428", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "429": { "description": "Too Many Requests", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "rate_limited", "detail": "Too many requests. Please try again later.", "status": "429", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying", "schema": { "type": "integer" } }, "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" } } } }, "500": { "description": "Internal Server 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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "server_error", "detail": "Something went wrong.", "status": "500", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "501": { "description": "Not Implemented", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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_implemented", "detail": "This operation is not available.", "status": "501", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "502": { "description": "Bad Gateway", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "bad_gateway", "detail": "We couldn't complete that request because one of Natural's services returned an unexpected response. Please try again.", "status": "502", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "503": { "description": "Service Unavailable", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "service_unavailable", "detail": "The service is temporarily unavailable.", "status": "503", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } } }, "security": [ { "HTTPBearer": [] } ] } }, "/customers/{customerId}": { "get": { "operationId": "customers.get", "summary": "Get customer", "description": "Get a customer.", "tags": [ "Customers" ], "parameters": [ { "name": "customerId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$", "description": "Customer party ID" } }, { "name": "X-Agent-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "description": "Agent ID (agt_xxx) identifying which agent is making the request." }, { "name": "X-Instance-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 1024 }, { "type": "null" } ] }, "description": "Required when X-Agent-ID is present. Session or conversation ID for agent observability." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "description": "Resource type", "type": "string", "enum": [ "customer" ] }, "id": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$", "description": "Customer party ID" }, "attributes": { "type": "object", "properties": { "name": { "type": "string", "description": "Customer name" }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Email address" }, "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" }, "status": { "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" } }, "required": [ "id", "status", "permissions", "createdAt" ], "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" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Agent name" }, "status": { "type": "string", "description": "Connection status" }, "permissions": { "type": "array", "items": { "type": "string" }, "description": "Permissions this agent holds" }, "limits": { "anyOf": [ { "$ref": "#/components/schemas/TransactionLimits" }, { "type": "null" } ], "description": "Transaction limits for this agent" } }, "required": [ "id", "name", "status", "permissions", "limits" ], "additionalProperties": false, "title": "CustomerConnectedAgent" }, "description": "Connected agents" } }, "required": [ "name", "email", "createdAt", "delegation", "agents" ], "additionalProperties": false, "title": "CustomerActiveAttributes", "description": "Customer attributes" } }, "required": [ "type", "id", "attributes" ], "additionalProperties": false, "title": "CustomerActiveResource", "description": "An active customer." } }, "required": [ "data" ], "additionalProperties": false, "title": "CustomerResponse" }, "examples": { "default": { "summary": "Default", "value": { "data": { "id": "pty_4a8c9823f39c42a5b817556766551112", "type": "customer", "attributes": { "name": "Acme Co", "email": "ops@acme.com", "createdAt": "2026-01-04T15:30:00.000Z", "delegation": { "id": "dlg_550e8400e29b41d4a716446655440000", "status": "ACTIVE", "permissions": [ "payments.read" ], "createdAt": "2026-01-10T12:00:00.000Z" }, "agents": [ { "id": "agt_3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f", "name": "Invoice Agent", "status": "ACTIVE", "permissions": [ "payments.read" ], "limits": { "perTransaction": 100000 } } ] } } } } } } }, "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "A request value is invalid.", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "email: Invalid email address", "status": "422", "source": { "pointer": "/data/attributes/email" }, "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "428": { "description": "Precondition Required", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "mfa_required", "detail": "MFA verification required", "status": "428", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "429": { "description": "Too Many Requests", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "rate_limited", "detail": "Too many requests. Please try again later.", "status": "429", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying", "schema": { "type": "integer" } }, "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" } } } }, "500": { "description": "Internal Server 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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "server_error", "detail": "Something went wrong.", "status": "500", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "501": { "description": "Not Implemented", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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_implemented", "detail": "This operation is not available.", "status": "501", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "502": { "description": "Bad Gateway", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "bad_gateway", "detail": "We couldn't complete that request because one of Natural's services returned an unexpected response. Please try again.", "status": "502", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "503": { "description": "Service Unavailable", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "service_unavailable", "detail": "The service is temporarily unavailable.", "status": "503", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } } }, "security": [ { "HTTPBearer": [] } ] } }, "/customers/invitations": { "get": { "operationId": "customers.listInvitations", "summary": "List customer invitations", "description": "List pending customer invitations you've sent.", "tags": [ "Customers" ], "parameters": [ { "name": "cursor", "in": "query", "schema": { "type": "string", "description": "Cursor for pagination" }, "allowEmptyValue": true, "allowReserved": true }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20, "description": "Maximum number of results" }, "allowEmptyValue": true, "allowReserved": true }, { "name": "X-Agent-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "description": "Agent ID (agt_xxx) identifying which agent is making the request." }, { "name": "X-Instance-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 1024 }, { "type": "null" } ] }, "description": "Required when X-Agent-ID is present. Session or conversation ID for agent observability." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "type": { "description": "Resource type", "type": "string", "enum": [ "customerInvitation" ] }, "id": { "type": "string", "description": "Recipient email" }, "attributes": { "type": "object", "properties": { "status": { "type": "string", "description": "Invitation status" }, "party": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$", "description": "Party ID" }, "name": { "type": "string", "description": "Customer name" }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Email address" }, "createdAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "When the customer was created" } }, "required": [ "id", "name", "email", "createdAt" ], "additionalProperties": false, "title": "CustomerParty" }, { "type": "null" } ], "description": "Customer party, or null if they haven't signed up yet" }, "email": { "type": "string", "description": "Recipient email" }, "createdAt": { "type": "string", "format": "date-time", "description": "When the invitation was created" }, "agentInvitations": { "type": "array", "items": { "type": "object", "properties": { "invitationId": { "type": "string", "pattern": "^adi_[0-9a-f]{32}$", "description": "Invitation ID" }, "agent": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^agt_[0-9a-f]{32}$", "description": "Agent ID" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Agent name" } }, "required": [ "id", "name" ], "additionalProperties": false, "title": "CustomerAgent", "description": "The invited agent" }, "permissions": { "type": "array", "items": { "type": "string" }, "description": "Permissions requested for this agent" }, "url": { "type": "string", "format": "uri", "description": "Shareable URL where the recipient reviews and accepts the invitation. Also sent in the invitation email; for phone invitations, deliver it yourself." }, "createdAt": { "type": "string", "format": "date-time", "description": "When the invitation was created" }, "expiresAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "When the invitation expires, or null if it does not expire" }, "tags": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" }, "description": "Custom metadata tags. Visible to any party authorized to read the resource." } }, "required": [ "invitationId", "agent", "permissions", "url", "createdAt", "expiresAt", "tags" ], "additionalProperties": false, "title": "AgentInvitation" }, "description": "Agent invitations sent to this recipient" } }, "required": [ "status", "party", "email", "createdAt", "agentInvitations" ], "additionalProperties": false, "title": "CustomerInvitationAttributes", "description": "Resource attributes" } }, "required": [ "type", "id", "attributes" ], "additionalProperties": false, "title": "CustomerInvitationResource", "description": "A pending customer invitation grouped by recipient." } }, "meta": { "type": "object", "properties": { "pagination": { "type": "object", "properties": { "hasMore": { "type": "boolean" }, "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "hasMore", "nextCursor" ], "additionalProperties": false, "title": "PaginationMeta" } }, "required": [ "pagination" ], "additionalProperties": false } }, "required": [ "data", "meta" ], "additionalProperties": false, "title": "PendingInvitationListResponse" }, "examples": { "default": { "summary": "Default", "value": { "data": [ { "type": "customerInvitation", "id": "ops@acme.com", "attributes": { "status": "PENDING", "party": null, "email": "ops@acme.com", "createdAt": "2026-01-05T10:15:00.000Z", "agentInvitations": [ { "invitationId": "adi_550e8400e29b41d4a716446655440000", "agent": { "id": "agt_3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f", "name": "Invoice Agent" }, "permissions": [ "payments.read" ], "url": "https://www.natural.co/connect/adi_550e8400e29b41d4a716446655440000", "createdAt": "2026-01-05T10:15:00.000Z", "expiresAt": "2026-01-12T10:15:00.000Z", "tags": { "campaign": "q3_reactivation" } }, { "invitationId": "adi_660f9500f30c52e5b827557766551111", "agent": { "id": "agt_4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a", "name": "Refunds Agent" }, "permissions": [ "payments.create", "payments.read" ], "url": "https://www.natural.co/connect/adi_660f9500f30c52e5b827557766551111", "createdAt": "2026-01-05T10:15:00.000Z", "expiresAt": "2026-01-12T10:15:00.000Z", "tags": { "campaign": "q3_reactivation" } } ] } } ], "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "A request value is invalid.", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "email: Invalid email address", "status": "422", "source": { "pointer": "/data/attributes/email" }, "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "428": { "description": "Precondition Required", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "mfa_required", "detail": "MFA verification required", "status": "428", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "429": { "description": "Too Many Requests", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "rate_limited", "detail": "Too many requests. Please try again later.", "status": "429", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying", "schema": { "type": "integer" } }, "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" } } } }, "500": { "description": "Internal Server 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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "server_error", "detail": "Something went wrong.", "status": "500", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "501": { "description": "Not Implemented", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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_implemented", "detail": "This operation is not available.", "status": "501", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "502": { "description": "Bad Gateway", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "bad_gateway", "detail": "We couldn't complete that request because one of Natural's services returned an unexpected response. Please try again.", "status": "502", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "503": { "description": "Service Unavailable", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "service_unavailable", "detail": "The service is temporarily unavailable.", "status": "503", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } } }, "security": [ { "HTTPBearer": [] } ] }, "post": { "operationId": "customers.createInvitations", "summary": "Invite customers", "description": "Invite customers to connect with your agents.", "tags": [ "Customers" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "attributes": { "type": "object", "properties": { "recipients": { "type": "array", "minItems": 1, "maxItems": 100, "items": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "email" ] }, "value": { "type": "string", "format": "email", "description": "Email address" } }, "required": [ "type", "value" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "phone" ] }, "value": { "type": "string", "description": "Phone number in E.164 format" } }, "required": [ "type", "value" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "party_id" ] }, "value": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$", "description": "Natural party ID (pty_*)" } }, "required": [ "type", "value" ], "additionalProperties": false } ], "title": "CustomerInvitationRecipient" }, "description": "Recipients to invite. Each recipient gets one invitation per agent." }, "agents": { "type": "array", "minItems": 1, "maxItems": 50, "items": { "type": "object", "properties": { "agentId": { "type": "string", "pattern": "^agt_[0-9a-f]{32}$", "description": "Agent ID" }, "permissions": { "type": "array", "minItems": 1, "items": { "enum": [ "payments.read", "payments.create", "external_accounts.create", "wallets.read", "wallets.update", "party.read", "party.update" ], "type": "string" }, "description": "Permissions to grant this agent" }, "limits": { "type": "object", "properties": { "perTransaction": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0 }, { "type": "null" } ], "description": "Per-transaction cap, integer cents (USD)." } }, "additionalProperties": false, "description": "Transaction limits for this agent" } }, "required": [ "agentId", "permissions" ], "additionalProperties": false, "title": "CustomerInvitationAgentSpec" }, "description": "Agents to grant access to. Each recipient receives an invitation for every agent listed." }, "expiresAt": { "type": "string", "format": "date-time", "description": "When the invitation expires. Defaults to 7 days from now." }, "tags": { "type": "object", "propertyNames": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[a-zA-Z0-9_]+$" }, "additionalProperties": { "type": "string", "minLength": 1, "maxLength": 256 }, "description": "Tags applied to every invitation in this request" } }, "required": [ "recipients", "agents" ], "additionalProperties": false, "description": "Customer invitation creation attributes" } }, "required": [ "attributes" ], "additionalProperties": false, "description": "Resource object" } }, "required": [ "data" ], "additionalProperties": false, "title": "CustomerInvitationCreateRequest" }, "examples": { "default": { "summary": "Default", "value": { "data": { "attributes": { "recipients": [ { "type": "email", "value": "ops@acme.com" } ], "agents": [ { "agentId": "agt_3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f", "permissions": [ "payments.read" ], "limits": { "perTransaction": 100000 } } ], "expiresAt": "2026-01-12T10:15:00.000Z", "tags": { "campaign": "q3_reactivation" } } } } } } } } }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "type": { "description": "Resource type", "type": "string", "enum": [ "agentDelegationInvitation" ] }, "id": { "type": "string", "pattern": "^adi_[0-9a-f]{32}$", "description": "Invitation ID" }, "attributes": { "type": "object", "properties": { "developerName": { "type": "string", "description": "Developer name" }, "email": { "type": "string", "description": "Recipient email" }, "phone": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Recipient phone" }, "url": { "type": "string", "format": "uri", "description": "Shareable URL where the recipient reviews and accepts the invitation. Also sent in the invitation email; for phone invitations, deliver it yourself." }, "agentName": { "type": "string", "description": "Agent name" }, "permissions": { "type": "array", "items": { "type": "string" }, "description": "Permissions granted on accept" }, "limits": { "anyOf": [ { "type": "object", "properties": { "perTransaction": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0 }, { "type": "null" } ], "description": "Per-transaction cap, integer cents (USD)." } }, "additionalProperties": false, "title": "AgentLimitsSpec" }, { "type": "null" } ], "description": "Transaction limits" }, "status": { "enum": [ "PENDING", "ACCEPTED", "DECLINED", "EXPIRED", "CANCELED" ], "type": "string", "description": "Invitation status" }, "effectiveStatus": { "enum": [ "PENDING", "ACCEPTED", "DECLINED", "EXPIRED", "CANCELED" ], "type": "string", "description": "Resolved status, accounting for expiry" }, "expiresAt": { "type": "string", "description": "When the invitation expires" }, "acceptedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "When the invitation was accepted" }, "declinedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "When the invitation was declined" }, "cancelReason": { "anyOf": [ { "enum": [ "AGENT_RETIRED", "DEVELOPER_RETIRED", "DEVELOPER_REVOKED" ], "type": "string" }, { "type": "null" } ], "description": "Reason for cancellation" }, "tags": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" }, "description": "Custom metadata tags. Visible to any party authorized to read the resource." }, "createdAt": { "type": "string", "description": "When the invitation was created" }, "updatedAt": { "type": "string", "description": "When the invitation was last updated" } }, "required": [ "developerName", "email", "phone", "url", "agentName", "permissions", "limits", "status", "effectiveStatus", "expiresAt", "acceptedAt", "declinedAt", "cancelReason", "tags", "createdAt", "updatedAt" ], "additionalProperties": false, "title": "AgentDelegationInvitationAttributes", "description": "Invitation details" }, "relationships": { "type": "object", "properties": { "agent": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "description": "Resource type", "type": "string", "enum": [ "agent" ] }, "id": { "type": "string", "pattern": "^agt_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier" } }, "required": [ "data" ], "additionalProperties": false, "title": "ToOneRelationship", "description": "The invited agent" }, "customerParty": { "type": "object", "properties": { "data": { "anyOf": [ { "type": "object", "properties": { "type": { "description": "Resource 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" }, { "type": "null" } ] } }, "required": [ "data" ], "additionalProperties": false, "title": "NullableToOneRelationship", "description": "Customer party the invitation was accepted on (null until accept)" } }, "required": [ "agent", "customerParty" ], "additionalProperties": false, "description": "Related resources" } }, "required": [ "type", "id", "attributes", "relationships" ], "additionalProperties": false, "title": "AgentDelegationInvitationResource" }, "description": "Created invitations" }, "meta": { "type": "object", "properties": { "failedRecipients": { "type": "array", "items": { "type": "object", "properties": { "recipient": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "email" ] }, "value": { "type": "string", "format": "email", "description": "Email address" } }, "required": [ "type", "value" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "phone" ] }, "value": { "type": "string", "description": "Phone number in E.164 format" } }, "required": [ "type", "value" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "party_id" ] }, "value": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$", "description": "Natural party ID (pty_*)" } }, "required": [ "type", "value" ], "additionalProperties": false } ], "title": "CustomerInvitationRecipient", "description": "The recipient that failed" }, "reason": { "type": "string", "description": "Why the whole recipient batch failed" } }, "required": [ "recipient", "reason" ], "additionalProperties": false }, "description": "Recipients where the invitation could not be created." } }, "required": [ "failedRecipients" ], "additionalProperties": false, "description": "Metadata about the batch" } }, "required": [ "data", "meta" ], "additionalProperties": false, "title": "CustomerInvitationCreateResponse" }, "examples": { "default": { "summary": "Default", "value": { "data": [ { "type": "agentDelegationInvitation", "id": "adi_550e8400e29b41d4a716446655440000", "attributes": { "developerName": "Acme Co", "email": "ops@acme.com", "phone": null, "url": "https://www.natural.co/connect/adi_550e8400e29b41d4a716446655440000", "agentName": "Invoice Agent", "permissions": [ "payments.read" ], "limits": { "perTransaction": 100000 }, "status": "PENDING", "effectiveStatus": "PENDING", "expiresAt": "2026-01-12T10:15:00.000Z", "acceptedAt": null, "declinedAt": null, "cancelReason": null, "tags": { "campaign": "q3_reactivation" }, "createdAt": "2026-01-05T10:15:00.000Z", "updatedAt": "2026-01-05T10:15:00.000Z" }, "relationships": { "agent": { "data": { "type": "agent", "id": "agt_3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f" } }, "customerParty": { "data": null } } } ], "meta": { "failedRecipients": [] } } } } } }, "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "A request value is invalid.", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "email: Invalid email address", "status": "422", "source": { "pointer": "/data/attributes/email" }, "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "428": { "description": "Precondition Required", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "mfa_required", "detail": "MFA verification required", "status": "428", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "429": { "description": "Too Many Requests", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "rate_limited", "detail": "Too many requests. Please try again later.", "status": "429", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying", "schema": { "type": "integer" } }, "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" } } } }, "500": { "description": "Internal Server 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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "server_error", "detail": "Something went wrong.", "status": "500", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "501": { "description": "Not Implemented", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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_implemented", "detail": "This operation is not available.", "status": "501", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "502": { "description": "Bad Gateway", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "bad_gateway", "detail": "We couldn't complete that request because one of Natural's services returned an unexpected response. Please try again.", "status": "502", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "503": { "description": "Service Unavailable", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "service_unavailable", "detail": "The service is temporarily unavailable.", "status": "503", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } } }, "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "X-Agent-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "description": "Agent ID (agt_xxx) identifying which agent is making the request." }, { "name": "X-Instance-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 1024 }, { "type": "null" } ] }, "description": "Required when X-Agent-ID is present. Session or conversation ID for agent observability." } ] } }, "/customers/invitations/{invitationId}": { "delete": { "operationId": "customers.revokeInvitation", "summary": "Revoke customer invitation", "description": "Cancel a pending customer invitation.", "tags": [ "Customers" ], "parameters": [ { "name": "invitationId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^adi_[0-9a-f]{32}$", "description": "Invitation ID" } }, { "name": "X-Agent-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "description": "Agent ID (agt_xxx) identifying which agent is making the request." }, { "name": "X-Instance-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 1024 }, { "type": "null" } ] }, "description": "Required when X-Agent-ID is present. Session or conversation ID for agent observability." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "description": "Resource type", "type": "string", "enum": [ "agentDelegationInvitation" ] }, "id": { "type": "string", "pattern": "^adi_[0-9a-f]{32}$", "description": "Invitation ID" }, "attributes": { "type": "object", "properties": { "developerName": { "type": "string", "description": "Developer name" }, "email": { "type": "string", "description": "Recipient email" }, "phone": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Recipient phone" }, "url": { "type": "string", "format": "uri", "description": "Shareable URL where the recipient reviews and accepts the invitation. Also sent in the invitation email; for phone invitations, deliver it yourself." }, "agentName": { "type": "string", "description": "Agent name" }, "permissions": { "type": "array", "items": { "type": "string" }, "description": "Permissions granted on accept" }, "limits": { "anyOf": [ { "type": "object", "properties": { "perTransaction": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0 }, { "type": "null" } ], "description": "Per-transaction cap, integer cents (USD)." } }, "additionalProperties": false, "title": "AgentLimitsSpec" }, { "type": "null" } ], "description": "Transaction limits" }, "status": { "enum": [ "PENDING", "ACCEPTED", "DECLINED", "EXPIRED", "CANCELED" ], "type": "string", "description": "Invitation status" }, "effectiveStatus": { "enum": [ "PENDING", "ACCEPTED", "DECLINED", "EXPIRED", "CANCELED" ], "type": "string", "description": "Resolved status, accounting for expiry" }, "expiresAt": { "type": "string", "description": "When the invitation expires" }, "acceptedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "When the invitation was accepted" }, "declinedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "When the invitation was declined" }, "cancelReason": { "anyOf": [ { "enum": [ "AGENT_RETIRED", "DEVELOPER_RETIRED", "DEVELOPER_REVOKED" ], "type": "string" }, { "type": "null" } ], "description": "Reason for cancellation" }, "tags": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" }, "description": "Custom metadata tags. Visible to any party authorized to read the resource." }, "createdAt": { "type": "string", "description": "When the invitation was created" }, "updatedAt": { "type": "string", "description": "When the invitation was last updated" } }, "required": [ "developerName", "email", "phone", "url", "agentName", "permissions", "limits", "status", "effectiveStatus", "expiresAt", "acceptedAt", "declinedAt", "cancelReason", "tags", "createdAt", "updatedAt" ], "additionalProperties": false, "title": "AgentDelegationInvitationAttributes", "description": "Invitation details" }, "relationships": { "type": "object", "properties": { "agent": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "description": "Resource type", "type": "string", "enum": [ "agent" ] }, "id": { "type": "string", "pattern": "^agt_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier" } }, "required": [ "data" ], "additionalProperties": false, "title": "ToOneRelationship", "description": "The invited agent" }, "customerParty": { "type": "object", "properties": { "data": { "anyOf": [ { "type": "object", "properties": { "type": { "description": "Resource 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" }, { "type": "null" } ] } }, "required": [ "data" ], "additionalProperties": false, "title": "NullableToOneRelationship", "description": "Customer party the invitation was accepted on (null until accept)" } }, "required": [ "agent", "customerParty" ], "additionalProperties": false, "description": "Related resources" } }, "required": [ "type", "id", "attributes", "relationships" ], "additionalProperties": false, "title": "AgentDelegationInvitationResource" }, "meta": { "type": "object", "properties": { "deleted": { "const": true, "description": "Indicates the resource was deleted" } }, "required": [ "deleted" ], "additionalProperties": false, "title": "DeletedMeta" } }, "required": [ "data", "meta" ], "additionalProperties": false, "title": "CustomerInvitationSingleResponse" }, "examples": { "default": { "summary": "Default", "value": { "data": { "type": "agentDelegationInvitation", "id": "adi_550e8400e29b41d4a716446655440000", "attributes": { "developerName": "Acme Co", "email": "ops@acme.com", "phone": null, "url": "https://www.natural.co/connect/adi_550e8400e29b41d4a716446655440000", "agentName": "Invoice Agent", "permissions": [ "payments.read" ], "limits": { "perTransaction": 100000 }, "status": "CANCELED", "effectiveStatus": "CANCELED", "expiresAt": "2026-01-12T10:15:00.000Z", "acceptedAt": null, "declinedAt": null, "cancelReason": "DEVELOPER_REVOKED", "tags": { "campaign": "q3_reactivation" }, "createdAt": "2026-01-05T10:15:00.000Z", "updatedAt": "2026-01-05T10:20:00.000Z" }, "relationships": { "agent": { "data": { "type": "agent", "id": "agt_3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f" } }, "customerParty": { "data": null } } }, "meta": { "deleted": true } } } } } }, "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "A request value is invalid.", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "email: Invalid email address", "status": "422", "source": { "pointer": "/data/attributes/email" }, "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "428": { "description": "Precondition Required", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "mfa_required", "detail": "MFA verification required", "status": "428", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "429": { "description": "Too Many Requests", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "rate_limited", "detail": "Too many requests. Please try again later.", "status": "429", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying", "schema": { "type": "integer" } }, "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" } } } }, "500": { "description": "Internal Server 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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "server_error", "detail": "Something went wrong.", "status": "500", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "501": { "description": "Not Implemented", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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_implemented", "detail": "This operation is not available.", "status": "501", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "502": { "description": "Bad Gateway", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "bad_gateway", "detail": "We couldn't complete that request because one of Natural's services returned an unexpected response. Please try again.", "status": "502", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "503": { "description": "Service Unavailable", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "service_unavailable", "detail": "The service is temporarily unavailable.", "status": "503", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } } }, "security": [ { "HTTPBearer": [] } ] } }, "/customers/{customerId}/agents/{agentId}": { "delete": { "operationId": "customers.revokeAgent", "summary": "Revoke agent access", "description": "Remove an agent's access to a customer.", "tags": [ "Customers" ], "parameters": [ { "name": "customerId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$", "description": "Customer party ID" } }, { "name": "agentId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^agt_[0-9a-f]{32}$", "description": "Agent ID" } }, { "name": "X-Agent-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "description": "Agent ID (agt_xxx) identifying which agent is making the request." }, { "name": "X-Instance-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 1024 }, { "type": "null" } ] }, "description": "Required when X-Agent-ID is present. Session or conversation ID for agent observability." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "description": "Resource type", "type": "string", "enum": [ "customer" ] }, "id": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$", "description": "Customer party ID" }, "attributes": { "type": "object", "properties": { "name": { "type": "string", "description": "Customer name" }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Email address" }, "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" }, "status": { "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" } }, "required": [ "id", "status", "permissions", "createdAt" ], "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" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Agent name" }, "status": { "type": "string", "description": "Connection status" }, "permissions": { "type": "array", "items": { "type": "string" }, "description": "Permissions this agent holds" }, "limits": { "anyOf": [ { "$ref": "#/components/schemas/TransactionLimits" }, { "type": "null" } ], "description": "Transaction limits for this agent" } }, "required": [ "id", "name", "status", "permissions", "limits" ], "additionalProperties": false, "title": "CustomerConnectedAgent" }, "description": "Connected agents" } }, "required": [ "name", "email", "createdAt", "delegation", "agents" ], "additionalProperties": false, "title": "CustomerActiveAttributes", "description": "Customer attributes" } }, "required": [ "type", "id", "attributes" ], "additionalProperties": false, "title": "CustomerActiveResource", "description": "An active customer." } }, "required": [ "data" ], "additionalProperties": false, "title": "CustomerResponse" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "description": "Resource type", "type": "string", "enum": [ "customer" ] }, "id": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$", "description": "Customer party ID" }, "attributes": { "type": "object", "properties": { "name": { "type": "string", "description": "Customer name" }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Email address" }, "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" }, "status": { "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" } }, "required": [ "id", "status", "permissions", "createdAt" ], "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" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Agent name" }, "status": { "type": "string", "description": "Connection status" }, "permissions": { "type": "array", "items": { "type": "string" }, "description": "Permissions this agent holds" }, "limits": { "anyOf": [ { "$ref": "#/components/schemas/TransactionLimits" }, { "type": "null" } ], "description": "Transaction limits for this agent" } }, "required": [ "id", "name", "status", "permissions", "limits" ], "additionalProperties": false, "title": "CustomerConnectedAgent" }, "description": "Connected agents" } }, "required": [ "name", "email", "createdAt", "delegation", "agents" ], "additionalProperties": false, "title": "CustomerActiveAttributes", "description": "Customer attributes" } }, "required": [ "type", "id", "attributes" ], "additionalProperties": false, "title": "CustomerActiveResource", "description": "An active customer." }, "meta": { "type": "object", "properties": { "deleted": { "const": true, "description": "Indicates the resource was deleted" } }, "required": [ "deleted" ], "additionalProperties": false, "title": "DeletedMeta" } }, "required": [ "data", "meta" ], "additionalProperties": false } ], "title": "CustomerAgentRevokeResponse" }, "examples": { "default": { "summary": "Default", "value": { "data": { "id": "pty_4a8c9823f39c42a5b817556766551112", "type": "customer", "attributes": { "name": "Acme Co", "email": "ops@acme.com", "createdAt": "2026-01-04T15:30:00.000Z", "delegation": { "id": "dlg_550e8400e29b41d4a716446655440000", "status": "ACTIVE", "permissions": [ "payments.read" ], "createdAt": "2026-01-10T12:00:00.000Z" }, "agents": [ { "id": "agt_3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f", "name": "Invoice Agent", "status": "ACTIVE", "permissions": [ "payments.read" ], "limits": { "perTransaction": 100000 } } ] } }, "meta": { "deleted": true } } } } } }, "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "A request value is invalid.", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "email: Invalid email address", "status": "422", "source": { "pointer": "/data/attributes/email" }, "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "428": { "description": "Precondition Required", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "mfa_required", "detail": "MFA verification required", "status": "428", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "429": { "description": "Too Many Requests", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "rate_limited", "detail": "Too many requests. Please try again later.", "status": "429", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying", "schema": { "type": "integer" } }, "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" } } } }, "500": { "description": "Internal Server 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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "server_error", "detail": "Something went wrong.", "status": "500", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "501": { "description": "Not Implemented", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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_implemented", "detail": "This operation is not available.", "status": "501", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "502": { "description": "Bad Gateway", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "bad_gateway", "detail": "We couldn't complete that request because one of Natural's services returned an unexpected response. Please try again.", "status": "502", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "503": { "description": "Service Unavailable", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "service_unavailable", "detail": "The service is temporarily unavailable.", "status": "503", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } } }, "security": [ { "HTTPBearer": [] } ] } }, "/counterparties": { "get": { "operationId": "counterparties.list", "summary": "List counterparties", "description": "List counterparties.", "tags": [ "Counterparties" ], "parameters": [ { "name": "direction", "in": "query", "schema": { "enum": [ "sent", "received" ], "type": "string", "description": "Optional filter. When set, only counterparties with activity in that direction are returned, and pagination is scoped to that subset. Omit to return every counterparty." }, "allowEmptyValue": true, "allowReserved": true }, { "name": "cursor", "in": "query", "schema": { "type": "string", "description": "Cursor for pagination" }, "allowEmptyValue": true, "allowReserved": true }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50, "description": "Maximum number of results" }, "allowEmptyValue": true, "allowReserved": true }, { "name": "X-Agent-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "description": "Agent ID (agt_xxx) identifying which agent is making the request." }, { "name": "X-Instance-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 1024 }, { "type": "null" } ] }, "description": "Required when X-Agent-ID is present. Session or conversation ID for agent observability." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "anyOf": [ { "type": "string", "pattern": "^pty_[0-9a-f]{32}$" }, { "type": "string", "pattern": "^unknown_[0-9a-f]{16}$" } ], "description": "Counterparty ID: a party id (pty_xxx), or unknown_xxx for unclaimed payments" }, "type": { "description": "Resource type", "type": "string", "enum": [ "party" ] }, "attributes": { "type": "object", "properties": { "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Counterparty display name" }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Counterparty primary email" }, "status": { "anyOf": [ { "enum": [ "PROVISIONAL", "ACTIVE", "SUSPENDED", "INACTIVE" ], "type": "string" }, { "type": "null" } ], "description": "Counterparty status" } }, "required": [ "name", "email", "status" ], "additionalProperties": false, "title": "CounterpartyAttributes", "description": "Counterparty attributes" } }, "required": [ "id", "type", "attributes" ], "additionalProperties": false, "title": "CounterpartyResource" } }, "meta": { "type": "object", "properties": { "pagination": { "type": "object", "properties": { "hasMore": { "type": "boolean" }, "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "hasMore", "nextCursor" ], "additionalProperties": false, "title": "PaginationMeta" } }, "required": [ "pagination" ], "additionalProperties": false } }, "required": [ "data", "meta" ], "additionalProperties": false, "title": "CounterpartyListResponse" }, "examples": { "default": { "summary": "Default", "value": { "data": [ { "id": "pty_550e8400e29b41d4a716446655440002", "type": "party", "attributes": { "name": "Acme Supplies", "email": "payables@acmesupplies.com", "status": "ACTIVE" } } ], "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "A request value is invalid.", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "email: Invalid email address", "status": "422", "source": { "pointer": "/data/attributes/email" }, "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "428": { "description": "Precondition Required", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "mfa_required", "detail": "MFA verification required", "status": "428", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "429": { "description": "Too Many Requests", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "rate_limited", "detail": "Too many requests. Please try again later.", "status": "429", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying", "schema": { "type": "integer" } }, "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" } } } }, "500": { "description": "Internal Server 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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "server_error", "detail": "Something went wrong.", "status": "500", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "501": { "description": "Not Implemented", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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_implemented", "detail": "This operation is not available.", "status": "501", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "502": { "description": "Bad Gateway", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "bad_gateway", "detail": "We couldn't complete that request because one of Natural's services returned an unexpected response. Please try again.", "status": "502", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "503": { "description": "Service Unavailable", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "service_unavailable", "detail": "The service is temporarily unavailable.", "status": "503", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } } }, "security": [ { "HTTPBearer": [] } ] } }, "/payments": { "post": { "operationId": "payments.create", "summary": "Create payment", "description": "Create a payment.", "tags": [ "Payments" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "attributes": { "type": "object", "properties": { "amount": { "type": "integer", "exclusiveMinimum": 0, "description": "Amount in cents" }, "counterparty": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "email" ] }, "value": { "type": "string", "format": "email", "description": "Email address" } }, "required": [ "type", "value" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "phone" ] }, "value": { "type": "string", "description": "Phone number in E.164 format" } }, "required": [ "type", "value" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "party_id" ] }, "value": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$", "description": "Natural party ID (pty_*)" } }, "required": [ "type", "value" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "agent_id" ] }, "value": { "type": "string", "pattern": "^agt_[0-9a-f]{32}$", "description": "Natural agent ID (agt_*)" } }, "required": [ "type", "value" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "handle" ] }, "value": { "type": "string", "pattern": "^@?[A-Za-z0-9](?:[A-Za-z0-9-]{0,28}[A-Za-z0-9])?(?:\\/[A-Za-z0-9](?:[A-Za-z0-9-]{0,28}[A-Za-z0-9])?)?$", "description": "Natural handle (@namespace or @namespace/slug)" } }, "required": [ "type", "value" ], "additionalProperties": false } ], "title": "PaymentRecipientCounterparty", "description": "Recipient identifier. Provide exactly one typed email, phone, party ID, agent ID, or handle (@namespace[/slug]) value. Agent recipients (agent ID or @namespace/slug) credit the agent's preferred wallet when one is set, otherwise the owner party's default wallet." }, "customerPartyId": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$", "description": "Sender party ID (pty_*). Omit to send from your own wallet; provide for delegated payments on behalf of a customer." }, "currency": { "enum": [ "USD" ], "type": "string", "default": "USD", "description": "Currency code" }, "description": { "type": "string", "maxLength": 500, "description": "Payment description. Maximum 500 characters." }, "walletId": { "type": "string", "pattern": "^wal_[0-9a-f]{32}$", "description": "Source wallet ID (wal_*). Omit to pay from the sender party's default wallet." } }, "required": [ "amount", "counterparty" ], "additionalProperties": false, "title": "PaymentCreateAttributes" } }, "required": [ "attributes" ], "additionalProperties": false } }, "required": [ "data" ], "additionalProperties": false, "title": "PaymentCreateRequest" }, "examples": { "default": { "summary": "Default", "value": { "data": { "attributes": { "amount": 500000, "currency": "USD", "counterparty": { "type": "party_id", "value": "pty_019cd1798d627ad9bc302511c4f2c115" }, "customerPartyId": "pty_019cd1798d617f65a79cb965dda9eac3", "description": "Payment for Q4 2025 development work" } } } } } } } }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "payment" ] }, "id": { "type": "string", "pattern": "^pay_[0-9a-f]{32}$" }, "attributes": { "type": "object", "properties": { "amount": { "type": "integer", "description": "Amount in cents" }, "currency": { "type": "string", "description": "Currency code" }, "status": { "enum": [ "CREATED", "PROCESSING", "PENDING_CLAIM", "IN_REVIEW", "COMPLETED", "FAILED", "RETURNED", "APPROVAL_DENIED", "CANCELED" ], "type": "string", "description": "Payment status" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Payment description" }, "createdAt": { "type": "string", "description": "When this payment was created" }, "updatedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "When this payment was last updated" } }, "required": [ "amount", "currency", "status", "description", "createdAt", "updatedAt" ], "additionalProperties": false, "title": "PaymentAttributes", "description": "Resource attributes" }, "relationships": { "type": "object", "properties": { "sender": { "type": "object", "properties": { "data": { "anyOf": [ { "type": "object", "properties": { "type": { "description": "Resource 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" }, { "type": "null" } ] } }, "required": [ "data" ], "additionalProperties": false, "title": "NullableToOneRelationship", "description": "Party that initiated the payment, when the sender is on Natural." }, "recipient": { "type": "object", "properties": { "data": { "anyOf": [ { "type": "object", "properties": { "type": { "description": "Resource 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" }, { "type": "null" } ] } }, "required": [ "data" ], "additionalProperties": false, "title": "NullableToOneRelationship", "description": "Recipient party for this payment, when known." }, "recipientAgent": { "type": "object", "properties": { "data": { "anyOf": [ { "type": "object", "properties": { "type": { "description": "Resource type", "type": "string", "enum": [ "agent" ] }, "id": { "type": "string", "pattern": "^agt_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier" }, { "type": "null" } ] } }, "required": [ "data" ], "additionalProperties": false, "title": "NullableToOneRelationship", "description": "Recipient agent when the caller addressed an agent ID. Null otherwise, including when the recipient was addressed as an email, phone, or party ID." }, "transaction": { "type": "object", "properties": { "data": { "anyOf": [ { "type": "object", "properties": { "type": { "description": "Resource type", "type": "string", "enum": [ "transaction" ] }, "id": { "type": "string" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier" }, { "type": "null" } ] } }, "required": [ "data" ], "additionalProperties": false, "title": "NullableToOneRelationship", "description": "Sender-side transaction row for this payment, when available." }, "paymentRequest": { "type": "object", "properties": { "data": { "anyOf": [ { "type": "object", "properties": { "type": { "description": "Resource type", "type": "string", "enum": [ "paymentRequest" ] }, "id": { "type": "string", "pattern": "^prq_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier" }, { "type": "null" } ] } }, "required": [ "data" ], "additionalProperties": false, "title": "NullableToOneRelationship", "description": "Payment request that produced this payment, when applicable." } }, "required": [ "sender", "recipient", "recipientAgent", "transaction", "paymentRequest" ], "additionalProperties": false, "title": "PaymentRelationships", "description": "Resource relationships" } }, "required": [ "type", "id", "attributes", "relationships" ], "additionalProperties": false, "title": "PaymentResource" } }, "required": [ "data" ], "additionalProperties": false, "title": "PaymentResponse" }, "examples": { "default": { "summary": "Default", "value": { "data": { "type": "payment", "id": "pay_550e8400e29b41d4a716446655440000", "attributes": { "amount": 500000, "currency": "USD", "status": "PROCESSING", "description": "Payment for Q4 2025 development work", "createdAt": "2026-01-04T15:30:00Z", "updatedAt": "2026-01-04T15:30:00Z" }, "relationships": { "sender": { "data": { "type": "party", "id": "pty_019cd1798d617f65a79cb965dda9eac3" } }, "recipient": { "data": { "type": "party", "id": "pty_019cd1798d627ad9bc302511c4f2c115" } }, "recipientAgent": { "data": null }, "transaction": { "data": { "type": "transaction", "id": "txn_550e8400e29b41d4a716446655440000" } }, "paymentRequest": { "data": 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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "A request value is invalid.", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "email: Invalid email address", "status": "422", "source": { "pointer": "/data/attributes/email" }, "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "428": { "description": "Precondition Required", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "mfa_required", "detail": "MFA verification required", "status": "428", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "429": { "description": "Too Many Requests", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "rate_limited", "detail": "Too many requests. Please try again later.", "status": "429", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying", "schema": { "type": "integer" } }, "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" } } } }, "500": { "description": "Internal Server 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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "server_error", "detail": "Something went wrong.", "status": "500", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "501": { "description": "Not Implemented", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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_implemented", "detail": "This operation is not available.", "status": "501", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "502": { "description": "Bad Gateway", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "bad_gateway", "detail": "We couldn't complete that request because one of Natural's services returned an unexpected response. Please try again.", "status": "502", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "503": { "description": "Service Unavailable", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "service_unavailable", "detail": "The service is temporarily unavailable.", "status": "503", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } } }, "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Unique key for idempotent request handling. If a request with the same key was already processed, the original response is returned." }, { "name": "X-Agent-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "description": "Agent ID (agt_xxx) identifying which agent is making the request." }, { "name": "X-Instance-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 1024 }, { "type": "null" } ] }, "description": "Required when X-Agent-ID is present. Session or conversation ID for agent observability." } ] }, "get": { "operationId": "payments.list", "summary": "List payments", "description": "List payments initiated by the authenticated party.", "tags": [ "Payments" ], "parameters": [ { "name": "partyId", "in": "query", "schema": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$", "description": "Party ID for delegated payment lookup" }, "allowEmptyValue": true, "allowReserved": true }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50, "description": "Results per page" }, "allowEmptyValue": true, "allowReserved": true }, { "name": "cursor", "in": "query", "schema": { "type": "string", "description": "Pagination cursor from previous response" }, "allowEmptyValue": true, "allowReserved": true }, { "name": "X-Agent-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "description": "Agent ID (agt_xxx) identifying which agent is making the request." }, { "name": "X-Instance-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 1024 }, { "type": "null" } ] }, "description": "Required when X-Agent-ID is present. Session or conversation ID for agent observability." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "payment" ] }, "id": { "type": "string", "pattern": "^pay_[0-9a-f]{32}$" }, "attributes": { "type": "object", "properties": { "amount": { "type": "integer", "description": "Amount in cents" }, "currency": { "type": "string", "description": "Currency code" }, "status": { "enum": [ "CREATED", "PROCESSING", "PENDING_CLAIM", "IN_REVIEW", "COMPLETED", "FAILED", "RETURNED", "APPROVAL_DENIED", "CANCELED" ], "type": "string", "description": "Payment status" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Payment description" }, "createdAt": { "type": "string", "description": "When this payment was created" }, "updatedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "When this payment was last updated" } }, "required": [ "amount", "currency", "status", "description", "createdAt", "updatedAt" ], "additionalProperties": false, "title": "PaymentAttributes", "description": "Resource attributes" }, "relationships": { "type": "object", "properties": { "sender": { "type": "object", "properties": { "data": { "anyOf": [ { "type": "object", "properties": { "type": { "description": "Resource 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" }, { "type": "null" } ] } }, "required": [ "data" ], "additionalProperties": false, "title": "NullableToOneRelationship", "description": "Party that initiated the payment, when the sender is on Natural." }, "recipient": { "type": "object", "properties": { "data": { "anyOf": [ { "type": "object", "properties": { "type": { "description": "Resource 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" }, { "type": "null" } ] } }, "required": [ "data" ], "additionalProperties": false, "title": "NullableToOneRelationship", "description": "Recipient party for this payment, when known." }, "recipientAgent": { "type": "object", "properties": { "data": { "anyOf": [ { "type": "object", "properties": { "type": { "description": "Resource type", "type": "string", "enum": [ "agent" ] }, "id": { "type": "string", "pattern": "^agt_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier" }, { "type": "null" } ] } }, "required": [ "data" ], "additionalProperties": false, "title": "NullableToOneRelationship", "description": "Recipient agent when the caller addressed an agent ID. Null otherwise, including when the recipient was addressed as an email, phone, or party ID." }, "transaction": { "type": "object", "properties": { "data": { "anyOf": [ { "type": "object", "properties": { "type": { "description": "Resource type", "type": "string", "enum": [ "transaction" ] }, "id": { "type": "string" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier" }, { "type": "null" } ] } }, "required": [ "data" ], "additionalProperties": false, "title": "NullableToOneRelationship", "description": "Sender-side transaction row for this payment, when available." }, "paymentRequest": { "type": "object", "properties": { "data": { "anyOf": [ { "type": "object", "properties": { "type": { "description": "Resource type", "type": "string", "enum": [ "paymentRequest" ] }, "id": { "type": "string", "pattern": "^prq_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier" }, { "type": "null" } ] } }, "required": [ "data" ], "additionalProperties": false, "title": "NullableToOneRelationship", "description": "Payment request that produced this payment, when applicable." } }, "required": [ "sender", "recipient", "recipientAgent", "transaction", "paymentRequest" ], "additionalProperties": false, "title": "PaymentRelationships", "description": "Resource relationships" } }, "required": [ "type", "id", "attributes", "relationships" ], "additionalProperties": false, "title": "PaymentResource" } }, "meta": { "type": "object", "properties": { "pagination": { "type": "object", "properties": { "hasMore": { "type": "boolean" }, "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "hasMore", "nextCursor" ], "additionalProperties": false, "title": "PaginationMeta" } }, "required": [ "pagination" ], "additionalProperties": false } }, "required": [ "data", "meta" ], "additionalProperties": false, "title": "PaymentListResponse" }, "examples": { "default": { "summary": "Default", "value": { "data": [ { "type": "payment", "id": "pay_550e8400e29b41d4a716446655440000", "attributes": { "amount": 500000, "currency": "USD", "status": "PROCESSING", "description": "Payment for Q4 2025 development work", "createdAt": "2026-01-04T15:30:00Z", "updatedAt": "2026-01-04T15:30:00Z" }, "relationships": { "sender": { "data": { "type": "party", "id": "pty_019cd1798d617f65a79cb965dda9eac3" } }, "recipient": { "data": { "type": "party", "id": "pty_019cd1798d627ad9bc302511c4f2c115" } }, "recipientAgent": { "data": null }, "transaction": { "data": { "type": "transaction", "id": "txn_550e8400e29b41d4a716446655440000" } }, "paymentRequest": { "data": 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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "A request value is invalid.", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "email: Invalid email address", "status": "422", "source": { "pointer": "/data/attributes/email" }, "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "428": { "description": "Precondition Required", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "mfa_required", "detail": "MFA verification required", "status": "428", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "429": { "description": "Too Many Requests", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "rate_limited", "detail": "Too many requests. Please try again later.", "status": "429", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying", "schema": { "type": "integer" } }, "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" } } } }, "500": { "description": "Internal Server 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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "server_error", "detail": "Something went wrong.", "status": "500", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "501": { "description": "Not Implemented", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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_implemented", "detail": "This operation is not available.", "status": "501", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "502": { "description": "Bad Gateway", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "bad_gateway", "detail": "We couldn't complete that request because one of Natural's services returned an unexpected response. Please try again.", "status": "502", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "503": { "description": "Service Unavailable", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "service_unavailable", "detail": "The service is temporarily unavailable.", "status": "503", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } } }, "security": [ { "HTTPBearer": [] } ] } }, "/payments/{paymentId}": { "get": { "operationId": "payments.get", "summary": "Get payment", "description": "Get a payment initiated by the authenticated party.", "tags": [ "Payments" ], "parameters": [ { "name": "paymentId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^pay_[0-9a-f]{32}$" } }, { "name": "partyId", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$", "description": "Party ID for delegated payment lookup" }, "allowEmptyValue": true, "allowReserved": true }, { "name": "X-Agent-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "description": "Agent ID (agt_xxx) identifying which agent is making the request." }, { "name": "X-Instance-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 1024 }, { "type": "null" } ] }, "description": "Required when X-Agent-ID is present. Session or conversation ID for agent observability." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "payment" ] }, "id": { "type": "string", "pattern": "^pay_[0-9a-f]{32}$" }, "attributes": { "type": "object", "properties": { "amount": { "type": "integer", "description": "Amount in cents" }, "currency": { "type": "string", "description": "Currency code" }, "status": { "enum": [ "CREATED", "PROCESSING", "PENDING_CLAIM", "IN_REVIEW", "COMPLETED", "FAILED", "RETURNED", "APPROVAL_DENIED", "CANCELED" ], "type": "string", "description": "Payment status" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Payment description" }, "createdAt": { "type": "string", "description": "When this payment was created" }, "updatedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "When this payment was last updated" } }, "required": [ "amount", "currency", "status", "description", "createdAt", "updatedAt" ], "additionalProperties": false, "title": "PaymentAttributes", "description": "Resource attributes" }, "relationships": { "type": "object", "properties": { "sender": { "type": "object", "properties": { "data": { "anyOf": [ { "type": "object", "properties": { "type": { "description": "Resource 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" }, { "type": "null" } ] } }, "required": [ "data" ], "additionalProperties": false, "title": "NullableToOneRelationship", "description": "Party that initiated the payment, when the sender is on Natural." }, "recipient": { "type": "object", "properties": { "data": { "anyOf": [ { "type": "object", "properties": { "type": { "description": "Resource 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" }, { "type": "null" } ] } }, "required": [ "data" ], "additionalProperties": false, "title": "NullableToOneRelationship", "description": "Recipient party for this payment, when known." }, "recipientAgent": { "type": "object", "properties": { "data": { "anyOf": [ { "type": "object", "properties": { "type": { "description": "Resource type", "type": "string", "enum": [ "agent" ] }, "id": { "type": "string", "pattern": "^agt_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier" }, { "type": "null" } ] } }, "required": [ "data" ], "additionalProperties": false, "title": "NullableToOneRelationship", "description": "Recipient agent when the caller addressed an agent ID. Null otherwise, including when the recipient was addressed as an email, phone, or party ID." }, "transaction": { "type": "object", "properties": { "data": { "anyOf": [ { "type": "object", "properties": { "type": { "description": "Resource type", "type": "string", "enum": [ "transaction" ] }, "id": { "type": "string" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier" }, { "type": "null" } ] } }, "required": [ "data" ], "additionalProperties": false, "title": "NullableToOneRelationship", "description": "Sender-side transaction row for this payment, when available." }, "paymentRequest": { "type": "object", "properties": { "data": { "anyOf": [ { "type": "object", "properties": { "type": { "description": "Resource type", "type": "string", "enum": [ "paymentRequest" ] }, "id": { "type": "string", "pattern": "^prq_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier" }, { "type": "null" } ] } }, "required": [ "data" ], "additionalProperties": false, "title": "NullableToOneRelationship", "description": "Payment request that produced this payment, when applicable." } }, "required": [ "sender", "recipient", "recipientAgent", "transaction", "paymentRequest" ], "additionalProperties": false, "title": "PaymentRelationships", "description": "Resource relationships" } }, "required": [ "type", "id", "attributes", "relationships" ], "additionalProperties": false, "title": "PaymentResource" } }, "required": [ "data" ], "additionalProperties": false, "title": "PaymentResponse" }, "examples": { "default": { "summary": "Default", "value": { "data": { "type": "payment", "id": "pay_550e8400e29b41d4a716446655440000", "attributes": { "amount": 500000, "currency": "USD", "status": "PROCESSING", "description": "Payment for Q4 2025 development work", "createdAt": "2026-01-04T15:30:00Z", "updatedAt": "2026-01-04T15:30:00Z" }, "relationships": { "sender": { "data": { "type": "party", "id": "pty_019cd1798d617f65a79cb965dda9eac3" } }, "recipient": { "data": { "type": "party", "id": "pty_019cd1798d627ad9bc302511c4f2c115" } }, "recipientAgent": { "data": null }, "transaction": { "data": { "type": "transaction", "id": "txn_550e8400e29b41d4a716446655440000" } }, "paymentRequest": { "data": 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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "A request value is invalid.", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "email: Invalid email address", "status": "422", "source": { "pointer": "/data/attributes/email" }, "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "428": { "description": "Precondition Required", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "mfa_required", "detail": "MFA verification required", "status": "428", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "429": { "description": "Too Many Requests", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "rate_limited", "detail": "Too many requests. Please try again later.", "status": "429", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying", "schema": { "type": "integer" } }, "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" } } } }, "500": { "description": "Internal Server 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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "server_error", "detail": "Something went wrong.", "status": "500", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "501": { "description": "Not Implemented", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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_implemented", "detail": "This operation is not available.", "status": "501", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "502": { "description": "Bad Gateway", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "bad_gateway", "detail": "We couldn't complete that request because one of Natural's services returned an unexpected response. Please try again.", "status": "502", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "503": { "description": "Service Unavailable", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "service_unavailable", "detail": "The service is temporarily unavailable.", "status": "503", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } } }, "security": [ { "HTTPBearer": [] } ] } }, "/payments/{paymentId}/cancel": { "post": { "operationId": "payments.cancel", "summary": "Cancel payment", "description": "Cancel a pending-claim payment before the recipient starts claiming it.", "tags": [ "Payments" ], "parameters": [ { "name": "paymentId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^pay_[0-9a-f]{32}$" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Unique key for idempotent request handling. If a request with the same key was already processed, the original response is returned." }, { "name": "X-Agent-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "description": "Agent ID (agt_xxx) identifying which agent is making the request." }, { "name": "X-Instance-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 1024 }, { "type": "null" } ] }, "description": "Required when X-Agent-ID is present. Session or conversation ID for agent observability." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "payment" ] }, "id": { "type": "string", "pattern": "^pay_[0-9a-f]{32}$" }, "attributes": { "type": "object", "properties": { "amount": { "type": "integer", "description": "Amount in cents" }, "currency": { "type": "string", "description": "Currency code" }, "status": { "enum": [ "CREATED", "PROCESSING", "PENDING_CLAIM", "IN_REVIEW", "COMPLETED", "FAILED", "RETURNED", "APPROVAL_DENIED", "CANCELED" ], "type": "string", "description": "Payment status" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Payment description" }, "createdAt": { "type": "string", "description": "When this payment was created" }, "updatedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "When this payment was last updated" } }, "required": [ "amount", "currency", "status", "description", "createdAt", "updatedAt" ], "additionalProperties": false, "title": "PaymentAttributes", "description": "Resource attributes" }, "relationships": { "type": "object", "properties": { "sender": { "type": "object", "properties": { "data": { "anyOf": [ { "type": "object", "properties": { "type": { "description": "Resource 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" }, { "type": "null" } ] } }, "required": [ "data" ], "additionalProperties": false, "title": "NullableToOneRelationship", "description": "Party that initiated the payment, when the sender is on Natural." }, "recipient": { "type": "object", "properties": { "data": { "anyOf": [ { "type": "object", "properties": { "type": { "description": "Resource 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" }, { "type": "null" } ] } }, "required": [ "data" ], "additionalProperties": false, "title": "NullableToOneRelationship", "description": "Recipient party for this payment, when known." }, "recipientAgent": { "type": "object", "properties": { "data": { "anyOf": [ { "type": "object", "properties": { "type": { "description": "Resource type", "type": "string", "enum": [ "agent" ] }, "id": { "type": "string", "pattern": "^agt_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier" }, { "type": "null" } ] } }, "required": [ "data" ], "additionalProperties": false, "title": "NullableToOneRelationship", "description": "Recipient agent when the caller addressed an agent ID. Null otherwise, including when the recipient was addressed as an email, phone, or party ID." }, "transaction": { "type": "object", "properties": { "data": { "anyOf": [ { "type": "object", "properties": { "type": { "description": "Resource type", "type": "string", "enum": [ "transaction" ] }, "id": { "type": "string" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier" }, { "type": "null" } ] } }, "required": [ "data" ], "additionalProperties": false, "title": "NullableToOneRelationship", "description": "Sender-side transaction row for this payment, when available." }, "paymentRequest": { "type": "object", "properties": { "data": { "anyOf": [ { "type": "object", "properties": { "type": { "description": "Resource type", "type": "string", "enum": [ "paymentRequest" ] }, "id": { "type": "string", "pattern": "^prq_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier" }, { "type": "null" } ] } }, "required": [ "data" ], "additionalProperties": false, "title": "NullableToOneRelationship", "description": "Payment request that produced this payment, when applicable." } }, "required": [ "sender", "recipient", "recipientAgent", "transaction", "paymentRequest" ], "additionalProperties": false, "title": "PaymentRelationships", "description": "Resource relationships" } }, "required": [ "type", "id", "attributes", "relationships" ], "additionalProperties": false, "title": "PaymentResource" } }, "required": [ "data" ], "additionalProperties": false, "title": "PaymentResponse" }, "examples": { "default": { "summary": "Default", "value": { "data": { "type": "payment", "id": "pay_550e8400e29b41d4a716446655440000", "attributes": { "amount": 500000, "currency": "USD", "status": "CANCELED", "description": "Payment for Q4 2025 development work", "createdAt": "2026-01-04T15:30:00Z", "updatedAt": "2026-01-04T15:35:00Z" }, "relationships": { "sender": { "data": { "type": "party", "id": "pty_019cd1798d617f65a79cb965dda9eac3" } }, "recipient": { "data": { "type": "party", "id": "pty_019cd1798d627ad9bc302511c4f2c115" } }, "recipientAgent": { "data": null }, "transaction": { "data": { "type": "transaction", "id": "txn_550e8400e29b41d4a716446655440000" } }, "paymentRequest": { "data": 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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "A request value is invalid.", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "email: Invalid email address", "status": "422", "source": { "pointer": "/data/attributes/email" }, "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "428": { "description": "Precondition Required", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "mfa_required", "detail": "MFA verification required", "status": "428", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "429": { "description": "Too Many Requests", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "rate_limited", "detail": "Too many requests. Please try again later.", "status": "429", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying", "schema": { "type": "integer" } }, "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" } } } }, "500": { "description": "Internal Server 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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "server_error", "detail": "Something went wrong.", "status": "500", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "501": { "description": "Not Implemented", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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_implemented", "detail": "This operation is not available.", "status": "501", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "502": { "description": "Bad Gateway", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "bad_gateway", "detail": "We couldn't complete that request because one of Natural's services returned an unexpected response. Please try again.", "status": "502", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "503": { "description": "Service Unavailable", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "service_unavailable", "detail": "The service is temporarily unavailable.", "status": "503", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } } }, "security": [ { "HTTPBearer": [] } ] } }, "/transactions": { "get": { "operationId": "transactions.list", "summary": "List transactions", "description": "List transactions visible to your party.", "tags": [ "Transactions" ], "parameters": [ { "name": "type", "in": "query", "schema": { "enum": [ "payment", "transfer", "all" ], "type": "string", "default": "all" }, "allowEmptyValue": true, "allowReserved": true }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50, "description": "Results per page" }, "allowEmptyValue": true, "allowReserved": true }, { "name": "cursor", "in": "query", "schema": { "type": "string", "description": "Pagination cursor from previous response" }, "allowEmptyValue": true, "allowReserved": true }, { "name": "counterpartyPartyId", "in": "query", "schema": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$", "description": "Restrict results to transactions whose payment counterparty is this party." }, "allowEmptyValue": true, "allowReserved": true }, { "name": "walletId", "in": "query", "schema": { "type": "string", "pattern": "^wal_[0-9a-f]{32}$", "description": "Restrict results to transactions visible through this wallet." }, "allowEmptyValue": true, "allowReserved": true }, { "name": "customerPartyId", "in": "query", "schema": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$", "description": "Restrict results to delegated customer activity executed on behalf of this customer party. This maps to the transaction subject party, not the payment counterparty." }, "allowEmptyValue": true, "allowReserved": true }, { "name": "delegated", "in": "query", "schema": { "type": "boolean", "description": "When true, restrict results to transactions executed through an agent delegation (agentDelegationId IS NOT NULL) — the connection-scoped feed." }, "allowEmptyValue": true, "allowReserved": true }, { "name": "X-Agent-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "description": "Agent ID (agt_xxx) identifying which agent is making the request." }, { "name": "X-Instance-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 1024 }, { "type": "null" } ] }, "description": "Required when X-Agent-ID is present. Session or conversation ID for agent observability." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "transaction" ] }, "id": { "type": "string", "pattern": "^txn_[0-9a-f]{32}$", "description": "Transaction handle (txn_xxx)" }, "attributes": { "type": "object", "properties": { "amount": { "type": "integer", "description": "Amount in cents" }, "currency": { "type": "string", "description": "Currency code" }, "status": { "type": "string", "description": "Transaction status" }, "createdAt": { "type": "string", "description": "When this transaction was created" }, "transactionType": { "enum": [ "payment", "transfer" ], "type": "string", "description": "Transaction type: payment | transfer" }, "direction": { "enum": [ "INBOUND", "OUTBOUND" ], "type": "string", "description": "Direction: INBOUND | OUTBOUND" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Payment description" }, "updatedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "When this transaction was last updated" }, "expectedAvailableAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Projected funds-available time for transfers. Null when no projection exists and null for payments." } }, "required": [ "amount", "currency", "status", "createdAt", "transactionType", "direction", "description", "updatedAt", "expectedAvailableAt" ], "additionalProperties": false, "title": "TransactionAttributes", "description": "Resource attributes" }, "relationships": { "type": "object", "properties": { "sourceParty": { "type": "object", "properties": { "data": { "anyOf": [ { "type": "object", "properties": { "type": { "description": "Resource 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" }, { "type": "null" } ] } }, "required": [ "data" ], "additionalProperties": false, "title": "NullableToOneRelationship", "description": "Source party" }, "destinationParty": { "type": "object", "properties": { "data": { "anyOf": [ { "type": "object", "properties": { "type": { "description": "Resource 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" }, { "type": "null" } ] } }, "required": [ "data" ], "additionalProperties": false, "title": "NullableToOneRelationship", "description": "Destination party" }, "payment": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "description": "Resource type", "type": "string", "enum": [ "payment" ] }, "id": { "type": "string", "pattern": "^pay_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier" } }, "required": [ "data" ], "additionalProperties": false, "description": "Payment that produced this transaction. Present only when the authenticated caller can access the payment resource." }, "transfer": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "description": "Resource type", "type": "string", "enum": [ "transfer" ] }, "id": { "type": "string", "pattern": "^trf_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier" } }, "required": [ "data" ], "additionalProperties": false, "description": "Transfer that produced this transaction. Present only when the authenticated caller can access the transfer resource." }, "wallet": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "description": "Resource type", "type": "string", "enum": [ "wallet" ] }, "id": { "type": "string", "pattern": "^wal_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier" } }, "required": [ "data" ], "additionalProperties": false, "description": "Wallet whose ledger row made this transaction visible." } }, "required": [ "sourceParty", "destinationParty" ], "additionalProperties": false, "title": "TransactionRelationships", "description": "Resource relationships" } }, "required": [ "type", "id", "attributes", "relationships" ], "additionalProperties": false, "title": "TransactionResource" } }, "meta": { "type": "object", "properties": { "pagination": { "type": "object", "properties": { "hasMore": { "type": "boolean" }, "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "hasMore", "nextCursor" ], "additionalProperties": false, "title": "PaginationMeta" } }, "required": [ "pagination" ], "additionalProperties": false } }, "required": [ "data", "meta" ], "additionalProperties": false, "title": "TransactionListResponse" }, "examples": { "default": { "summary": "Default", "value": { "data": [ { "type": "transaction", "id": "txn_650e8400e29b41d4a716446655440000", "attributes": { "amount": 50000, "currency": "USD", "status": "PROCESSING", "description": "Cash in", "createdAt": "2026-01-04T15:30:00Z", "updatedAt": "2026-01-04T15:31:00Z", "transactionType": "transfer", "direction": "INBOUND", "expectedAvailableAt": null }, "relationships": { "sourceParty": { "data": null }, "destinationParty": { "data": { "type": "party", "id": "pty_7c9e6679e29b41d4a716446655440001" } }, "transfer": { "data": { "type": "transfer", "id": "trf_650e8400e29b41d4a716446655440000" } } } } ], "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "A request value is invalid.", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "email: Invalid email address", "status": "422", "source": { "pointer": "/data/attributes/email" }, "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "428": { "description": "Precondition Required", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "mfa_required", "detail": "MFA verification required", "status": "428", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "429": { "description": "Too Many Requests", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "rate_limited", "detail": "Too many requests. Please try again later.", "status": "429", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying", "schema": { "type": "integer" } }, "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" } } } }, "500": { "description": "Internal Server 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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "server_error", "detail": "Something went wrong.", "status": "500", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "501": { "description": "Not Implemented", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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_implemented", "detail": "This operation is not available.", "status": "501", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "502": { "description": "Bad Gateway", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "bad_gateway", "detail": "We couldn't complete that request because one of Natural's services returned an unexpected response. Please try again.", "status": "502", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "503": { "description": "Service Unavailable", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "service_unavailable", "detail": "The service is temporarily unavailable.", "status": "503", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } } }, "security": [ { "HTTPBearer": [] } ] } }, "/transactions/{transactionId}": { "get": { "operationId": "transactions.get", "summary": "Get transaction", "description": "Get a single transaction visible to your party.", "tags": [ "Transactions" ], "parameters": [ { "name": "transactionId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^txn_[0-9a-f]{32}$", "description": "Transaction handle (txn_xxx)" } }, { "name": "partyId", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$", "description": "Party ID for delegated transaction lookup" }, "allowEmptyValue": true, "allowReserved": true }, { "name": "X-Agent-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "description": "Agent ID (agt_xxx) identifying which agent is making the request." }, { "name": "X-Instance-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 1024 }, { "type": "null" } ] }, "description": "Required when X-Agent-ID is present. Session or conversation ID for agent observability." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "transaction" ] }, "id": { "type": "string", "pattern": "^txn_[0-9a-f]{32}$", "description": "Transaction handle (txn_xxx)" }, "attributes": { "type": "object", "properties": { "amount": { "type": "integer", "description": "Amount in cents" }, "currency": { "type": "string", "description": "Currency code" }, "status": { "type": "string", "description": "Transaction status" }, "createdAt": { "type": "string", "description": "When this transaction was created" }, "transactionType": { "enum": [ "payment", "transfer" ], "type": "string", "description": "Transaction type: payment | transfer" }, "direction": { "enum": [ "INBOUND", "OUTBOUND" ], "type": "string", "description": "Direction: INBOUND | OUTBOUND" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Payment description" }, "updatedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "When this transaction was last updated" }, "expectedAvailableAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Projected funds-available time for transfers. Null when no projection exists and null for payments." } }, "required": [ "amount", "currency", "status", "createdAt", "transactionType", "direction", "description", "updatedAt", "expectedAvailableAt" ], "additionalProperties": false, "title": "TransactionAttributes", "description": "Resource attributes" }, "relationships": { "type": "object", "properties": { "sourceParty": { "type": "object", "properties": { "data": { "anyOf": [ { "type": "object", "properties": { "type": { "description": "Resource 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" }, { "type": "null" } ] } }, "required": [ "data" ], "additionalProperties": false, "title": "NullableToOneRelationship", "description": "Source party" }, "destinationParty": { "type": "object", "properties": { "data": { "anyOf": [ { "type": "object", "properties": { "type": { "description": "Resource 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" }, { "type": "null" } ] } }, "required": [ "data" ], "additionalProperties": false, "title": "NullableToOneRelationship", "description": "Destination party" }, "payment": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "description": "Resource type", "type": "string", "enum": [ "payment" ] }, "id": { "type": "string", "pattern": "^pay_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier" } }, "required": [ "data" ], "additionalProperties": false, "description": "Payment that produced this transaction. Present only when the authenticated caller can access the payment resource." }, "transfer": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "description": "Resource type", "type": "string", "enum": [ "transfer" ] }, "id": { "type": "string", "pattern": "^trf_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier" } }, "required": [ "data" ], "additionalProperties": false, "description": "Transfer that produced this transaction. Present only when the authenticated caller can access the transfer resource." }, "wallet": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "description": "Resource type", "type": "string", "enum": [ "wallet" ] }, "id": { "type": "string", "pattern": "^wal_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier" } }, "required": [ "data" ], "additionalProperties": false, "description": "Wallet whose ledger row made this transaction visible." } }, "required": [ "sourceParty", "destinationParty" ], "additionalProperties": false, "title": "TransactionRelationships", "description": "Resource relationships" } }, "required": [ "type", "id", "attributes", "relationships" ], "additionalProperties": false, "title": "TransactionResource" } }, "required": [ "data" ], "additionalProperties": false, "title": "TransactionSingleResponse" }, "examples": { "default": { "summary": "Default", "value": { "data": { "type": "transaction", "id": "txn_550e8400e29b41d4a716446655440000", "attributes": { "amount": 100000, "currency": "USD", "status": "COMPLETED", "description": "Invoice payment", "createdAt": "2026-01-04T15:30:00Z", "updatedAt": "2026-01-04T15:31:00Z", "transactionType": "payment", "direction": "OUTBOUND", "expectedAvailableAt": null }, "relationships": { "sourceParty": { "data": { "type": "party", "id": "pty_7c9e6679e29b41d4a716446655440001" } }, "destinationParty": { "data": { "type": "party", "id": "pty_7c9e6679e29b41d4a716446655440002" } }, "payment": { "data": { "type": "payment", "id": "pay_550e8400e29b41d4a716446655440000" } } } } } } } } }, "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "A request value is invalid.", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "email: Invalid email address", "status": "422", "source": { "pointer": "/data/attributes/email" }, "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "428": { "description": "Precondition Required", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "mfa_required", "detail": "MFA verification required", "status": "428", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "429": { "description": "Too Many Requests", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "rate_limited", "detail": "Too many requests. Please try again later.", "status": "429", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying", "schema": { "type": "integer" } }, "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" } } } }, "500": { "description": "Internal Server 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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "server_error", "detail": "Something went wrong.", "status": "500", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "501": { "description": "Not Implemented", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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_implemented", "detail": "This operation is not available.", "status": "501", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "502": { "description": "Bad Gateway", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "bad_gateway", "detail": "We couldn't complete that request because one of Natural's services returned an unexpected response. Please try again.", "status": "502", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "503": { "description": "Service Unavailable", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "service_unavailable", "detail": "The service is temporarily unavailable.", "status": "503", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } } }, "security": [ { "HTTPBearer": [] } ] } }, "/transfers/deposit": { "post": { "operationId": "transfers.initiateDeposit", "summary": "Initiate deposit", "description": "Initiate a wallet deposit.", "tags": [ "Transfers" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "attributes": { "type": "object", "properties": { "amount": { "type": "integer", "minimum": 100, "description": "Amount in cents" }, "currency": { "type": "string", "default": "USD", "description": "Currency code" }, "externalAccountId": { "type": "string", "pattern": "^eac_[0-9a-f]{32}$", "description": "External account ID (eac_*)" }, "walletId": { "type": "string", "pattern": "^wal_[0-9a-f]{32}$", "description": "Target wallet for the deposit. Defaults to the party's default wallet when omitted; external accounts remain party-level." }, "description": { "type": "string", "maxLength": 255, "description": "Deposit description" } }, "required": [ "amount", "externalAccountId" ], "additionalProperties": false, "title": "DepositCreateAttributes", "description": "Resource attributes" } }, "required": [ "attributes" ], "additionalProperties": false, "title": "DepositCreateData" } }, "required": [ "data" ], "additionalProperties": false }, "examples": { "default": { "summary": "Default", "value": { "data": { "attributes": { "amount": 50000, "currency": "USD", "externalAccountId": "eac_550e8400e29b41d4a716446655440000", "description": "Wallet top-up" } } } } } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "transfer" ] }, "id": { "type": "string", "pattern": "^trf_[0-9a-f]{32}$" }, "attributes": { "type": "object", "properties": { "type": { "enum": [ "deposit", "withdrawal", "internal" ], "type": "string", "description": "Transfer type" }, "amount": { "type": "integer", "description": "Amount in cents" }, "currency": { "type": "string", "description": "Currency code" }, "status": { "enum": [ "CREATED", "APPROVAL_DENIED", "PROCESSING", "IN_REVIEW", "COMPLETED", "FAILED", "RETURNED", "CANCELED" ], "type": "string", "description": "Transfer status" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Transfer description" }, "externalAccountDisplayMask": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Masked external account display" }, "expectedAvailableAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Expected availability time, when known" }, "failure": { "anyOf": [ { "type": "object", "properties": { "code": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Failure code, when available" }, "reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Failure reason, when available" } }, "required": [ "code", "reason" ], "additionalProperties": false }, { "type": "null" } ], "description": "Failure details when this transfer failed." }, "return": { "anyOf": [ { "type": "object", "properties": { "code": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Return code, when available" }, "reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Return reason, when available" }, "returnedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "When this transfer returned" } }, "required": [ "code", "reason", "returnedAt" ], "additionalProperties": false }, { "type": "null" } ], "description": "Return details when this transfer was returned." }, "submittedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "When this transfer was submitted" }, "settledAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "When this transfer settled" }, "createdAt": { "type": "string", "description": "When this transfer was created" }, "updatedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "When this transfer was last updated" } }, "required": [ "type", "amount", "currency", "status", "description", "externalAccountDisplayMask", "expectedAvailableAt", "failure", "return", "submittedAt", "settledAt", "createdAt", "updatedAt" ], "additionalProperties": false, "title": "TransferAttributes", "description": "Resource attributes" }, "relationships": { "type": "object", "properties": { "party": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "description": "Resource 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 transfer" }, "wallet": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "description": "Resource type", "type": "string", "enum": [ "wallet" ] }, "id": { "type": "string", "pattern": "^wal_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier" } }, "required": [ "data" ], "additionalProperties": false, "title": "ToOneRelationship", "description": "Wallet for this transfer" }, "destWallet": { "type": "object", "properties": { "data": { "anyOf": [ { "type": "object", "properties": { "type": { "description": "Resource type", "type": "string", "enum": [ "wallet" ] }, "id": { "type": "string", "pattern": "^wal_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier" }, { "type": "null" } ] } }, "required": [ "data" ], "additionalProperties": false, "title": "NullableToOneRelationship", "description": "Destination wallet for internal transfers." }, "externalAccount": { "type": "object", "properties": { "data": { "anyOf": [ { "type": "object", "properties": { "type": { "description": "Resource type", "type": "string", "enum": [ "externalAccount" ] }, "id": { "type": "string", "pattern": "^eac_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier" }, { "type": "null" } ] } }, "required": [ "data" ], "additionalProperties": false, "title": "NullableToOneRelationship", "description": "External account used for this transfer, when available." }, "transaction": { "type": "object", "properties": { "data": { "anyOf": [ { "type": "object", "properties": { "type": { "description": "Resource type", "type": "string", "enum": [ "transaction" ] }, "id": { "type": "string" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier" }, { "type": "null" } ] } }, "required": [ "data" ], "additionalProperties": false, "title": "NullableToOneRelationship", "description": "Primary transaction row for this transfer, when available." } }, "required": [ "party", "wallet", "externalAccount", "transaction" ], "additionalProperties": false, "title": "TransferRelationships", "description": "Resource relationships" } }, "required": [ "type", "id", "attributes", "relationships" ], "additionalProperties": false, "title": "TransferResource" } }, "required": [ "data" ], "additionalProperties": false }, "examples": { "default": { "summary": "Default", "value": { "data": { "type": "transfer", "id": "trf_550e8400e29b41d4a716446655440000", "attributes": { "type": "deposit", "amount": 50000, "currency": "USD", "status": "PROCESSING", "description": "Wallet top-up", "externalAccountDisplayMask": "6789", "expectedAvailableAt": null, "failure": null, "return": null, "submittedAt": "2026-01-04T15:30:00Z", "settledAt": null, "createdAt": "2026-01-04T15:30:00Z", "updatedAt": "2026-01-04T15:30:00Z" }, "relationships": { "party": { "data": { "type": "party", "id": "pty_7c9e6679e29b41d4a716446655440001" } }, "wallet": { "data": { "type": "wallet", "id": "wal_550e8400e29b41d4a716446655440000" } }, "externalAccount": { "data": { "type": "externalAccount", "id": "eac_550e8400e29b41d4a716446655440000" } }, "transaction": { "data": { "type": "transaction", "id": "txn_550e8400e29b41d4a716446655440000" } } } } } } } } }, "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "A request value is invalid.", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "email: Invalid email address", "status": "422", "source": { "pointer": "/data/attributes/email" }, "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "428": { "description": "Precondition Required", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "mfa_required", "detail": "MFA verification required", "status": "428", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "429": { "description": "Too Many Requests", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "rate_limited", "detail": "Too many requests. Please try again later.", "status": "429", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying", "schema": { "type": "integer" } }, "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" } } } }, "500": { "description": "Internal Server 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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "server_error", "detail": "Something went wrong.", "status": "500", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "501": { "description": "Not Implemented", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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_implemented", "detail": "This operation is not available.", "status": "501", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "502": { "description": "Bad Gateway", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "bad_gateway", "detail": "We couldn't complete that request because one of Natural's services returned an unexpected response. Please try again.", "status": "502", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "503": { "description": "Service Unavailable", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "service_unavailable", "detail": "The service is temporarily unavailable.", "status": "503", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } } }, "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Unique key for idempotent request handling. If a request with the same key was already processed, the original response is returned." }, { "name": "X-Agent-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "description": "Agent ID (agt_xxx) identifying which agent is making the request." }, { "name": "X-Instance-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 1024 }, { "type": "null" } ] }, "description": "Required when X-Agent-ID is present. Session or conversation ID for agent observability." } ] } }, "/transfers/withdraw": { "post": { "operationId": "transfers.initiateWithdrawal", "summary": "Initiate withdrawal", "description": "Initiate a wallet withdrawal.", "tags": [ "Transfers" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "attributes": { "type": "object", "properties": { "amount": { "type": "integer", "exclusiveMinimum": 0, "description": "Amount in cents" }, "currency": { "type": "string", "default": "USD", "description": "Currency code" }, "externalAccountId": { "type": "string", "pattern": "^eac_[0-9a-f]{32}$", "description": "External account ID (eac_*)" }, "walletId": { "type": "string", "pattern": "^wal_[0-9a-f]{32}$", "description": "Source wallet for the withdrawal. Defaults to the party's default wallet when omitted; external accounts remain party-level." }, "description": { "type": "string", "maxLength": 255, "description": "Withdrawal description" } }, "required": [ "amount", "externalAccountId" ], "additionalProperties": false, "title": "WithdrawCreateAttributes", "description": "Resource attributes" } }, "required": [ "attributes" ], "additionalProperties": false, "title": "WithdrawCreateData" } }, "required": [ "data" ], "additionalProperties": false }, "examples": { "default": { "summary": "Default", "value": { "data": { "attributes": { "amount": 12500, "currency": "USD", "externalAccountId": "eac_550e8400e29b41d4a716446655440000", "description": "Payout transfer" } } } } } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "transfer" ] }, "id": { "type": "string", "pattern": "^trf_[0-9a-f]{32}$" }, "attributes": { "type": "object", "properties": { "type": { "enum": [ "deposit", "withdrawal", "internal" ], "type": "string", "description": "Transfer type" }, "amount": { "type": "integer", "description": "Amount in cents" }, "currency": { "type": "string", "description": "Currency code" }, "status": { "enum": [ "CREATED", "APPROVAL_DENIED", "PROCESSING", "IN_REVIEW", "COMPLETED", "FAILED", "RETURNED", "CANCELED" ], "type": "string", "description": "Transfer status" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Transfer description" }, "externalAccountDisplayMask": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Masked external account display" }, "expectedAvailableAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Expected availability time, when known" }, "failure": { "anyOf": [ { "type": "object", "properties": { "code": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Failure code, when available" }, "reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Failure reason, when available" } }, "required": [ "code", "reason" ], "additionalProperties": false }, { "type": "null" } ], "description": "Failure details when this transfer failed." }, "return": { "anyOf": [ { "type": "object", "properties": { "code": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Return code, when available" }, "reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Return reason, when available" }, "returnedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "When this transfer returned" } }, "required": [ "code", "reason", "returnedAt" ], "additionalProperties": false }, { "type": "null" } ], "description": "Return details when this transfer was returned." }, "submittedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "When this transfer was submitted" }, "settledAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "When this transfer settled" }, "createdAt": { "type": "string", "description": "When this transfer was created" }, "updatedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "When this transfer was last updated" } }, "required": [ "type", "amount", "currency", "status", "description", "externalAccountDisplayMask", "expectedAvailableAt", "failure", "return", "submittedAt", "settledAt", "createdAt", "updatedAt" ], "additionalProperties": false, "title": "TransferAttributes", "description": "Resource attributes" }, "relationships": { "type": "object", "properties": { "party": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "description": "Resource 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 transfer" }, "wallet": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "description": "Resource type", "type": "string", "enum": [ "wallet" ] }, "id": { "type": "string", "pattern": "^wal_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier" } }, "required": [ "data" ], "additionalProperties": false, "title": "ToOneRelationship", "description": "Wallet for this transfer" }, "destWallet": { "type": "object", "properties": { "data": { "anyOf": [ { "type": "object", "properties": { "type": { "description": "Resource type", "type": "string", "enum": [ "wallet" ] }, "id": { "type": "string", "pattern": "^wal_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier" }, { "type": "null" } ] } }, "required": [ "data" ], "additionalProperties": false, "title": "NullableToOneRelationship", "description": "Destination wallet for internal transfers." }, "externalAccount": { "type": "object", "properties": { "data": { "anyOf": [ { "type": "object", "properties": { "type": { "description": "Resource type", "type": "string", "enum": [ "externalAccount" ] }, "id": { "type": "string", "pattern": "^eac_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier" }, { "type": "null" } ] } }, "required": [ "data" ], "additionalProperties": false, "title": "NullableToOneRelationship", "description": "External account used for this transfer, when available." }, "transaction": { "type": "object", "properties": { "data": { "anyOf": [ { "type": "object", "properties": { "type": { "description": "Resource type", "type": "string", "enum": [ "transaction" ] }, "id": { "type": "string" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier" }, { "type": "null" } ] } }, "required": [ "data" ], "additionalProperties": false, "title": "NullableToOneRelationship", "description": "Primary transaction row for this transfer, when available." } }, "required": [ "party", "wallet", "externalAccount", "transaction" ], "additionalProperties": false, "title": "TransferRelationships", "description": "Resource relationships" } }, "required": [ "type", "id", "attributes", "relationships" ], "additionalProperties": false, "title": "TransferResource" } }, "required": [ "data" ], "additionalProperties": false }, "examples": { "default": { "summary": "Default", "value": { "data": { "type": "transfer", "id": "trf_650e8400e29b41d4a716446655440000", "attributes": { "type": "withdrawal", "amount": 12500, "currency": "USD", "status": "PROCESSING", "description": "Payout transfer", "externalAccountDisplayMask": "6789", "expectedAvailableAt": "2026-01-06T15:30:00Z", "failure": null, "return": null, "submittedAt": "2026-01-04T15:30:00Z", "settledAt": null, "createdAt": "2026-01-04T15:30:00Z", "updatedAt": "2026-01-04T15:30:00Z" }, "relationships": { "party": { "data": { "type": "party", "id": "pty_7c9e6679e29b41d4a716446655440001" } }, "wallet": { "data": { "type": "wallet", "id": "wal_550e8400e29b41d4a716446655440000" } }, "externalAccount": { "data": { "type": "externalAccount", "id": "eac_550e8400e29b41d4a716446655440000" } }, "transaction": { "data": { "type": "transaction", "id": "txn_650e8400e29b41d4a716446655440000" } } } } } } } } }, "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "A request value is invalid.", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "email: Invalid email address", "status": "422", "source": { "pointer": "/data/attributes/email" }, "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "428": { "description": "Precondition Required", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "mfa_required", "detail": "MFA verification required", "status": "428", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "429": { "description": "Too Many Requests", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "rate_limited", "detail": "Too many requests. Please try again later.", "status": "429", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying", "schema": { "type": "integer" } }, "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" } } } }, "500": { "description": "Internal Server 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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "server_error", "detail": "Something went wrong.", "status": "500", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "501": { "description": "Not Implemented", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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_implemented", "detail": "This operation is not available.", "status": "501", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "502": { "description": "Bad Gateway", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "bad_gateway", "detail": "We couldn't complete that request because one of Natural's services returned an unexpected response. Please try again.", "status": "502", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "503": { "description": "Service Unavailable", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "service_unavailable", "detail": "The service is temporarily unavailable.", "status": "503", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } } }, "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Unique key for idempotent request handling. If a request with the same key was already processed, the original response is returned." }, { "name": "X-Agent-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "description": "Agent ID (agt_xxx) identifying which agent is making the request." }, { "name": "X-Instance-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 1024 }, { "type": "null" } ] }, "description": "Required when X-Agent-ID is present. Session or conversation ID for agent observability." } ] } }, "/transfers": { "get": { "operationId": "transfers.list", "summary": "List transfers", "description": "List transfers for the authenticated party.", "tags": [ "Transfers" ], "parameters": [ { "name": "partyId", "in": "query", "schema": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$", "description": "Party ID for delegated transfer lookup" }, "allowEmptyValue": true, "allowReserved": true }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50, "description": "Results per page" }, "allowEmptyValue": true, "allowReserved": true }, { "name": "cursor", "in": "query", "schema": { "type": "string", "description": "Pagination cursor from previous response" }, "allowEmptyValue": true, "allowReserved": true }, { "name": "X-Agent-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "description": "Agent ID (agt_xxx) identifying which agent is making the request." }, { "name": "X-Instance-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 1024 }, { "type": "null" } ] }, "description": "Required when X-Agent-ID is present. Session or conversation ID for agent observability." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "transfer" ] }, "id": { "type": "string", "pattern": "^trf_[0-9a-f]{32}$" }, "attributes": { "type": "object", "properties": { "type": { "enum": [ "deposit", "withdrawal", "internal" ], "type": "string", "description": "Transfer type" }, "amount": { "type": "integer", "description": "Amount in cents" }, "currency": { "type": "string", "description": "Currency code" }, "status": { "enum": [ "CREATED", "APPROVAL_DENIED", "PROCESSING", "IN_REVIEW", "COMPLETED", "FAILED", "RETURNED", "CANCELED" ], "type": "string", "description": "Transfer status" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Transfer description" }, "externalAccountDisplayMask": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Masked external account display" }, "expectedAvailableAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Expected availability time, when known" }, "failure": { "anyOf": [ { "type": "object", "properties": { "code": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Failure code, when available" }, "reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Failure reason, when available" } }, "required": [ "code", "reason" ], "additionalProperties": false }, { "type": "null" } ], "description": "Failure details when this transfer failed." }, "return": { "anyOf": [ { "type": "object", "properties": { "code": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Return code, when available" }, "reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Return reason, when available" }, "returnedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "When this transfer returned" } }, "required": [ "code", "reason", "returnedAt" ], "additionalProperties": false }, { "type": "null" } ], "description": "Return details when this transfer was returned." }, "submittedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "When this transfer was submitted" }, "settledAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "When this transfer settled" }, "createdAt": { "type": "string", "description": "When this transfer was created" }, "updatedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "When this transfer was last updated" } }, "required": [ "type", "amount", "currency", "status", "description", "externalAccountDisplayMask", "expectedAvailableAt", "failure", "return", "submittedAt", "settledAt", "createdAt", "updatedAt" ], "additionalProperties": false, "title": "TransferAttributes", "description": "Resource attributes" }, "relationships": { "type": "object", "properties": { "party": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "description": "Resource 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 transfer" }, "wallet": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "description": "Resource type", "type": "string", "enum": [ "wallet" ] }, "id": { "type": "string", "pattern": "^wal_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier" } }, "required": [ "data" ], "additionalProperties": false, "title": "ToOneRelationship", "description": "Wallet for this transfer" }, "destWallet": { "type": "object", "properties": { "data": { "anyOf": [ { "type": "object", "properties": { "type": { "description": "Resource type", "type": "string", "enum": [ "wallet" ] }, "id": { "type": "string", "pattern": "^wal_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier" }, { "type": "null" } ] } }, "required": [ "data" ], "additionalProperties": false, "title": "NullableToOneRelationship", "description": "Destination wallet for internal transfers." }, "externalAccount": { "type": "object", "properties": { "data": { "anyOf": [ { "type": "object", "properties": { "type": { "description": "Resource type", "type": "string", "enum": [ "externalAccount" ] }, "id": { "type": "string", "pattern": "^eac_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier" }, { "type": "null" } ] } }, "required": [ "data" ], "additionalProperties": false, "title": "NullableToOneRelationship", "description": "External account used for this transfer, when available." }, "transaction": { "type": "object", "properties": { "data": { "anyOf": [ { "type": "object", "properties": { "type": { "description": "Resource type", "type": "string", "enum": [ "transaction" ] }, "id": { "type": "string" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier" }, { "type": "null" } ] } }, "required": [ "data" ], "additionalProperties": false, "title": "NullableToOneRelationship", "description": "Primary transaction row for this transfer, when available." } }, "required": [ "party", "wallet", "externalAccount", "transaction" ], "additionalProperties": false, "title": "TransferRelationships", "description": "Resource relationships" } }, "required": [ "type", "id", "attributes", "relationships" ], "additionalProperties": false, "title": "TransferResource" } }, "meta": { "type": "object", "properties": { "pagination": { "type": "object", "properties": { "hasMore": { "type": "boolean" }, "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "hasMore", "nextCursor" ], "additionalProperties": false, "title": "PaginationMeta" } }, "required": [ "pagination" ], "additionalProperties": false } }, "required": [ "data", "meta" ], "additionalProperties": false, "title": "TransferListResponse" }, "examples": { "default": { "summary": "Default", "value": { "data": [ { "type": "transfer", "id": "trf_550e8400e29b41d4a716446655440000", "attributes": { "type": "deposit", "amount": 50000, "currency": "USD", "status": "PROCESSING", "description": "Wallet top-up", "externalAccountDisplayMask": "6789", "expectedAvailableAt": null, "failure": null, "return": null, "submittedAt": "2026-01-04T15:30:00Z", "settledAt": null, "createdAt": "2026-01-04T15:30:00Z", "updatedAt": "2026-01-04T15:30:00Z" }, "relationships": { "party": { "data": { "type": "party", "id": "pty_7c9e6679e29b41d4a716446655440001" } }, "wallet": { "data": { "type": "wallet", "id": "wal_550e8400e29b41d4a716446655440000" } }, "externalAccount": { "data": { "type": "externalAccount", "id": "eac_550e8400e29b41d4a716446655440000" } }, "transaction": { "data": { "type": "transaction", "id": "txn_550e8400e29b41d4a716446655440000" } } } } ], "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "A request value is invalid.", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "email: Invalid email address", "status": "422", "source": { "pointer": "/data/attributes/email" }, "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "428": { "description": "Precondition Required", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "mfa_required", "detail": "MFA verification required", "status": "428", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "429": { "description": "Too Many Requests", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "rate_limited", "detail": "Too many requests. Please try again later.", "status": "429", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying", "schema": { "type": "integer" } }, "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" } } } }, "500": { "description": "Internal Server 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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "server_error", "detail": "Something went wrong.", "status": "500", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "501": { "description": "Not Implemented", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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_implemented", "detail": "This operation is not available.", "status": "501", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "502": { "description": "Bad Gateway", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "bad_gateway", "detail": "We couldn't complete that request because one of Natural's services returned an unexpected response. Please try again.", "status": "502", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "503": { "description": "Service Unavailable", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "service_unavailable", "detail": "The service is temporarily unavailable.", "status": "503", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } } }, "security": [ { "HTTPBearer": [] } ] } }, "/transfers/{transferId}": { "get": { "operationId": "transfers.get", "summary": "Get transfer", "description": "Get a transfer by ID.", "tags": [ "Transfers" ], "parameters": [ { "name": "transferId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^trf_[0-9a-f]{32}$" } }, { "name": "partyId", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$", "description": "Party ID for delegated transfer lookup" }, "allowEmptyValue": true, "allowReserved": true }, { "name": "X-Agent-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "description": "Agent ID (agt_xxx) identifying which agent is making the request." }, { "name": "X-Instance-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 1024 }, { "type": "null" } ] }, "description": "Required when X-Agent-ID is present. Session or conversation ID for agent observability." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "transfer" ] }, "id": { "type": "string", "pattern": "^trf_[0-9a-f]{32}$" }, "attributes": { "type": "object", "properties": { "type": { "enum": [ "deposit", "withdrawal", "internal" ], "type": "string", "description": "Transfer type" }, "amount": { "type": "integer", "description": "Amount in cents" }, "currency": { "type": "string", "description": "Currency code" }, "status": { "enum": [ "CREATED", "APPROVAL_DENIED", "PROCESSING", "IN_REVIEW", "COMPLETED", "FAILED", "RETURNED", "CANCELED" ], "type": "string", "description": "Transfer status" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Transfer description" }, "externalAccountDisplayMask": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Masked external account display" }, "expectedAvailableAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Expected availability time, when known" }, "failure": { "anyOf": [ { "type": "object", "properties": { "code": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Failure code, when available" }, "reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Failure reason, when available" } }, "required": [ "code", "reason" ], "additionalProperties": false }, { "type": "null" } ], "description": "Failure details when this transfer failed." }, "return": { "anyOf": [ { "type": "object", "properties": { "code": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Return code, when available" }, "reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Return reason, when available" }, "returnedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "When this transfer returned" } }, "required": [ "code", "reason", "returnedAt" ], "additionalProperties": false }, { "type": "null" } ], "description": "Return details when this transfer was returned." }, "submittedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "When this transfer was submitted" }, "settledAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "When this transfer settled" }, "createdAt": { "type": "string", "description": "When this transfer was created" }, "updatedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "When this transfer was last updated" } }, "required": [ "type", "amount", "currency", "status", "description", "externalAccountDisplayMask", "expectedAvailableAt", "failure", "return", "submittedAt", "settledAt", "createdAt", "updatedAt" ], "additionalProperties": false, "title": "TransferAttributes", "description": "Resource attributes" }, "relationships": { "type": "object", "properties": { "party": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "description": "Resource 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 transfer" }, "wallet": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "description": "Resource type", "type": "string", "enum": [ "wallet" ] }, "id": { "type": "string", "pattern": "^wal_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier" } }, "required": [ "data" ], "additionalProperties": false, "title": "ToOneRelationship", "description": "Wallet for this transfer" }, "destWallet": { "type": "object", "properties": { "data": { "anyOf": [ { "type": "object", "properties": { "type": { "description": "Resource type", "type": "string", "enum": [ "wallet" ] }, "id": { "type": "string", "pattern": "^wal_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier" }, { "type": "null" } ] } }, "required": [ "data" ], "additionalProperties": false, "title": "NullableToOneRelationship", "description": "Destination wallet for internal transfers." }, "externalAccount": { "type": "object", "properties": { "data": { "anyOf": [ { "type": "object", "properties": { "type": { "description": "Resource type", "type": "string", "enum": [ "externalAccount" ] }, "id": { "type": "string", "pattern": "^eac_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier" }, { "type": "null" } ] } }, "required": [ "data" ], "additionalProperties": false, "title": "NullableToOneRelationship", "description": "External account used for this transfer, when available." }, "transaction": { "type": "object", "properties": { "data": { "anyOf": [ { "type": "object", "properties": { "type": { "description": "Resource type", "type": "string", "enum": [ "transaction" ] }, "id": { "type": "string" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier" }, { "type": "null" } ] } }, "required": [ "data" ], "additionalProperties": false, "title": "NullableToOneRelationship", "description": "Primary transaction row for this transfer, when available." } }, "required": [ "party", "wallet", "externalAccount", "transaction" ], "additionalProperties": false, "title": "TransferRelationships", "description": "Resource relationships" } }, "required": [ "type", "id", "attributes", "relationships" ], "additionalProperties": false, "title": "TransferResource" } }, "required": [ "data" ], "additionalProperties": false, "title": "TransferResponse" }, "examples": { "default": { "summary": "Default", "value": { "data": { "type": "transfer", "id": "trf_550e8400e29b41d4a716446655440000", "attributes": { "type": "deposit", "amount": 50000, "currency": "USD", "status": "PROCESSING", "description": "Wallet top-up", "externalAccountDisplayMask": "6789", "expectedAvailableAt": null, "failure": null, "return": null, "submittedAt": "2026-01-04T15:30:00Z", "settledAt": null, "createdAt": "2026-01-04T15:30:00Z", "updatedAt": "2026-01-04T15:30:00Z" }, "relationships": { "party": { "data": { "type": "party", "id": "pty_7c9e6679e29b41d4a716446655440001" } }, "wallet": { "data": { "type": "wallet", "id": "wal_550e8400e29b41d4a716446655440000" } }, "externalAccount": { "data": { "type": "externalAccount", "id": "eac_550e8400e29b41d4a716446655440000" } }, "transaction": { "data": { "type": "transaction", "id": "txn_550e8400e29b41d4a716446655440000" } } } } } } } } }, "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "A request value is invalid.", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "email: Invalid email address", "status": "422", "source": { "pointer": "/data/attributes/email" }, "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "428": { "description": "Precondition Required", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "mfa_required", "detail": "MFA verification required", "status": "428", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "429": { "description": "Too Many Requests", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "rate_limited", "detail": "Too many requests. Please try again later.", "status": "429", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying", "schema": { "type": "integer" } }, "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" } } } }, "500": { "description": "Internal Server 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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "server_error", "detail": "Something went wrong.", "status": "500", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "501": { "description": "Not Implemented", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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_implemented", "detail": "This operation is not available.", "status": "501", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "502": { "description": "Bad Gateway", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "bad_gateway", "detail": "We couldn't complete that request because one of Natural's services returned an unexpected response. Please try again.", "status": "502", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "503": { "description": "Service Unavailable", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "service_unavailable", "detail": "The service is temporarily unavailable.", "status": "503", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } } }, "security": [ { "HTTPBearer": [] } ] } }, "/payment-requests": { "post": { "operationId": "paymentRequests.create", "summary": "Create payment request", "description": "Create a payment request. Natural notifies the payer directly: email and phone payers receive the pay link, on-platform parties receive a dashboard deep-link, and agent and handle payers receive only the in-app webhook.", "tags": [ "PaymentRequests" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "attributes": { "type": "object", "properties": { "customerPartyId": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$", "description": "Requester party ID (pty_*). Omit to request into your own wallet; provide for delegated payment requests on behalf of a customer." }, "walletId": { "type": "string", "pattern": "^wal_[0-9a-f]{32}$", "description": "Wallet that should receive the funds. Omit to use the requester party's default wallet." }, "amount": { "type": "integer", "exclusiveMinimum": 0, "description": "Amount in minor units (cents for USD)" }, "currency": { "enum": [ "USD" ], "type": "string", "default": "USD", "description": "Currency code (currently only USD)" }, "description": { "type": "string", "maxLength": 500, "description": "Free-form description shown to the payer. Maximum 500 characters." }, "payerName": { "type": "string", "description": "Display name of the payer" }, "payer": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "email" ] }, "value": { "type": "string", "format": "email", "description": "Email address" } }, "required": [ "type", "value" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "phone" ] }, "value": { "type": "string", "description": "Phone number in E.164 format" } }, "required": [ "type", "value" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "party_id" ] }, "value": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$", "description": "Natural party ID (pty_*)" } }, "required": [ "type", "value" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "agent_id" ] }, "value": { "type": "string", "pattern": "^agt_[0-9a-f]{32}$", "description": "Natural agent ID (agt_*)" } }, "required": [ "type", "value" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "handle" ] }, "value": { "type": "string", "pattern": "^@?[A-Za-z0-9](?:[A-Za-z0-9-]{0,28}[A-Za-z0-9])?(?:\\/[A-Za-z0-9](?:[A-Za-z0-9-]{0,28}[A-Za-z0-9])?)?$", "description": "Natural handle (@namespace or @namespace/slug)" } }, "required": [ "type", "value" ], "additionalProperties": false } ], "title": "PaymentRequestPayer", "description": "Who pays: exactly one typed email, phone, party ID, agent ID, or handle value." } }, "required": [ "amount", "payer" ], "additionalProperties": false, "description": "Payment request creation attributes" } }, "required": [ "attributes" ], "additionalProperties": false, "description": "Resource object" } }, "required": [ "data" ], "additionalProperties": false, "title": "PaymentRequestCreateRequest" }, "examples": { "default": { "summary": "Default", "value": { "data": { "attributes": { "amount": 2500, "currency": "USD", "description": "Invoice 7", "payerName": "Ada Lovelace", "payer": { "type": "email", "value": "ada@example.com" } } } } } } } } }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "description": "Resource type", "type": "string", "enum": [ "paymentRequest" ] }, "id": { "type": "string", "pattern": "^prq_[0-9a-f]{32}$", "description": "Resource ID (prq_*)" }, "attributes": { "type": "object", "properties": { "amount": { "type": "integer", "description": "Amount in cents" }, "currency": { "type": "string", "description": "Currency code" }, "status": { "enum": [ "OPEN", "PROCESSING", "COMPLETED", "FAILED", "RETURNED", "CANCELED", "DECLINED", "EXPIRED" ], "type": "string", "description": "Current status of the payment request" }, "description": { "anyOf": [ { "type": "string", "maxLength": 500 }, { "type": "null" } ], "description": "Free-form description provided at creation. Maximum 500 characters." }, "requesterName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Display name of the party requesting payment" }, "requesterEmail": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Email of the party requesting payment" }, "payerName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Display name of the payer" }, "payerEmail": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Email of the payer if addressed by email" }, "payerPhone": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Phone of the payer in E.164 format if addressed by phone" }, "payerPartyId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Natural party ID (pty_*) resolved for the payer, including agent owner parties" }, "payerIdentifierType": { "enum": [ "email", "phone", "party_id", "agent_id", "handle" ], "type": "string", "description": "Which identifier type was used to address the payer" }, "payerIdentifier": { "type": "string", "description": "The identifier value used to address the payer" }, "paymentLinkUrl": { "type": "string", "format": "uri", "description": "URL the payer visits to complete payment" }, "transactionId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "ID of the transaction created by the most recent payment attempt, or null if no attempt yet" }, "createdAt": { "type": "string", "description": "ISO 8601 timestamp when the payment request was created" }, "updatedAt": { "type": "string", "description": "ISO 8601 timestamp when the payment request was last updated" } }, "required": [ "amount", "currency", "status", "description", "requesterName", "requesterEmail", "payerName", "payerEmail", "payerPhone", "payerPartyId", "payerIdentifierType", "payerIdentifier", "paymentLinkUrl", "transactionId", "createdAt", "updatedAt" ], "additionalProperties": false, "title": "PaymentRequestAttributes", "description": "Resource attributes" }, "relationships": { "type": "object", "properties": { "requesterParty": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "description": "Resource 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 requesting the payment" }, "payerParty": { "type": "object", "properties": { "data": { "anyOf": [ { "type": "object", "properties": { "type": { "description": "Resource 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" }, { "type": "null" } ] } }, "required": [ "data" ], "additionalProperties": false, "title": "NullableToOneRelationship", "description": "Resolved payer party, if the payer is known to Natural" } }, "required": [ "requesterParty", "payerParty" ], "additionalProperties": false, "title": "PaymentRequestCreateRelationships", "description": "Resource relationships" } }, "required": [ "type", "id", "attributes", "relationships" ], "additionalProperties": false, "title": "PaymentRequestCreateResource" } }, "required": [ "data" ], "additionalProperties": false, "title": "PaymentRequestCreateResponse" }, "examples": { "default": { "summary": "Default", "value": { "data": { "type": "paymentRequest", "id": "prq_550e8400e29b41d4a716446655440000", "attributes": { "amount": 2500, "currency": "USD", "status": "OPEN", "description": "Invoice 7", "requesterName": null, "requesterEmail": null, "payerName": "Ada Lovelace", "payerEmail": "ada@example.com", "payerPhone": null, "payerPartyId": null, "payerIdentifierType": "email", "payerIdentifier": "ada@example.com", "paymentLinkUrl": "https://natural.co/paymentLink/token_123", "transactionId": null, "createdAt": "2026-04-15T00:00:00.000Z", "updatedAt": "2026-04-15T00:00:00.000Z" }, "relationships": { "requesterParty": { "data": { "type": "party", "id": "pty_019cd1798d617f65a79cb965dda9eac3" } }, "payerParty": { "data": 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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "A request value is invalid.", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "email: Invalid email address", "status": "422", "source": { "pointer": "/data/attributes/email" }, "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "428": { "description": "Precondition Required", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "mfa_required", "detail": "MFA verification required", "status": "428", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "429": { "description": "Too Many Requests", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "rate_limited", "detail": "Too many requests. Please try again later.", "status": "429", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying", "schema": { "type": "integer" } }, "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" } } } }, "500": { "description": "Internal Server 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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "server_error", "detail": "Something went wrong.", "status": "500", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "501": { "description": "Not Implemented", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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_implemented", "detail": "This operation is not available.", "status": "501", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "502": { "description": "Bad Gateway", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "bad_gateway", "detail": "We couldn't complete that request because one of Natural's services returned an unexpected response. Please try again.", "status": "502", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "503": { "description": "Service Unavailable", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "service_unavailable", "detail": "The service is temporarily unavailable.", "status": "503", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } } }, "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Unique key for idempotent request handling. If a request with the same key was already processed, the original response is returned." }, { "name": "X-Agent-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "description": "Agent ID (agt_xxx) identifying which agent is making the request." }, { "name": "X-Instance-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 1024 }, { "type": "null" } ] }, "description": "Required when X-Agent-ID is present. Session or conversation ID for agent observability." } ] }, "get": { "operationId": "paymentRequests.list", "summary": "List payment requests", "description": "List payment requests visible to the authenticated requester party.", "tags": [ "PaymentRequests" ], "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50, "description": "Results per page (1-100)" }, "allowEmptyValue": true, "allowReserved": true }, { "name": "cursor", "in": "query", "schema": { "type": "string", "description": "Pagination cursor returned by the previous response" }, "allowEmptyValue": true, "allowReserved": true }, { "name": "partyId", "in": "query", "schema": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$", "description": "Effective party ID (pty_*) for delegated payment request access." }, "allowEmptyValue": true, "allowReserved": true }, { "name": "X-Agent-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "description": "Agent ID (agt_xxx) identifying which agent is making the request." }, { "name": "X-Instance-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 1024 }, { "type": "null" } ] }, "description": "Required when X-Agent-ID is present. Session or conversation ID for agent observability." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "type": { "description": "Resource type", "type": "string", "enum": [ "paymentRequest" ] }, "id": { "type": "string", "pattern": "^prq_[0-9a-f]{32}$", "description": "Resource ID (prq_*)" }, "attributes": { "type": "object", "properties": { "amount": { "type": "integer", "description": "Amount in cents" }, "currency": { "type": "string", "description": "Currency code" }, "status": { "enum": [ "OPEN", "PROCESSING", "COMPLETED", "FAILED", "RETURNED", "CANCELED", "DECLINED", "EXPIRED" ], "type": "string", "description": "Current status of the payment request" }, "description": { "anyOf": [ { "type": "string", "maxLength": 500 }, { "type": "null" } ], "description": "Free-form description provided at creation. Maximum 500 characters." }, "requesterName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Display name of the party requesting payment" }, "requesterEmail": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Email of the party requesting payment" }, "payerName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Display name of the payer" }, "payerEmail": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Email of the payer if addressed by email" }, "payerPhone": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Phone of the payer in E.164 format if addressed by phone" }, "payerPartyId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Natural party ID (pty_*) resolved for the payer, including agent owner parties" }, "payerIdentifierType": { "enum": [ "email", "phone", "party_id", "agent_id", "handle" ], "type": "string", "description": "Which identifier type was used to address the payer" }, "payerIdentifier": { "type": "string", "description": "The identifier value used to address the payer" }, "paymentLinkUrl": { "type": "string", "format": "uri", "description": "URL the payer visits to complete payment" }, "transactionId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "ID of the transaction created by the most recent payment attempt, or null if no attempt yet" }, "createdAt": { "type": "string", "description": "ISO 8601 timestamp when the payment request was created" }, "updatedAt": { "type": "string", "description": "ISO 8601 timestamp when the payment request was last updated" } }, "required": [ "amount", "currency", "status", "description", "requesterName", "requesterEmail", "payerName", "payerEmail", "payerPhone", "payerPartyId", "payerIdentifierType", "payerIdentifier", "paymentLinkUrl", "transactionId", "createdAt", "updatedAt" ], "additionalProperties": false, "title": "PaymentRequestAttributes", "description": "Resource attributes" }, "relationships": { "type": "object", "properties": { "requesterParty": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "description": "Resource 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 requesting the payment" }, "wallet": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "description": "Resource type", "type": "string", "enum": [ "wallet" ] }, "id": { "type": "string", "pattern": "^wal_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier" } }, "required": [ "data" ], "additionalProperties": false, "title": "ToOneRelationship", "description": "Wallet that receives the funds" }, "payerParty": { "type": "object", "properties": { "data": { "anyOf": [ { "type": "object", "properties": { "type": { "description": "Resource 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" }, { "type": "null" } ] } }, "required": [ "data" ], "additionalProperties": false, "title": "NullableToOneRelationship", "description": "Resolved payer party, if the payer is known to Natural" }, "payment": { "type": "object", "properties": { "data": { "anyOf": [ { "type": "object", "properties": { "type": { "description": "Resource type", "type": "string", "enum": [ "payment" ] }, "id": { "type": "string", "pattern": "^pay_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier" }, { "type": "null" } ] } }, "required": [ "data" ], "additionalProperties": false, "title": "NullableToOneRelationship", "description": "Payment submitted for this payment request, if one exists." } }, "required": [ "requesterParty", "wallet", "payerParty", "payment" ], "additionalProperties": false, "title": "PaymentRequestRelationships", "description": "Resource relationships" } }, "required": [ "type", "id", "attributes", "relationships" ], "additionalProperties": false, "title": "PaymentRequestResource" } }, "meta": { "type": "object", "properties": { "pagination": { "type": "object", "properties": { "hasMore": { "type": "boolean" }, "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "hasMore", "nextCursor" ], "additionalProperties": false, "title": "PaginationMeta" } }, "required": [ "pagination" ], "additionalProperties": false } }, "required": [ "data", "meta" ], "additionalProperties": false, "title": "PaymentRequestListResponse" }, "examples": { "default": { "summary": "Default", "value": { "data": [ { "type": "paymentRequest", "id": "prq_550e8400e29b41d4a716446655440000", "attributes": { "amount": 2500, "currency": "USD", "status": "OPEN", "description": "Invoice 7", "requesterName": "Acme Payments", "requesterEmail": "billing@acmepayments.com", "payerName": "Ada Lovelace", "payerEmail": "ada@example.com", "payerPhone": null, "payerPartyId": null, "payerIdentifierType": "email", "payerIdentifier": "ada@example.com", "paymentLinkUrl": "https://natural.co/paymentLink/token_123", "transactionId": null, "createdAt": "2026-04-15T00:00:00.000Z", "updatedAt": "2026-04-15T00:00:00.000Z" }, "relationships": { "requesterParty": { "data": { "type": "party", "id": "pty_019cd1798d617f65a79cb965dda9eac3" } }, "wallet": { "data": { "type": "wallet", "id": "wal_550e8400e29b41d4a716446655440000" } }, "payerParty": { "data": null }, "payment": { "data": 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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "A request value is invalid.", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "email: Invalid email address", "status": "422", "source": { "pointer": "/data/attributes/email" }, "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "428": { "description": "Precondition Required", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "mfa_required", "detail": "MFA verification required", "status": "428", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "429": { "description": "Too Many Requests", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "rate_limited", "detail": "Too many requests. Please try again later.", "status": "429", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying", "schema": { "type": "integer" } }, "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" } } } }, "500": { "description": "Internal Server 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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "server_error", "detail": "Something went wrong.", "status": "500", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "501": { "description": "Not Implemented", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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_implemented", "detail": "This operation is not available.", "status": "501", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "502": { "description": "Bad Gateway", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "bad_gateway", "detail": "We couldn't complete that request because one of Natural's services returned an unexpected response. Please try again.", "status": "502", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "503": { "description": "Service Unavailable", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "service_unavailable", "detail": "The service is temporarily unavailable.", "status": "503", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } } }, "security": [ { "HTTPBearer": [] } ] } }, "/payment-requests/incoming": { "get": { "operationId": "paymentRequests.listIncoming", "summary": "List incoming payment requests", "description": "List open payment requests where the authenticated party is expected to pay.", "tags": [ "PaymentRequests" ], "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50, "description": "Results per page (1-100)" }, "allowEmptyValue": true, "allowReserved": true }, { "name": "cursor", "in": "query", "schema": { "type": "string", "description": "Pagination cursor returned by the previous response" }, "allowEmptyValue": true, "allowReserved": true }, { "name": "partyId", "in": "query", "schema": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$", "description": "Effective party ID (pty_*) for delegated payment request access." }, "allowEmptyValue": true, "allowReserved": true }, { "name": "X-Agent-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "description": "Agent ID (agt_xxx) identifying which agent is making the request." }, { "name": "X-Instance-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 1024 }, { "type": "null" } ] }, "description": "Required when X-Agent-ID is present. Session or conversation ID for agent observability." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "type": { "description": "Resource type", "type": "string", "enum": [ "paymentRequest" ] }, "id": { "type": "string", "pattern": "^prq_[0-9a-f]{32}$", "description": "Resource ID (prq_*)" }, "attributes": { "type": "object", "properties": { "amount": { "type": "integer", "description": "Amount in cents" }, "currency": { "type": "string", "description": "Currency code" }, "status": { "enum": [ "OPEN", "PROCESSING", "COMPLETED", "FAILED", "RETURNED", "CANCELED", "DECLINED", "EXPIRED" ], "type": "string", "description": "Current status of the payment request" }, "description": { "anyOf": [ { "type": "string", "maxLength": 500 }, { "type": "null" } ], "description": "Free-form description provided at creation. Maximum 500 characters." }, "requesterName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Display name of the party requesting payment" }, "requesterEmail": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Email of the party requesting payment" }, "payerName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Display name of the payer" }, "payerEmail": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Email of the payer if addressed by email" }, "payerPhone": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Phone of the payer in E.164 format if addressed by phone" }, "payerPartyId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Natural party ID (pty_*) resolved for the payer, including agent owner parties" }, "payerIdentifierType": { "enum": [ "email", "phone", "party_id", "agent_id", "handle" ], "type": "string", "description": "Which identifier type was used to address the payer" }, "payerIdentifier": { "type": "string", "description": "The identifier value used to address the payer" }, "paymentLinkUrl": { "type": "string", "format": "uri", "description": "URL the payer visits to complete payment" }, "transactionId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "ID of the transaction created by the most recent payment attempt, or null if no attempt yet" }, "createdAt": { "type": "string", "description": "ISO 8601 timestamp when the payment request was created" }, "updatedAt": { "type": "string", "description": "ISO 8601 timestamp when the payment request was last updated" } }, "required": [ "amount", "currency", "status", "description", "requesterName", "requesterEmail", "payerName", "payerEmail", "payerPhone", "payerPartyId", "payerIdentifierType", "payerIdentifier", "paymentLinkUrl", "transactionId", "createdAt", "updatedAt" ], "additionalProperties": false, "title": "PaymentRequestAttributes", "description": "Resource attributes" }, "relationships": { "type": "object", "properties": { "requesterParty": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "description": "Resource 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 requesting the payment" }, "wallet": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "description": "Resource type", "type": "string", "enum": [ "wallet" ] }, "id": { "type": "string", "pattern": "^wal_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier" } }, "required": [ "data" ], "additionalProperties": false, "title": "ToOneRelationship", "description": "Wallet that receives the funds" }, "payerParty": { "type": "object", "properties": { "data": { "anyOf": [ { "type": "object", "properties": { "type": { "description": "Resource 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" }, { "type": "null" } ] } }, "required": [ "data" ], "additionalProperties": false, "title": "NullableToOneRelationship", "description": "Resolved payer party, if the payer is known to Natural" }, "payment": { "type": "object", "properties": { "data": { "anyOf": [ { "type": "object", "properties": { "type": { "description": "Resource type", "type": "string", "enum": [ "payment" ] }, "id": { "type": "string", "pattern": "^pay_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier" }, { "type": "null" } ] } }, "required": [ "data" ], "additionalProperties": false, "title": "NullableToOneRelationship", "description": "Payment submitted for this payment request, if one exists." } }, "required": [ "requesterParty", "wallet", "payerParty", "payment" ], "additionalProperties": false, "title": "PaymentRequestRelationships", "description": "Resource relationships" } }, "required": [ "type", "id", "attributes", "relationships" ], "additionalProperties": false, "title": "PaymentRequestResource" } }, "meta": { "type": "object", "properties": { "pagination": { "type": "object", "properties": { "hasMore": { "type": "boolean" }, "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "hasMore", "nextCursor" ], "additionalProperties": false, "title": "PaginationMeta" } }, "required": [ "pagination" ], "additionalProperties": false } }, "required": [ "data", "meta" ], "additionalProperties": false, "title": "PaymentRequestListResponse" }, "examples": { "default": { "summary": "Default", "value": { "data": [ { "type": "paymentRequest", "id": "prq_550e8400e29b41d4a716446655440000", "attributes": { "amount": 500, "currency": "USD", "status": "OPEN", "requesterName": "Natural Coffee", "requesterEmail": "billing@natural.test", "description": "Invoice 7", "payerName": "Ada Lovelace", "payerEmail": "ada@example.com", "payerPhone": "+14155550100", "payerPartyId": "pty_550e8400e29b41d4a716446655440000", "payerIdentifierType": "party_id", "payerIdentifier": "pty_550e8400e29b41d4a716446655440000", "paymentLinkUrl": "https://app.natural.test/pay/token_123", "transactionId": null, "createdAt": "2026-04-15T00:00:00.000Z", "updatedAt": "2026-04-15T00:00:00.000Z" }, "relationships": { "requesterParty": { "data": { "type": "party", "id": "pty_019cd1798d617f65a79cb965dda9eac3" } }, "wallet": { "data": { "type": "wallet", "id": "wal_550e8400e29b41d4a716446655440000" } }, "payerParty": { "data": { "type": "party", "id": "pty_550e8400e29b41d4a716446655440000" } }, "payment": { "data": 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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "A request value is invalid.", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "email: Invalid email address", "status": "422", "source": { "pointer": "/data/attributes/email" }, "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "428": { "description": "Precondition Required", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "mfa_required", "detail": "MFA verification required", "status": "428", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "429": { "description": "Too Many Requests", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "rate_limited", "detail": "Too many requests. Please try again later.", "status": "429", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying", "schema": { "type": "integer" } }, "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" } } } }, "500": { "description": "Internal Server 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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "server_error", "detail": "Something went wrong.", "status": "500", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "501": { "description": "Not Implemented", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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_implemented", "detail": "This operation is not available.", "status": "501", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "502": { "description": "Bad Gateway", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "bad_gateway", "detail": "We couldn't complete that request because one of Natural's services returned an unexpected response. Please try again.", "status": "502", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "503": { "description": "Service Unavailable", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "service_unavailable", "detail": "The service is temporarily unavailable.", "status": "503", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } } }, "security": [ { "HTTPBearer": [] } ] } }, "/payment-requests/{paymentRequestId}": { "get": { "operationId": "paymentRequests.get", "summary": "Get payment request", "description": "Get a single payment request visible to the authenticated participant party.", "tags": [ "PaymentRequests" ], "parameters": [ { "name": "paymentRequestId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^prq_[0-9a-f]{32}$" } }, { "name": "partyId", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$", "description": "Effective party ID (pty_*) for delegated payment request access." }, "allowEmptyValue": true, "allowReserved": true }, { "name": "X-Agent-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "description": "Agent ID (agt_xxx) identifying which agent is making the request." }, { "name": "X-Instance-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 1024 }, { "type": "null" } ] }, "description": "Required when X-Agent-ID is present. Session or conversation ID for agent observability." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "description": "Resource type", "type": "string", "enum": [ "paymentRequest" ] }, "id": { "type": "string", "pattern": "^prq_[0-9a-f]{32}$", "description": "Resource ID (prq_*)" }, "attributes": { "type": "object", "properties": { "amount": { "type": "integer", "description": "Amount in cents" }, "currency": { "type": "string", "description": "Currency code" }, "status": { "enum": [ "OPEN", "PROCESSING", "COMPLETED", "FAILED", "RETURNED", "CANCELED", "DECLINED", "EXPIRED" ], "type": "string", "description": "Current status of the payment request" }, "description": { "anyOf": [ { "type": "string", "maxLength": 500 }, { "type": "null" } ], "description": "Free-form description provided at creation. Maximum 500 characters." }, "requesterName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Display name of the party requesting payment" }, "requesterEmail": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Email of the party requesting payment" }, "payerName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Display name of the payer" }, "payerEmail": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Email of the payer if addressed by email" }, "payerPhone": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Phone of the payer in E.164 format if addressed by phone" }, "payerPartyId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Natural party ID (pty_*) resolved for the payer, including agent owner parties" }, "payerIdentifierType": { "enum": [ "email", "phone", "party_id", "agent_id", "handle" ], "type": "string", "description": "Which identifier type was used to address the payer" }, "payerIdentifier": { "type": "string", "description": "The identifier value used to address the payer" }, "paymentLinkUrl": { "type": "string", "format": "uri", "description": "URL the payer visits to complete payment" }, "transactionId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "ID of the transaction created by the most recent payment attempt, or null if no attempt yet" }, "createdAt": { "type": "string", "description": "ISO 8601 timestamp when the payment request was created" }, "updatedAt": { "type": "string", "description": "ISO 8601 timestamp when the payment request was last updated" } }, "required": [ "amount", "currency", "status", "description", "requesterName", "requesterEmail", "payerName", "payerEmail", "payerPhone", "payerPartyId", "payerIdentifierType", "payerIdentifier", "paymentLinkUrl", "transactionId", "createdAt", "updatedAt" ], "additionalProperties": false, "title": "PaymentRequestAttributes", "description": "Resource attributes" }, "relationships": { "type": "object", "properties": { "requesterParty": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "description": "Resource 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 requesting the payment" }, "wallet": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "description": "Resource type", "type": "string", "enum": [ "wallet" ] }, "id": { "type": "string", "pattern": "^wal_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier" } }, "required": [ "data" ], "additionalProperties": false, "title": "ToOneRelationship", "description": "Wallet that receives the funds" }, "payerParty": { "type": "object", "properties": { "data": { "anyOf": [ { "type": "object", "properties": { "type": { "description": "Resource 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" }, { "type": "null" } ] } }, "required": [ "data" ], "additionalProperties": false, "title": "NullableToOneRelationship", "description": "Resolved payer party, if the payer is known to Natural" }, "payment": { "type": "object", "properties": { "data": { "anyOf": [ { "type": "object", "properties": { "type": { "description": "Resource type", "type": "string", "enum": [ "payment" ] }, "id": { "type": "string", "pattern": "^pay_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier" }, { "type": "null" } ] } }, "required": [ "data" ], "additionalProperties": false, "title": "NullableToOneRelationship", "description": "Payment submitted for this payment request, if one exists." } }, "required": [ "requesterParty", "wallet", "payerParty", "payment" ], "additionalProperties": false, "title": "PaymentRequestRelationships", "description": "Resource relationships" } }, "required": [ "type", "id", "attributes", "relationships" ], "additionalProperties": false, "title": "PaymentRequestResource" } }, "required": [ "data" ], "additionalProperties": false, "title": "PaymentRequestResponse" }, "examples": { "default": { "summary": "Default", "value": { "data": { "type": "paymentRequest", "id": "prq_550e8400e29b41d4a716446655440000", "attributes": { "amount": 2500, "currency": "USD", "status": "OPEN", "description": "Invoice 7", "requesterName": "Acme Payments", "requesterEmail": "billing@acmepayments.com", "payerName": "Ada Lovelace", "payerEmail": "ada@example.com", "payerPhone": null, "payerPartyId": null, "payerIdentifierType": "email", "payerIdentifier": "ada@example.com", "paymentLinkUrl": "https://natural.co/paymentLink/token_123", "transactionId": null, "createdAt": "2026-04-15T00:00:00.000Z", "updatedAt": "2026-04-15T00:00:00.000Z" }, "relationships": { "requesterParty": { "data": { "type": "party", "id": "pty_019cd1798d617f65a79cb965dda9eac3" } }, "wallet": { "data": { "type": "wallet", "id": "wal_550e8400e29b41d4a716446655440000" } }, "payerParty": { "data": null }, "payment": { "data": 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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "A request value is invalid.", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "email: Invalid email address", "status": "422", "source": { "pointer": "/data/attributes/email" }, "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "428": { "description": "Precondition Required", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "mfa_required", "detail": "MFA verification required", "status": "428", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "429": { "description": "Too Many Requests", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "rate_limited", "detail": "Too many requests. Please try again later.", "status": "429", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying", "schema": { "type": "integer" } }, "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" } } } }, "500": { "description": "Internal Server 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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "server_error", "detail": "Something went wrong.", "status": "500", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "501": { "description": "Not Implemented", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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_implemented", "detail": "This operation is not available.", "status": "501", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "502": { "description": "Bad Gateway", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "bad_gateway", "detail": "We couldn't complete that request because one of Natural's services returned an unexpected response. Please try again.", "status": "502", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "503": { "description": "Service Unavailable", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "service_unavailable", "detail": "The service is temporarily unavailable.", "status": "503", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } } }, "security": [ { "HTTPBearer": [] } ] } }, "/payment-requests/{paymentRequestId}/fulfill": { "post": { "operationId": "paymentRequests.fulfill", "summary": "Fulfill payment request", "description": "Fulfill an open payment request from inside the authenticated app.", "tags": [ "PaymentRequests" ], "parameters": [ { "name": "paymentRequestId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^prq_[0-9a-f]{32}$" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Unique key for idempotent request handling. If a request with the same key was already processed, the original response is returned." }, { "name": "X-Agent-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "description": "Agent ID (agt_xxx) identifying which agent is making the request." }, { "name": "X-Instance-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 1024 }, { "type": "null" } ] }, "description": "Required when X-Agent-ID is present. Session or conversation ID for agent observability." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "partyId": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$", "description": "Effective payer party ID (pty_*) for delegated payment request fulfillment." }, "data": { "type": "object", "properties": { "attributes": { "type": "object", "properties": { "paymentSource": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "wallet" ] }, "walletId": { "type": "string", "pattern": "^wal_[0-9a-f]{32}$" } }, "required": [ "type", "walletId" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "external_account" ] }, "externalAccountId": { "type": "string", "pattern": "^eac_[0-9a-f]{32}$" } }, "required": [ "type", "externalAccountId" ], "additionalProperties": false } ] } }, "required": [ "paymentSource" ], "additionalProperties": false } }, "required": [ "attributes" ], "additionalProperties": false } }, "required": [ "data" ], "additionalProperties": false }, "examples": { "default": { "summary": "Default", "value": { "data": { "attributes": { "paymentSource": { "type": "wallet", "walletId": "wal_550e8400e29b41d4a716446655440000" } } } } } } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "payment" ] }, "id": { "type": "string", "pattern": "^pay_[0-9a-f]{32}$" }, "attributes": { "type": "object", "properties": { "amount": { "type": "integer", "description": "Amount in cents" }, "currency": { "type": "string", "description": "Currency code" }, "status": { "enum": [ "CREATED", "PROCESSING", "PENDING_CLAIM", "IN_REVIEW", "COMPLETED", "FAILED", "RETURNED", "APPROVAL_DENIED", "CANCELED" ], "type": "string", "description": "Payment status" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Payment description" }, "createdAt": { "type": "string", "description": "When this payment was created" }, "updatedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "When this payment was last updated" } }, "required": [ "amount", "currency", "status", "description", "createdAt", "updatedAt" ], "additionalProperties": false, "title": "PaymentAttributes", "description": "Resource attributes" }, "relationships": { "type": "object", "properties": { "sender": { "type": "object", "properties": { "data": { "anyOf": [ { "type": "object", "properties": { "type": { "description": "Resource 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" }, { "type": "null" } ] } }, "required": [ "data" ], "additionalProperties": false, "title": "NullableToOneRelationship", "description": "Party that initiated the payment, when the sender is on Natural." }, "recipient": { "type": "object", "properties": { "data": { "anyOf": [ { "type": "object", "properties": { "type": { "description": "Resource 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" }, { "type": "null" } ] } }, "required": [ "data" ], "additionalProperties": false, "title": "NullableToOneRelationship", "description": "Recipient party for this payment, when known." }, "recipientAgent": { "type": "object", "properties": { "data": { "anyOf": [ { "type": "object", "properties": { "type": { "description": "Resource type", "type": "string", "enum": [ "agent" ] }, "id": { "type": "string", "pattern": "^agt_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier" }, { "type": "null" } ] } }, "required": [ "data" ], "additionalProperties": false, "title": "NullableToOneRelationship", "description": "Recipient agent when the caller addressed an agent ID. Null otherwise, including when the recipient was addressed as an email, phone, or party ID." }, "transaction": { "type": "object", "properties": { "data": { "anyOf": [ { "type": "object", "properties": { "type": { "description": "Resource type", "type": "string", "enum": [ "transaction" ] }, "id": { "type": "string" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier" }, { "type": "null" } ] } }, "required": [ "data" ], "additionalProperties": false, "title": "NullableToOneRelationship", "description": "Sender-side transaction row for this payment, when available." }, "paymentRequest": { "type": "object", "properties": { "data": { "anyOf": [ { "type": "object", "properties": { "type": { "description": "Resource type", "type": "string", "enum": [ "paymentRequest" ] }, "id": { "type": "string", "pattern": "^prq_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier" }, { "type": "null" } ] } }, "required": [ "data" ], "additionalProperties": false, "title": "NullableToOneRelationship", "description": "Payment request that produced this payment, when applicable." } }, "required": [ "sender", "recipient", "recipientAgent", "transaction", "paymentRequest" ], "additionalProperties": false, "title": "PaymentRelationships", "description": "Resource relationships" } }, "required": [ "type", "id", "attributes", "relationships" ], "additionalProperties": false, "title": "PaymentResource" } }, "required": [ "data" ], "additionalProperties": false }, "examples": { "default": { "summary": "Default", "value": { "data": { "type": "payment", "id": "pay_550e8400e29b41d4a716446655440000", "attributes": { "amount": 2500, "currency": "USD", "status": "PROCESSING", "description": "Invoice 7", "createdAt": "2026-04-15T00:00:00.000Z", "updatedAt": "2026-04-15T00:00:00.000Z" }, "relationships": { "sender": { "data": { "type": "party", "id": "pty_550e8400e29b41d4a716446655440000" } }, "recipient": { "data": { "type": "party", "id": "pty_019cd1798d617f65a79cb965dda9eac3" } }, "recipientAgent": { "data": null }, "transaction": { "data": null }, "paymentRequest": { "data": { "type": "paymentRequest", "id": "prq_550e8400e29b41d4a716446655440000" } } } } } } } } }, "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "A request value is invalid.", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "email: Invalid email address", "status": "422", "source": { "pointer": "/data/attributes/email" }, "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "428": { "description": "Precondition Required", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "mfa_required", "detail": "MFA verification required", "status": "428", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "429": { "description": "Too Many Requests", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "rate_limited", "detail": "Too many requests. Please try again later.", "status": "429", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying", "schema": { "type": "integer" } }, "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" } } } }, "500": { "description": "Internal Server 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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "server_error", "detail": "Something went wrong.", "status": "500", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "501": { "description": "Not Implemented", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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_implemented", "detail": "This operation is not available.", "status": "501", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "502": { "description": "Bad Gateway", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "bad_gateway", "detail": "We couldn't complete that request because one of Natural's services returned an unexpected response. Please try again.", "status": "502", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "503": { "description": "Service Unavailable", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "service_unavailable", "detail": "The service is temporarily unavailable.", "status": "503", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } } }, "security": [ { "HTTPBearer": [] } ] } }, "/payment-requests/{paymentRequestId}/decline": { "post": { "operationId": "paymentRequests.decline", "summary": "Decline payment request", "description": "Decline an open payment request where the authenticated party is expected to pay.", "tags": [ "PaymentRequests" ], "parameters": [ { "name": "paymentRequestId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^prq_[0-9a-f]{32}$" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Unique key for idempotent request handling. If a request with the same key was already processed, the original response is returned." }, { "name": "X-Agent-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "description": "Agent ID (agt_xxx) identifying which agent is making the request." }, { "name": "X-Instance-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 1024 }, { "type": "null" } ] }, "description": "Required when X-Agent-ID is present. Session or conversation ID for agent observability." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "description": "Resource type", "type": "string", "enum": [ "paymentRequest" ] }, "id": { "type": "string", "pattern": "^prq_[0-9a-f]{32}$", "description": "Resource ID (prq_*)" }, "attributes": { "type": "object", "properties": { "amount": { "type": "integer", "description": "Amount in cents" }, "currency": { "type": "string", "description": "Currency code" }, "status": { "enum": [ "OPEN", "PROCESSING", "COMPLETED", "FAILED", "RETURNED", "CANCELED", "DECLINED", "EXPIRED" ], "type": "string", "description": "Current status of the payment request" }, "description": { "anyOf": [ { "type": "string", "maxLength": 500 }, { "type": "null" } ], "description": "Free-form description provided at creation. Maximum 500 characters." }, "requesterName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Display name of the party requesting payment" }, "requesterEmail": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Email of the party requesting payment" }, "payerName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Display name of the payer" }, "payerEmail": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Email of the payer if addressed by email" }, "payerPhone": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Phone of the payer in E.164 format if addressed by phone" }, "payerPartyId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Natural party ID (pty_*) resolved for the payer, including agent owner parties" }, "payerIdentifierType": { "enum": [ "email", "phone", "party_id", "agent_id", "handle" ], "type": "string", "description": "Which identifier type was used to address the payer" }, "payerIdentifier": { "type": "string", "description": "The identifier value used to address the payer" }, "paymentLinkUrl": { "type": "string", "format": "uri", "description": "URL the payer visits to complete payment" }, "transactionId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "ID of the transaction created by the most recent payment attempt, or null if no attempt yet" }, "createdAt": { "type": "string", "description": "ISO 8601 timestamp when the payment request was created" }, "updatedAt": { "type": "string", "description": "ISO 8601 timestamp when the payment request was last updated" } }, "required": [ "amount", "currency", "status", "description", "requesterName", "requesterEmail", "payerName", "payerEmail", "payerPhone", "payerPartyId", "payerIdentifierType", "payerIdentifier", "paymentLinkUrl", "transactionId", "createdAt", "updatedAt" ], "additionalProperties": false, "title": "PaymentRequestAttributes", "description": "Resource attributes" }, "relationships": { "type": "object", "properties": { "requesterParty": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "description": "Resource 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 requesting the payment" }, "wallet": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "description": "Resource type", "type": "string", "enum": [ "wallet" ] }, "id": { "type": "string", "pattern": "^wal_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier" } }, "required": [ "data" ], "additionalProperties": false, "title": "ToOneRelationship", "description": "Wallet that receives the funds" }, "payerParty": { "type": "object", "properties": { "data": { "anyOf": [ { "type": "object", "properties": { "type": { "description": "Resource 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" }, { "type": "null" } ] } }, "required": [ "data" ], "additionalProperties": false, "title": "NullableToOneRelationship", "description": "Resolved payer party, if the payer is known to Natural" }, "payment": { "type": "object", "properties": { "data": { "anyOf": [ { "type": "object", "properties": { "type": { "description": "Resource type", "type": "string", "enum": [ "payment" ] }, "id": { "type": "string", "pattern": "^pay_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier" }, { "type": "null" } ] } }, "required": [ "data" ], "additionalProperties": false, "title": "NullableToOneRelationship", "description": "Payment submitted for this payment request, if one exists." } }, "required": [ "requesterParty", "wallet", "payerParty", "payment" ], "additionalProperties": false, "title": "PaymentRequestRelationships", "description": "Resource relationships" } }, "required": [ "type", "id", "attributes", "relationships" ], "additionalProperties": false, "title": "PaymentRequestResource" } }, "required": [ "data" ], "additionalProperties": false, "title": "PaymentRequestResponse" }, "examples": { "default": { "summary": "Default", "value": { "data": { "type": "paymentRequest", "id": "prq_550e8400e29b41d4a716446655440000", "attributes": { "amount": 500, "currency": "USD", "status": "DECLINED", "requesterName": "Natural Coffee", "requesterEmail": "billing@natural.test", "description": "Invoice 7", "payerName": "Ada Lovelace", "payerEmail": "ada@example.com", "payerPhone": "+14155550100", "payerPartyId": "pty_550e8400e29b41d4a716446655440000", "payerIdentifierType": "party_id", "payerIdentifier": "pty_550e8400e29b41d4a716446655440000", "paymentLinkUrl": "https://app.natural.test/pay/token_123", "transactionId": null, "createdAt": "2026-04-15T00:00:00.000Z", "updatedAt": "2026-04-15T00:00:00.000Z" }, "relationships": { "requesterParty": { "data": { "type": "party", "id": "pty_019cd1798d617f65a79cb965dda9eac3" } }, "wallet": { "data": { "type": "wallet", "id": "wal_550e8400e29b41d4a716446655440000" } }, "payerParty": { "data": { "type": "party", "id": "pty_550e8400e29b41d4a716446655440000" } }, "payment": { "data": 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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "A request value is invalid.", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "email: Invalid email address", "status": "422", "source": { "pointer": "/data/attributes/email" }, "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "428": { "description": "Precondition Required", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "mfa_required", "detail": "MFA verification required", "status": "428", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "429": { "description": "Too Many Requests", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "rate_limited", "detail": "Too many requests. Please try again later.", "status": "429", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying", "schema": { "type": "integer" } }, "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" } } } }, "500": { "description": "Internal Server 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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "server_error", "detail": "Something went wrong.", "status": "500", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "501": { "description": "Not Implemented", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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_implemented", "detail": "This operation is not available.", "status": "501", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "502": { "description": "Bad Gateway", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "bad_gateway", "detail": "We couldn't complete that request because one of Natural's services returned an unexpected response. Please try again.", "status": "502", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "503": { "description": "Service Unavailable", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "service_unavailable", "detail": "The service is temporarily unavailable.", "status": "503", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } } }, "security": [ { "HTTPBearer": [] } ] } }, "/approvals": { "get": { "operationId": "approvals.list", "summary": "List approvals", "description": "List approvals for your party.", "tags": [ "Approvals" ], "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50, "description": "Maximum number to return" }, "allowEmptyValue": true, "allowReserved": true }, { "name": "status", "in": "query", "schema": { "enum": [ "pending", "approved", "denied", "canceled" ], "type": "string", "description": "Approval status to list. Defaults to pending approvals." }, "allowEmptyValue": true, "allowReserved": true }, { "name": "X-Agent-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "description": "Agent ID (agt_xxx) identifying which agent is making the request." }, { "name": "X-Instance-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 1024 }, { "type": "null" } ] }, "description": "Required when X-Agent-ID is present. Session or conversation ID for agent observability." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "type": { "description": "Resource type", "type": "string", "enum": [ "approval" ] }, "id": { "type": "string", "description": "Approval ID" }, "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": "Product execution type under approval" }, "id": { "type": "string", "description": "Product execution ID" } }, "required": [ "type", "id" ], "additionalProperties": false, "description": "Product operation that needs approval" }, "reasons": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "limitExceeded" ] }, "limitType": { "enum": [ "perTransactionAmount", "dailyAmount", "monthlyAmount" ], "type": "string", "description": "Configured limit type that caused the approval" }, "limitAmount": { "type": "integer", "description": "Configured limit amount in minor units" }, "actualAmount": { "type": "integer", "description": "Actual transaction amount or projected daily usage in minor units" }, "currency": { "type": "string", "description": "Currency code" } }, "required": [ "type", "limitType", "limitAmount", "actualAmount", "currency" ], "additionalProperties": false } ] }, "description": "Reasons this approval is under review" }, "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", "reasons", "createdAt", "updatedAt", "resolvedAt" ], "additionalProperties": false, "description": "Resource attributes" } }, "required": [ "type", "id", "attributes" ], "additionalProperties": false } }, "meta": { "type": "object", "properties": { "pagination": { "type": "object", "properties": { "hasMore": { "type": "boolean" }, "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "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" }, "reasons": [ { "type": "limitExceeded", "limitType": "perTransactionAmount", "limitAmount": 250000, "actualAmount": 500000, "currency": "USD" } ], "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "A request value is invalid.", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "email: Invalid email address", "status": "422", "source": { "pointer": "/data/attributes/email" }, "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "428": { "description": "Precondition Required", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "mfa_required", "detail": "MFA verification required", "status": "428", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "429": { "description": "Too Many Requests", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "rate_limited", "detail": "Too many requests. Please try again later.", "status": "429", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying", "schema": { "type": "integer" } }, "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" } } } }, "500": { "description": "Internal Server 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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "server_error", "detail": "Something went wrong.", "status": "500", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "501": { "description": "Not Implemented", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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_implemented", "detail": "This operation is not available.", "status": "501", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "502": { "description": "Bad Gateway", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "bad_gateway", "detail": "We couldn't complete that request because one of Natural's services returned an unexpected response. Please try again.", "status": "502", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "503": { "description": "Service Unavailable", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "service_unavailable", "detail": "The service is temporarily unavailable.", "status": "503", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } } }, "security": [ { "HTTPBearer": [] } ] } }, "/approvals/{approvalId}": { "get": { "operationId": "approvals.get", "summary": "Get approval details", "description": "Get details of a specific approval.", "tags": [ "Approvals" ], "parameters": [ { "name": "approvalId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^apr_[0-9a-f]{32}$", "description": "Approval ID (apr_xxx format)" } }, { "name": "X-Agent-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "description": "Agent ID (agt_xxx) identifying which agent is making the request." }, { "name": "X-Instance-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 1024 }, { "type": "null" } ] }, "description": "Required when X-Agent-ID is present. Session or conversation ID for agent observability." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "description": "Resource type", "type": "string", "enum": [ "approval" ] }, "id": { "type": "string", "description": "Approval ID" }, "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": "Product execution type under approval" }, "id": { "type": "string", "description": "Product execution ID" } }, "required": [ "type", "id" ], "additionalProperties": false, "description": "Product operation that needs approval" }, "reasons": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "limitExceeded" ] }, "limitType": { "enum": [ "perTransactionAmount", "dailyAmount", "monthlyAmount" ], "type": "string", "description": "Configured limit type that caused the approval" }, "limitAmount": { "type": "integer", "description": "Configured limit amount in minor units" }, "actualAmount": { "type": "integer", "description": "Actual transaction amount or projected daily usage in minor units" }, "currency": { "type": "string", "description": "Currency code" } }, "required": [ "type", "limitType", "limitAmount", "actualAmount", "currency" ], "additionalProperties": false } ] }, "description": "Reasons this approval is under review" }, "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", "reasons", "createdAt", "updatedAt", "resolvedAt" ], "additionalProperties": false, "description": "Resource attributes" } }, "required": [ "type", "id", "attributes" ], "additionalProperties": false } }, "required": [ "data" ], "additionalProperties": false }, "examples": { "default": { "summary": "Default", "value": { "data": { "type": "approval", "id": "apr_550e8400e29b41d4a716446655440000", "attributes": { "status": "pending", "target": { "type": "payment", "id": "pay_550e8400e29b41d4a716446655440001" }, "reasons": [ { "type": "limitExceeded", "limitType": "perTransactionAmount", "limitAmount": 250000, "actualAmount": 500000, "currency": "USD" } ], "createdAt": "2026-01-04T15:30:00.000Z", "updatedAt": "2026-01-04T15:30:00.000Z", "resolvedAt": 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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "A request value is invalid.", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "email: Invalid email address", "status": "422", "source": { "pointer": "/data/attributes/email" }, "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "428": { "description": "Precondition Required", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "mfa_required", "detail": "MFA verification required", "status": "428", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "429": { "description": "Too Many Requests", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "rate_limited", "detail": "Too many requests. Please try again later.", "status": "429", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying", "schema": { "type": "integer" } }, "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" } } } }, "500": { "description": "Internal Server 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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "server_error", "detail": "Something went wrong.", "status": "500", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "501": { "description": "Not Implemented", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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_implemented", "detail": "This operation is not available.", "status": "501", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "502": { "description": "Bad Gateway", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "bad_gateway", "detail": "We couldn't complete that request because one of Natural's services returned an unexpected response. Please try again.", "status": "502", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "503": { "description": "Service Unavailable", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "service_unavailable", "detail": "The service is temporarily unavailable.", "status": "503", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } } }, "security": [ { "HTTPBearer": [] } ] } }, "/approvals/{approvalId}/approve": { "post": { "operationId": "approvals.approve", "summary": "Approve approval", "description": "Approve the product operation under review.", "tags": [ "Approvals" ], "parameters": [ { "name": "approvalId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^apr_[0-9a-f]{32}$", "description": "Approval ID (apr_xxx format)" } }, { "name": "X-Agent-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "description": "Agent ID (agt_xxx) identifying which agent is making the request." }, { "name": "X-Instance-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 1024 }, { "type": "null" } ] }, "description": "Required when X-Agent-ID is present. Session or conversation ID for agent observability." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "description": "Resource type", "type": "string", "enum": [ "approval" ] }, "id": { "type": "string", "description": "Approval ID" }, "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": "Product execution type under approval" }, "id": { "type": "string", "description": "Product execution ID" } }, "required": [ "type", "id" ], "additionalProperties": false, "description": "Product operation that needs approval" }, "reasons": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "limitExceeded" ] }, "limitType": { "enum": [ "perTransactionAmount", "dailyAmount", "monthlyAmount" ], "type": "string", "description": "Configured limit type that caused the approval" }, "limitAmount": { "type": "integer", "description": "Configured limit amount in minor units" }, "actualAmount": { "type": "integer", "description": "Actual transaction amount or projected daily usage in minor units" }, "currency": { "type": "string", "description": "Currency code" } }, "required": [ "type", "limitType", "limitAmount", "actualAmount", "currency" ], "additionalProperties": false } ] }, "description": "Reasons this approval is under review" }, "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", "reasons", "createdAt", "updatedAt", "resolvedAt" ], "additionalProperties": false, "description": "Resource attributes" } }, "required": [ "type", "id", "attributes" ], "additionalProperties": false } }, "required": [ "data" ], "additionalProperties": false }, "examples": { "default": { "summary": "Default", "value": { "data": { "type": "approval", "id": "apr_550e8400e29b41d4a716446655440000", "attributes": { "status": "approved", "target": { "type": "payment", "id": "pay_550e8400e29b41d4a716446655440001" }, "reasons": [ { "type": "limitExceeded", "limitType": "perTransactionAmount", "limitAmount": 250000, "actualAmount": 500000, "currency": "USD" } ], "createdAt": "2026-01-04T15:30:00.000Z", "updatedAt": "2026-01-04T15:45:00.000Z", "resolvedAt": "2026-01-04T15:45:00.000Z" } } } } } } }, "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "A request value is invalid.", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "email: Invalid email address", "status": "422", "source": { "pointer": "/data/attributes/email" }, "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "428": { "description": "Precondition Required", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "mfa_required", "detail": "MFA verification required", "status": "428", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "429": { "description": "Too Many Requests", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "rate_limited", "detail": "Too many requests. Please try again later.", "status": "429", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying", "schema": { "type": "integer" } }, "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" } } } }, "500": { "description": "Internal Server 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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "server_error", "detail": "Something went wrong.", "status": "500", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "501": { "description": "Not Implemented", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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_implemented", "detail": "This operation is not available.", "status": "501", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "502": { "description": "Bad Gateway", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "bad_gateway", "detail": "We couldn't complete that request because one of Natural's services returned an unexpected response. Please try again.", "status": "502", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "503": { "description": "Service Unavailable", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "service_unavailable", "detail": "The service is temporarily unavailable.", "status": "503", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } } }, "security": [ { "HTTPBearer": [] } ] } }, "/approvals/{approvalId}/deny": { "post": { "operationId": "approvals.deny", "summary": "Deny approval", "description": "Deny the product operation under review.", "tags": [ "Approvals" ], "parameters": [ { "name": "approvalId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^apr_[0-9a-f]{32}$", "description": "Approval ID (apr_xxx format)" } }, { "name": "X-Agent-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "description": "Agent ID (agt_xxx) identifying which agent is making the request." }, { "name": "X-Instance-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 1024 }, { "type": "null" } ] }, "description": "Required when X-Agent-ID is present. Session or conversation ID for agent observability." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "description": "Resource type", "type": "string", "enum": [ "approval" ] }, "id": { "type": "string", "description": "Approval ID" }, "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": "Product execution type under approval" }, "id": { "type": "string", "description": "Product execution ID" } }, "required": [ "type", "id" ], "additionalProperties": false, "description": "Product operation that needs approval" }, "reasons": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "limitExceeded" ] }, "limitType": { "enum": [ "perTransactionAmount", "dailyAmount", "monthlyAmount" ], "type": "string", "description": "Configured limit type that caused the approval" }, "limitAmount": { "type": "integer", "description": "Configured limit amount in minor units" }, "actualAmount": { "type": "integer", "description": "Actual transaction amount or projected daily usage in minor units" }, "currency": { "type": "string", "description": "Currency code" } }, "required": [ "type", "limitType", "limitAmount", "actualAmount", "currency" ], "additionalProperties": false } ] }, "description": "Reasons this approval is under review" }, "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", "reasons", "createdAt", "updatedAt", "resolvedAt" ], "additionalProperties": false, "description": "Resource attributes" } }, "required": [ "type", "id", "attributes" ], "additionalProperties": false } }, "required": [ "data" ], "additionalProperties": false }, "examples": { "default": { "summary": "Default", "value": { "data": { "type": "approval", "id": "apr_550e8400e29b41d4a716446655440000", "attributes": { "status": "denied", "target": { "type": "payment", "id": "pay_550e8400e29b41d4a716446655440001" }, "reasons": [ { "type": "limitExceeded", "limitType": "perTransactionAmount", "limitAmount": 250000, "actualAmount": 500000, "currency": "USD" } ], "createdAt": "2026-01-04T15:30:00.000Z", "updatedAt": "2026-01-04T15:45:00.000Z", "resolvedAt": "2026-01-04T15:45:00.000Z" } } } } } } }, "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "A request value is invalid.", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "email: Invalid email address", "status": "422", "source": { "pointer": "/data/attributes/email" }, "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "428": { "description": "Precondition Required", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "mfa_required", "detail": "MFA verification required", "status": "428", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "429": { "description": "Too Many Requests", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "rate_limited", "detail": "Too many requests. Please try again later.", "status": "429", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying", "schema": { "type": "integer" } }, "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" } } } }, "500": { "description": "Internal Server 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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "server_error", "detail": "Something went wrong.", "status": "500", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "501": { "description": "Not Implemented", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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_implemented", "detail": "This operation is not available.", "status": "501", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "502": { "description": "Bad Gateway", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "bad_gateway", "detail": "We couldn't complete that request because one of Natural's services returned an unexpected response. Please try again.", "status": "502", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "503": { "description": "Service Unavailable", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "service_unavailable", "detail": "The service is temporarily unavailable.", "status": "503", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } } }, "security": [ { "HTTPBearer": [] } ] } }, "/party-invitations": { "post": { "operationId": "invitations.create", "summary": "Create party invitations", "description": "Send invitations to join your party.", "tags": [ "Invitations" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "attributes": { "type": "object", "properties": { "invitations": { "type": "array", "maxItems": 100, "items": { "type": "object", "properties": { "email": { "type": "string", "format": "email", "description": "Email address to invite" }, "role": { "enum": [ "ADMIN", "MEMBER", "VIEWER" ], "type": "string", "description": "Role to assign on acceptance" } }, "required": [ "email", "role" ], "additionalProperties": false, "title": "InvitationItem", "description": "Single invitation in batch request" }, "description": "List of invitations to create (max 100)" } }, "required": [ "invitations" ], "additionalProperties": false, "title": "InvitationCreateAttributes", "description": "Resource attributes" } }, "required": [ "attributes" ], "additionalProperties": false, "title": "InvitationCreateData" } }, "required": [ "data" ], "additionalProperties": false, "title": "CreateInvitationsInput" }, "examples": { "default": { "summary": "Default", "value": { "data": { "attributes": { "invitations": [ { "email": "engineer@velocitylogistics.com", "role": "MEMBER" }, { "email": "cfo@velocitylogistics.com", "role": "ADMIN" } ] } } } } } } } }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "type": { "description": "Resource type", "type": "string", "enum": [ "invitation" ] }, "id": { "type": "string", "pattern": "^inv_[0-9a-f]{32}$", "description": "Invitation ID (inv_xxx)" }, "attributes": { "type": "object", "properties": { "email": { "type": "string", "description": "Invitee email address" }, "role": { "enum": [ "OWNER", "ADMIN", "MEMBER", "VIEWER" ], "type": "string", "description": "Role assigned on acceptance" }, "status": { "enum": [ "PENDING", "ACCEPTED", "REVOKED", "DECLINED" ], "type": "string", "description": "Invitation status" }, "expiresAt": { "type": "string", "description": "When this invitation expires" }, "createdAt": { "type": "string", "description": "When this invitation was created" }, "acceptedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "When this invitation was accepted" } }, "required": [ "email", "role", "status", "expiresAt", "createdAt", "acceptedAt" ], "additionalProperties": false, "title": "InvitationAttributes", "description": "Resource attributes" } }, "required": [ "type", "id", "attributes" ], "additionalProperties": false, "title": "InvitationResource" }, "description": "Successfully created invitation resources" }, "meta": { "type": "object", "properties": { "failed": { "type": "array", "items": { "type": "object", "properties": { "email": { "type": "string", "description": "Email address that was invited" }, "error": { "type": "string", "description": "Error message for failed invitation" } }, "required": [ "email", "error" ], "additionalProperties": false, "title": "InvitationResult", "description": "Failed invitation result" }, "description": "Failed invitation attempts with error details" } }, "required": [ "failed" ], "additionalProperties": false, "title": "CreateInvitationsMeta", "description": "Batch invitation metadata" } }, "required": [ "data", "meta" ], "additionalProperties": false, "title": "CreateInvitationsOutput" }, "examples": { "default": { "summary": "Default", "value": { "data": [ { "type": "invitation", "id": "inv_019cd4a832f37c4b8a1d63e94b7c8d12", "attributes": { "email": "engineer@velocitylogistics.com", "role": "MEMBER", "status": "PENDING", "expiresAt": "2026-01-11T15:30:00Z", "createdAt": "2026-01-04T15:30:00Z", "acceptedAt": null } } ], "meta": { "failed": [ { "email": "cfo@velocitylogistics.com", "error": "User is already a member of this party" } ] } } } } } }, "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "A request value is invalid.", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "email: Invalid email address", "status": "422", "source": { "pointer": "/data/attributes/email" }, "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "428": { "description": "Precondition Required", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "mfa_required", "detail": "MFA verification required", "status": "428", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "429": { "description": "Too Many Requests", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "rate_limited", "detail": "Too many requests. Please try again later.", "status": "429", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying", "schema": { "type": "integer" } }, "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" } } } }, "500": { "description": "Internal Server 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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "server_error", "detail": "Something went wrong.", "status": "500", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "501": { "description": "Not Implemented", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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_implemented", "detail": "This operation is not available.", "status": "501", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "502": { "description": "Bad Gateway", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "bad_gateway", "detail": "We couldn't complete that request because one of Natural's services returned an unexpected response. Please try again.", "status": "502", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "503": { "description": "Service Unavailable", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "service_unavailable", "detail": "The service is temporarily unavailable.", "status": "503", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } } }, "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "X-Agent-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "description": "Agent ID (agt_xxx) identifying which agent is making the request." }, { "name": "X-Instance-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 1024 }, { "type": "null" } ] }, "description": "Required when X-Agent-ID is present. Session or conversation ID for agent observability." } ] }, "get": { "operationId": "invitations.list", "summary": "List invitations", "description": "List invitations with optional filters by party, email, or status.", "tags": [ "Invitations" ], "parameters": [ { "name": "partyId", "in": "query", "schema": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$", "description": "Filter by party" }, "allowEmptyValue": true, "allowReserved": true }, { "name": "email", "in": "query", "schema": { "type": "string", "description": "Filter by email" }, "allowEmptyValue": true, "allowReserved": true }, { "name": "status", "in": "query", "schema": { "enum": [ "PENDING", "ACCEPTED", "REVOKED", "DECLINED" ], "type": "string", "description": "Filter by status" }, "allowEmptyValue": true, "allowReserved": true }, { "name": "X-Agent-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "description": "Agent ID (agt_xxx) identifying which agent is making the request." }, { "name": "X-Instance-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 1024 }, { "type": "null" } ] }, "description": "Required when X-Agent-ID is present. Session or conversation ID for agent observability." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "type": { "description": "Resource type", "type": "string", "enum": [ "invitation" ] }, "id": { "type": "string", "pattern": "^inv_[0-9a-f]{32}$", "description": "Invitation ID (inv_xxx)" }, "attributes": { "type": "object", "properties": { "email": { "type": "string", "description": "Invitee email address" }, "role": { "enum": [ "OWNER", "ADMIN", "MEMBER", "VIEWER" ], "type": "string", "description": "Role assigned on acceptance" }, "status": { "enum": [ "PENDING", "ACCEPTED", "REVOKED", "DECLINED" ], "type": "string", "description": "Invitation status" }, "expiresAt": { "type": "string", "description": "When this invitation expires" }, "createdAt": { "type": "string", "description": "When this invitation was created" }, "acceptedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "When this invitation was accepted" } }, "required": [ "email", "role", "status", "expiresAt", "createdAt", "acceptedAt" ], "additionalProperties": false, "title": "InvitationAttributes", "description": "Resource attributes" } }, "required": [ "type", "id", "attributes" ], "additionalProperties": false, "title": "InvitationResource" } }, "meta": { "type": "object", "properties": { "pagination": { "type": "object", "properties": { "hasMore": { "type": "boolean" }, "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "hasMore", "nextCursor" ], "additionalProperties": false, "title": "PaginationMeta" } }, "required": [ "pagination" ], "additionalProperties": false } }, "required": [ "data", "meta" ], "additionalProperties": false, "title": "InvitationListResponse" }, "examples": { "default": { "summary": "Default", "value": { "data": [ { "type": "invitation", "id": "inv_019cd4a832f37c4b8a1d63e94b7c8d12", "attributes": { "email": "engineer@velocitylogistics.com", "role": "MEMBER", "status": "PENDING", "expiresAt": "2026-01-11T15:30:00Z", "createdAt": "2026-01-04T15:30:00Z", "acceptedAt": 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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "A request value is invalid.", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "email: Invalid email address", "status": "422", "source": { "pointer": "/data/attributes/email" }, "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "428": { "description": "Precondition Required", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "mfa_required", "detail": "MFA verification required", "status": "428", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "429": { "description": "Too Many Requests", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "rate_limited", "detail": "Too many requests. Please try again later.", "status": "429", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying", "schema": { "type": "integer" } }, "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" } } } }, "500": { "description": "Internal Server 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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "server_error", "detail": "Something went wrong.", "status": "500", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "501": { "description": "Not Implemented", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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_implemented", "detail": "This operation is not available.", "status": "501", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "502": { "description": "Bad Gateway", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "bad_gateway", "detail": "We couldn't complete that request because one of Natural's services returned an unexpected response. Please try again.", "status": "502", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "503": { "description": "Service Unavailable", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "service_unavailable", "detail": "The service is temporarily unavailable.", "status": "503", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } } }, "security": [ { "HTTPBearer": [] } ] } }, "/party-invitations/{invitationId}": { "delete": { "operationId": "invitations.revoke", "summary": "Revoke party invitation", "description": "Revoke a pending invitation so it can no longer be accepted.", "tags": [ "Invitations" ], "parameters": [ { "name": "invitationId", "in": "path", "required": true, "schema": { "type": "string", "description": "Invitation ID" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Unique key for idempotent request handling. If a request with the same key was already processed, the original response is returned." }, { "name": "X-Agent-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "description": "Agent ID (agt_xxx) identifying which agent is making the request." }, { "name": "X-Instance-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 1024 }, { "type": "null" } ] }, "description": "Required when X-Agent-ID is present. Session or conversation ID for agent observability." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "description": "Resource type", "type": "string", "enum": [ "invitation" ] }, "id": { "type": "string", "pattern": "^inv_[0-9a-f]{32}$", "description": "Invitation ID (inv_xxx)" }, "attributes": { "type": "object", "properties": { "email": { "type": "string", "description": "Invitee email address" }, "role": { "enum": [ "OWNER", "ADMIN", "MEMBER", "VIEWER" ], "type": "string", "description": "Role assigned on acceptance" }, "status": { "enum": [ "PENDING", "ACCEPTED", "REVOKED", "DECLINED" ], "type": "string", "description": "Invitation status" }, "expiresAt": { "type": "string", "description": "When this invitation expires" }, "createdAt": { "type": "string", "description": "When this invitation was created" }, "acceptedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "When this invitation was accepted" } }, "required": [ "email", "role", "status", "expiresAt", "createdAt", "acceptedAt" ], "additionalProperties": false, "title": "InvitationAttributes", "description": "Resource attributes" } }, "required": [ "type", "id", "attributes" ], "additionalProperties": false, "title": "InvitationResource" }, "meta": { "type": "object", "properties": { "deleted": { "const": true, "description": "Indicates the resource was deleted" } }, "required": [ "deleted" ], "additionalProperties": false, "title": "DeletedMeta" } }, "required": [ "data", "meta" ], "additionalProperties": false, "title": "InvitationRevokeResponse" }, "examples": { "default": { "summary": "Default", "value": { "data": { "type": "invitation", "id": "inv_019cd4a832f37c4b8a1d63e94b7c8d12", "attributes": { "email": "engineer@velocitylogistics.com", "role": "MEMBER", "status": "REVOKED", "expiresAt": "2026-01-11T15:30:00Z", "createdAt": "2026-01-04T15:30:00Z", "acceptedAt": null } }, "meta": { "deleted": true } } } } } }, "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "A request value is invalid.", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "email: Invalid email address", "status": "422", "source": { "pointer": "/data/attributes/email" }, "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "428": { "description": "Precondition Required", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "mfa_required", "detail": "MFA verification required", "status": "428", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "429": { "description": "Too Many Requests", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "rate_limited", "detail": "Too many requests. Please try again later.", "status": "429", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying", "schema": { "type": "integer" } }, "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" } } } }, "500": { "description": "Internal Server 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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "server_error", "detail": "Something went wrong.", "status": "500", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "501": { "description": "Not Implemented", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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_implemented", "detail": "This operation is not available.", "status": "501", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "502": { "description": "Bad Gateway", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "bad_gateway", "detail": "We couldn't complete that request because one of Natural's services returned an unexpected response. Please try again.", "status": "502", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "503": { "description": "Service Unavailable", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "service_unavailable", "detail": "The service is temporarily unavailable.", "status": "503", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } } }, "security": [ { "HTTPBearer": [] } ] } }, "/identity/me": { "get": { "operationId": "identity.me", "summary": "Get the caller's identity", "description": "Get the caller's own identity: home party card with handle, acting-for party, acting agent, and credential permissions.", "tags": [ "Identity" ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "description": "The caller's actor ID" }, "type": { "description": "Resource type", "type": "string", "enum": [ "identity" ] }, "attributes": { "type": "object", "properties": { "actor": { "type": "object", "properties": { "actorType": { "type": "string", "description": "Resolved actor type (e.g., USER, API, AGENT)" }, "credentialKind": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Credential class behind the request (\"api_key\", \"agent_key\", or \"oauth_grant\"), or null for a session token" }, "agentIdSource": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "How the agent identity was established (\"credential\", \"oauth_grant\", or \"header\"), or null when the caller carries no agent identity" } }, "required": [ "actorType", "credentialKind", "agentIdSource" ], "additionalProperties": false, "title": "IdentityActor", "description": "How the caller's credential was resolved" }, "party": { "type": "object", "properties": { "partyId": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$", "description": "The caller's home party" }, "displayName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Display name for the caller's home party" }, "handle": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Party handle (e.g. \"@acme\"), or null when the party has not claimed one" } }, "required": [ "partyId", "displayName", "handle" ], "additionalProperties": false, "title": "IdentityParty", "description": "The caller's home party card" }, "actingFor": { "type": "object", "properties": { "partyId": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$", "description": "The party the caller is acting for: the delegation target when delegated, otherwise the home party" } }, "required": [ "partyId" ], "additionalProperties": false, "title": "IdentityActingFor", "description": "The effective party for this request" }, "agent": { "anyOf": [ { "type": "object", "properties": { "agentId": { "type": "string", "pattern": "^agt_[0-9a-f]{32}$", "description": "Unique agent identifier" }, "name": { "type": "string", "description": "Agent name" }, "handle": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Agent handle (e.g. \"@acme/support\"), or null when the agent has no slug or the party has no handle" } }, "required": [ "agentId", "name", "handle" ], "additionalProperties": false, "title": "IdentityAgent" }, { "type": "null" } ], "description": "The acting agent, or null when the credential resolves no agent" }, "permissions": { "type": "array", "items": { "type": "string" }, "description": "Permissions granted to the credential" } }, "required": [ "actor", "party", "actingFor", "agent", "permissions" ], "additionalProperties": false, "title": "IdentityMeAttributes", "description": "Identity attributes" } }, "required": [ "id", "type", "attributes" ], "additionalProperties": false, "title": "IdentityMeResource" } }, "required": [ "data" ], "additionalProperties": false, "title": "IdentityMeResponse" }, "examples": { "default": { "summary": "Default", "value": { "data": { "id": "agt_019cd1798d657de5b5fed4198cb9fac0", "type": "identity", "attributes": { "actor": { "actorType": "AGENT", "credentialKind": "agent_key", "agentIdSource": "credential" }, "party": { "partyId": "pty_019cd1798d617f65a79cb965dda9eac3", "displayName": "Natural", "handle": "@natural" }, "actingFor": { "partyId": "pty_019cd1798d617f65a79cb965dda9eac3" }, "agent": { "agentId": "agt_019cd1798d657de5b5fed4198cb9fac0", "name": "Procurement Agent", "handle": "@natural/procurement" }, "permissions": [ "payments.create", "payments.read", "wallets.read" ] } } } } } } }, "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "A request value is invalid.", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "email: Invalid email address", "status": "422", "source": { "pointer": "/data/attributes/email" }, "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "428": { "description": "Precondition Required", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "mfa_required", "detail": "MFA verification required", "status": "428", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "429": { "description": "Too Many Requests", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "rate_limited", "detail": "Too many requests. Please try again later.", "status": "429", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying", "schema": { "type": "integer" } }, "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" } } } }, "500": { "description": "Internal Server 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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "server_error", "detail": "Something went wrong.", "status": "500", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "501": { "description": "Not Implemented", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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_implemented", "detail": "This operation is not available.", "status": "501", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "502": { "description": "Bad Gateway", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "bad_gateway", "detail": "We couldn't complete that request because one of Natural's services returned an unexpected response. Please try again.", "status": "502", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "503": { "description": "Service Unavailable", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "service_unavailable", "detail": "The service is temporarily unavailable.", "status": "503", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } } }, "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "X-Agent-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "description": "Agent ID (agt_xxx) identifying which agent is making the request." }, { "name": "X-Instance-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 1024 }, { "type": "null" } ] }, "description": "Required when X-Agent-ID is present. Session or conversation ID for agent observability." } ] } }, "/parties/me": { "get": { "operationId": "parties.get", "summary": "Get party", "description": "Get your party.", "tags": [ "Parties" ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$", "description": "Unique party identifier" }, "type": { "description": "Resource type", "type": "string", "enum": [ "party" ] }, "attributes": { "type": "object", "properties": { "partyType": { "enum": [ "PERSON", "ORG" ], "type": "string", "description": "Party type: individual or organization" }, "legalName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Legal business name for ORG parties" }, "firstName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Legal first name for PERSON parties" }, "lastName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Legal last name for PERSON parties" }, "status": { "enum": [ "PROVISIONAL", "ACTIVE", "SUSPENDED", "INACTIVE" ], "type": "string", "description": "Party status (e.g., ACTIVE, SUSPENDED)" }, "createdAt": { "type": "string", "format": "date-time", "description": "When the party was created" }, "updatedAt": { "type": "string", "format": "date-time", "description": "When the party was last updated" }, "displayName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Display name for the party" }, "handle": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Party handle (e.g. \"@acme\"), or null when the party has not claimed one" }, "persona": { "anyOf": [ { "enum": [ "INDIVIDUAL", "DEVELOPER" ], "type": "string" }, { "type": "null" } ], "description": "Party persona: INDIVIDUAL, DEVELOPER, or null during upstream rollout" }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Party's primary contact email" }, "primaryPhone": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Party's primary phone number" }, "addressLine1": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Street address line 1" }, "addressCity": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "City" }, "addressState": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "State or province" }, "addressPostalCode": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Postal or ZIP code" }, "addressCountry": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Country code (e.g., US)" }, "createdBy": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "User who created this party (usr_*)" } }, "required": [ "partyType", "legalName", "firstName", "lastName", "status", "createdAt", "updatedAt", "displayName", "handle", "persona", "email", "primaryPhone", "addressLine1", "addressCity", "addressState", "addressPostalCode", "addressCountry", "createdBy" ], "additionalProperties": false, "title": "PartyAttributes", "description": "Party attributes" } }, "required": [ "id", "type", "attributes" ], "additionalProperties": false, "title": "PartyResource" } }, "required": [ "data" ], "additionalProperties": false, "title": "PartySingleResponse" }, "examples": { "default": { "summary": "Default", "value": { "data": { "id": "pty_019cd1798d617f65a79cb965dda9eac3", "type": "party", "attributes": { "partyType": "ORG", "legalName": "Natural AI, Inc", "firstName": null, "lastName": null, "status": "ACTIVE", "createdAt": "2024-01-01T00:00:00Z", "updatedAt": "2024-01-15T10:30:00Z", "displayName": "Natural", "handle": "@natural", "persona": "DEVELOPER", "email": "contact@natural.co", "primaryPhone": "+1-555-555-0100", "addressLine1": "123 Main Street", "addressCity": "San Francisco", "addressState": "CA", "addressPostalCode": "94105", "addressCountry": "US", "createdBy": 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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "A request value is invalid.", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "email: Invalid email address", "status": "422", "source": { "pointer": "/data/attributes/email" }, "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "428": { "description": "Precondition Required", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "mfa_required", "detail": "MFA verification required", "status": "428", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "429": { "description": "Too Many Requests", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "rate_limited", "detail": "Too many requests. Please try again later.", "status": "429", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying", "schema": { "type": "integer" } }, "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" } } } }, "500": { "description": "Internal Server 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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "server_error", "detail": "Something went wrong.", "status": "500", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "501": { "description": "Not Implemented", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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_implemented", "detail": "This operation is not available.", "status": "501", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "502": { "description": "Bad Gateway", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "bad_gateway", "detail": "We couldn't complete that request because one of Natural's services returned an unexpected response. Please try again.", "status": "502", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "503": { "description": "Service Unavailable", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "service_unavailable", "detail": "The service is temporarily unavailable.", "status": "503", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } } }, "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "X-Agent-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "description": "Agent ID (agt_xxx) identifying which agent is making the request." }, { "name": "X-Instance-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 1024 }, { "type": "null" } ] }, "description": "Required when X-Agent-ID is present. Session or conversation ID for agent observability." } ] }, "patch": { "operationId": "parties.update", "summary": "Update party", "description": "Update your party.", "tags": [ "Parties" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "attributes": { "type": "object", "properties": { "displayName": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ], "description": "Updated display name. Pass null to clear; empty string is rejected (use null to clear instead)." } }, "additionalProperties": false, "title": "PartyUpdateAttributes" } }, "required": [ "attributes" ], "additionalProperties": false, "title": "PartyUpdateData" } }, "required": [ "data" ], "additionalProperties": false, "title": "UpdateOwnPartyInput" }, "examples": { "default": { "summary": "Default", "value": { "data": { "attributes": { "displayName": "Natural Inc." } } } } } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$", "description": "Unique party identifier" }, "type": { "description": "Resource type", "type": "string", "enum": [ "party" ] }, "attributes": { "type": "object", "properties": { "partyType": { "enum": [ "PERSON", "ORG" ], "type": "string", "description": "Party type: individual or organization" }, "legalName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Legal business name for ORG parties" }, "firstName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Legal first name for PERSON parties" }, "lastName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Legal last name for PERSON parties" }, "status": { "enum": [ "PROVISIONAL", "ACTIVE", "SUSPENDED", "INACTIVE" ], "type": "string", "description": "Party status (e.g., ACTIVE, SUSPENDED)" }, "createdAt": { "type": "string", "format": "date-time", "description": "When the party was created" }, "updatedAt": { "type": "string", "format": "date-time", "description": "When the party was last updated" }, "displayName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Display name for the party" }, "handle": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Party handle (e.g. \"@acme\"), or null when the party has not claimed one" }, "persona": { "anyOf": [ { "enum": [ "INDIVIDUAL", "DEVELOPER" ], "type": "string" }, { "type": "null" } ], "description": "Party persona: INDIVIDUAL, DEVELOPER, or null during upstream rollout" }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Party's primary contact email" }, "primaryPhone": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Party's primary phone number" }, "addressLine1": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Street address line 1" }, "addressCity": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "City" }, "addressState": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "State or province" }, "addressPostalCode": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Postal or ZIP code" }, "addressCountry": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Country code (e.g., US)" }, "createdBy": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "User who created this party (usr_*)" } }, "required": [ "partyType", "legalName", "firstName", "lastName", "status", "createdAt", "updatedAt", "displayName", "handle", "persona", "email", "primaryPhone", "addressLine1", "addressCity", "addressState", "addressPostalCode", "addressCountry", "createdBy" ], "additionalProperties": false, "title": "PartyAttributes", "description": "Party attributes" } }, "required": [ "id", "type", "attributes" ], "additionalProperties": false, "title": "PartyResource" } }, "required": [ "data" ], "additionalProperties": false, "title": "PartySingleResponse" }, "examples": { "default": { "summary": "Default", "value": { "data": { "id": "pty_019cd1798d617f65a79cb965dda9eac3", "type": "party", "attributes": { "partyType": "ORG", "legalName": "Natural AI, Inc", "firstName": null, "lastName": null, "status": "ACTIVE", "createdAt": "2024-01-01T00:00:00Z", "updatedAt": "2024-01-15T10:30:00Z", "displayName": "Natural Inc.", "handle": "@natural", "persona": "DEVELOPER", "email": "contact@natural.co", "primaryPhone": "+1-555-555-0100", "addressLine1": "123 Main Street", "addressCity": "San Francisco", "addressState": "CA", "addressPostalCode": "94105", "addressCountry": "US", "createdBy": 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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "A request value is invalid.", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "email: Invalid email address", "status": "422", "source": { "pointer": "/data/attributes/email" }, "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "428": { "description": "Precondition Required", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "mfa_required", "detail": "MFA verification required", "status": "428", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "429": { "description": "Too Many Requests", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "rate_limited", "detail": "Too many requests. Please try again later.", "status": "429", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying", "schema": { "type": "integer" } }, "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" } } } }, "500": { "description": "Internal Server 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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "server_error", "detail": "Something went wrong.", "status": "500", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "501": { "description": "Not Implemented", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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_implemented", "detail": "This operation is not available.", "status": "501", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "502": { "description": "Bad Gateway", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "bad_gateway", "detail": "We couldn't complete that request because one of Natural's services returned an unexpected response. Please try again.", "status": "502", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "503": { "description": "Service Unavailable", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "service_unavailable", "detail": "The service is temporarily unavailable.", "status": "503", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } } }, "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "X-Agent-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "description": "Agent ID (agt_xxx) identifying which agent is making the request." }, { "name": "X-Instance-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 1024 }, { "type": "null" } ] }, "description": "Required when X-Agent-ID is present. Session or conversation ID for agent observability." } ] } }, "/parties/{partyId}/compliance": { "get": { "operationId": "parties.getCompliance", "summary": "Get party compliance", "description": "Get a party's current compliance status.", "tags": [ "Parties" ], "parameters": [ { "name": "partyId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$", "description": "Unique party identifier" } }, { "name": "X-Agent-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "description": "Agent ID (agt_xxx) identifying which agent is making the request." }, { "name": "X-Instance-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 1024 }, { "type": "null" } ] }, "description": "Required when X-Agent-ID is present. Session or conversation ID for agent observability." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "description": "Compliance case ID" }, "type": { "description": "Resource type", "type": "string", "enum": [ "compliance_case" ] }, "attributes": { "type": "object", "properties": { "partyId": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$", "description": "Party this compliance status applies to" }, "status": { "enum": [ "preparingSubmission", "submitted", "actionRequired", "approved", "rejected" ], "type": "string", "description": "Current public compliance status. preparingSubmission means the case exists but has not been submitted, submitted means the case was submitted for compliance review, actionRequired means additional information is required, approved means verification passed, and rejected means verification failed." } }, "required": [ "partyId", "status" ], "additionalProperties": false, "title": "ComplianceCaseAttributes", "description": "Compliance case attributes" }, "version": { "type": "integer", "description": "Version of the compliance case" } }, "required": [ "id", "type", "attributes", "version" ], "additionalProperties": false, "title": "ComplianceCaseResource" }, { "type": "null" } ], "description": "Current canonical compliance case, or null when no current case exists." } }, "required": [ "data" ], "additionalProperties": false, "title": "PartyComplianceResponse" }, "examples": { "default": { "summary": "Default", "value": { "data": { "id": "cpc_00000000000000000000000000000001", "type": "compliance_case", "attributes": { "partyId": "pty_019cd1798d617f65a79cb965dda9eac3", "status": "approved" }, "version": 7 } } } } } }, "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "A request value is invalid.", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "email: Invalid email address", "status": "422", "source": { "pointer": "/data/attributes/email" }, "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "428": { "description": "Precondition Required", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "mfa_required", "detail": "MFA verification required", "status": "428", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "429": { "description": "Too Many Requests", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "rate_limited", "detail": "Too many requests. Please try again later.", "status": "429", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying", "schema": { "type": "integer" } }, "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" } } } }, "500": { "description": "Internal Server 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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "server_error", "detail": "Something went wrong.", "status": "500", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "501": { "description": "Not Implemented", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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_implemented", "detail": "This operation is not available.", "status": "501", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "502": { "description": "Bad Gateway", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "bad_gateway", "detail": "We couldn't complete that request because one of Natural's services returned an unexpected response. Please try again.", "status": "502", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "503": { "description": "Service Unavailable", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "service_unavailable", "detail": "The service is temporarily unavailable.", "status": "503", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } } }, "security": [ { "HTTPBearer": [] } ] } }, "/parties/me/members": { "get": { "operationId": "parties.listMembers", "summary": "List party members", "description": "List active members of your party.", "tags": [ "Parties" ], "parameters": [ { "name": "cursor", "in": "query", "schema": { "type": "string", "description": "Cursor for pagination" }, "allowEmptyValue": true, "allowReserved": true }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50, "description": "Max items per page" }, "allowEmptyValue": true, "allowReserved": true }, { "name": "X-Agent-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "description": "Agent ID (agt_xxx) identifying which agent is making the request." }, { "name": "X-Instance-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 1024 }, { "type": "null" } ] }, "description": "Required when X-Agent-ID is present. Session or conversation ID for agent observability." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "type": { "description": "Resource type", "type": "string", "enum": [ "user" ] }, "id": { "type": "string", "pattern": "^usr_[0-9a-f]{32}$", "description": "User id (usr_xxx)" }, "attributes": { "type": "object", "properties": { "partyId": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$", "description": "ID of the party this membership belongs to" }, "role": { "enum": [ "OWNER", "ADMIN", "MEMBER", "VIEWER" ], "type": "string", "description": "User's role in the party (OWNER, ADMIN, MEMBER)" }, "status": { "enum": [ "ACTIVE", "REVOKED", "DELETED" ], "type": "string", "description": "Membership status" }, "createdAt": { "type": "string", "format": "date-time", "description": "When the membership was created" }, "updatedAt": { "type": "string", "format": "date-time", "description": "When the membership was last updated" }, "firstName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "First name of the user" }, "lastName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Last name of the user" }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Email address of the user" } }, "required": [ "partyId", "role", "status", "createdAt", "updatedAt", "firstName", "lastName", "email" ], "title": "UserMemberAttributes", "description": "Resource attributes" } }, "required": [ "type", "id", "attributes" ], "additionalProperties": false, "title": "UserMemberResource" } }, "meta": { "type": "object", "properties": { "pagination": { "type": "object", "properties": { "hasMore": { "type": "boolean" }, "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "hasMore", "nextCursor" ], "additionalProperties": false, "title": "PaginationMeta" } }, "required": [ "pagination" ], "additionalProperties": false } }, "required": [ "data", "meta" ], "additionalProperties": false, "title": "PartyMembersListResponse" }, "examples": { "default": { "summary": "Default", "value": { "data": [ { "type": "user", "id": "usr_019cd1798d657de5b5fed4198cb9fac0", "attributes": { "partyId": "pty_019cd1798d617f65a79cb965dda9eac3", "role": "MEMBER", "status": "ACTIVE", "createdAt": "2024-01-01T00:00:00Z", "updatedAt": "2024-01-15T10:30:00Z", "firstName": "Eric", "lastName": "Smith", "email": "eric@natural.co" } } ], "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "A request value is invalid.", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "email: Invalid email address", "status": "422", "source": { "pointer": "/data/attributes/email" }, "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "428": { "description": "Precondition Required", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "mfa_required", "detail": "MFA verification required", "status": "428", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "429": { "description": "Too Many Requests", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "rate_limited", "detail": "Too many requests. Please try again later.", "status": "429", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying", "schema": { "type": "integer" } }, "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" } } } }, "500": { "description": "Internal Server 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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "server_error", "detail": "Something went wrong.", "status": "500", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "501": { "description": "Not Implemented", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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_implemented", "detail": "This operation is not available.", "status": "501", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "502": { "description": "Bad Gateway", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "bad_gateway", "detail": "We couldn't complete that request because one of Natural's services returned an unexpected response. Please try again.", "status": "502", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "503": { "description": "Service Unavailable", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "service_unavailable", "detail": "The service is temporarily unavailable.", "status": "503", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } } }, "security": [ { "HTTPBearer": [] } ] } }, "/parties/me/members/{userId}": { "delete": { "operationId": "parties.removeMember", "summary": "Remove party member", "description": "Remove a user from the party membership.", "tags": [ "Parties" ], "parameters": [ { "name": "userId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^usr_[0-9a-f]{32}$", "description": "User ID to remove from party" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Unique key for idempotent request handling. If a request with the same key was already processed, the original response is returned." }, { "name": "X-Agent-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "description": "Agent ID (agt_xxx) identifying which agent is making the request." }, { "name": "X-Instance-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 1024 }, { "type": "null" } ] }, "description": "Required when X-Agent-ID is present. Session or conversation ID for agent observability." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "description": "Resource type", "type": "string", "enum": [ "user" ] }, "id": { "type": "string", "pattern": "^usr_[0-9a-f]{32}$", "description": "ID of the removed user" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "RemovedMemberResource" }, "meta": { "type": "object", "properties": { "deleted": { "const": true, "description": "Indicates the resource was deleted" } }, "required": [ "deleted" ], "additionalProperties": false, "title": "DeletedMeta" } }, "required": [ "data", "meta" ], "additionalProperties": false }, "examples": { "default": { "summary": "Default", "value": { "data": { "type": "user", "id": "usr_019cd1798d657de5b5fed4198cb9fac0" }, "meta": { "deleted": true } } } } } }, "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "A request value is invalid.", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "email: Invalid email address", "status": "422", "source": { "pointer": "/data/attributes/email" }, "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "428": { "description": "Precondition Required", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "mfa_required", "detail": "MFA verification required", "status": "428", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "429": { "description": "Too Many Requests", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "rate_limited", "detail": "Too many requests. Please try again later.", "status": "429", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying", "schema": { "type": "integer" } }, "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" } } } }, "500": { "description": "Internal Server 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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "server_error", "detail": "Something went wrong.", "status": "500", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "501": { "description": "Not Implemented", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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_implemented", "detail": "This operation is not available.", "status": "501", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "502": { "description": "Bad Gateway", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "bad_gateway", "detail": "We couldn't complete that request because one of Natural's services returned an unexpected response. Please try again.", "status": "502", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "503": { "description": "Service Unavailable", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "service_unavailable", "detail": "The service is temporarily unavailable.", "status": "503", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } } }, "security": [ { "HTTPBearer": [] } ] } }, "/wallets": { "get": { "operationId": "wallet.list", "summary": "List wallets", "description": "List all wallets for the authenticated party, including wallet type, default flag, balance, and receiving bank name when available.", "tags": [ "Wallets" ], "parameters": [ { "name": "partyId", "in": "query", "schema": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$", "description": "Party ID for delegated wallet lookup" }, "allowEmptyValue": true, "allowReserved": true }, { "name": "X-Agent-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "description": "Agent ID (agt_xxx) identifying which agent is making the request." }, { "name": "X-Instance-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 1024 }, { "type": "null" } ] }, "description": "Required when X-Agent-ID is present. Session or conversation ID for agent observability." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "type": { "description": "Resource type", "type": "string", "enum": [ "wallet" ] }, "id": { "type": "string", "pattern": "^wal_[0-9a-f]{32}$", "description": "Resource ID" }, "attributes": { "type": "object", "properties": { "status": { "enum": [ "active", "frozen", "closed" ], "type": "string", "description": "Wallet readiness status" }, "walletType": { "enum": [ "standard", "vault" ], "type": "string", "description": "Wallet kind: a spendable standard wallet or the vault" }, "isDefault": { "type": "boolean", "description": "Whether this wallet is the party's default for unnamed operations" }, "createdAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "Wallet creation time; null when the upstream read omits it" }, "displayName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Human-readable wallet name, when set" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "User-facing wallet description, when set" }, "balance": { "anyOf": [ { "type": "object", "properties": { "available": { "type": "integer", "description": "Amount currently available to spend or withdraw (cents)" }, "total": { "type": "integer", "description": "Total wallet ledger balance (cents)" }, "currency": { "enum": [ "USD" ], "type": "string", "description": "Currency code" } }, "required": [ "available", "total", "currency" ], "additionalProperties": false, "title": "PublicWalletBalanceAttributes" }, { "type": "null" } ], "description": "Wallet ledger balance; null when the balance read failed transiently" }, "claims": { "type": "object", "properties": { "amount": { "type": "integer", "description": "Total unclaimed product-payment amount (cents)" }, "count": { "type": "integer", "description": "Number of unclaimed product payments" } }, "required": [ "amount", "count" ], "additionalProperties": false, "title": "WalletClaims", "description": "Claimable payment totals" }, "depositInstructions": { "anyOf": [ { "type": "object", "properties": { "bankName": { "type": "string", "description": "Name of the receiving bank" } }, "required": [ "bankName" ], "additionalProperties": false, "title": "PublicDepositInstructionsAttributes" }, { "type": "null" } ], "description": "ACH deposit-instruction metadata for this wallet, when available" } }, "required": [ "status", "walletType", "isDefault", "createdAt", "displayName", "description", "balance", "claims", "depositInstructions" ], "additionalProperties": false, "title": "WalletAttributes", "description": "Resource attributes" }, "relationships": { "type": "object", "properties": { "party": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "description": "Resource type", "type": "string", "enum": [ "party" ] }, "id": { "type": "string" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier" } }, "required": [ "data" ], "additionalProperties": false, "title": "ToOneRelationship", "description": "Party that owns the wallet" } }, "required": [ "party" ], "additionalProperties": false, "title": "WalletRelationships", "description": "Resource relationships" } }, "required": [ "type", "id", "attributes", "relationships" ], "additionalProperties": false, "title": "WalletResource" } }, "meta": { "type": "object", "properties": { "pagination": { "type": "object", "properties": { "hasMore": { "type": "boolean" }, "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "hasMore", "nextCursor" ], "additionalProperties": false, "title": "PaginationMeta" } }, "required": [ "pagination" ], "additionalProperties": false, "title": "WalletListMeta" } }, "required": [ "data", "meta" ], "additionalProperties": false, "title": "WalletListResponse" }, "examples": { "default": { "summary": "Default", "value": { "data": [ { "type": "wallet", "id": "wal_550e8400e29b41d4a716446655440000", "attributes": { "status": "active", "walletType": "standard", "isDefault": true, "createdAt": "2026-01-04T15:30:00Z", "displayName": "Operating", "description": null, "balance": { "available": 120000, "total": 125000, "currency": "USD" }, "claims": { "amount": 125000, "count": 2 }, "depositInstructions": { "bankName": "Bridge Financial" } }, "relationships": { "party": { "data": { "type": "party", "id": "pty_7c9e6679e29b41d4a716446655440001" } } } }, { "type": "wallet", "id": "wal_650e8400e29b41d4a716446655440000", "attributes": { "status": "active", "walletType": "vault", "isDefault": false, "createdAt": "2026-01-04T15:30:00Z", "displayName": "Vault", "description": null, "balance": { "available": 500000, "total": 500000, "currency": "USD" }, "claims": { "amount": 0, "count": 0 }, "depositInstructions": { "bankName": "Bridge Financial" } }, "relationships": { "party": { "data": { "type": "party", "id": "pty_7c9e6679e29b41d4a716446655440001" } } } } ], "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "A request value is invalid.", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "email: Invalid email address", "status": "422", "source": { "pointer": "/data/attributes/email" }, "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "428": { "description": "Precondition Required", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "mfa_required", "detail": "MFA verification required", "status": "428", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "429": { "description": "Too Many Requests", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "rate_limited", "detail": "Too many requests. Please try again later.", "status": "429", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying", "schema": { "type": "integer" } }, "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" } } } }, "500": { "description": "Internal Server 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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "server_error", "detail": "Something went wrong.", "status": "500", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "501": { "description": "Not Implemented", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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_implemented", "detail": "This operation is not available.", "status": "501", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "502": { "description": "Bad Gateway", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "bad_gateway", "detail": "We couldn't complete that request because one of Natural's services returned an unexpected response. Please try again.", "status": "502", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "503": { "description": "Service Unavailable", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "service_unavailable", "detail": "The service is temporarily unavailable.", "status": "503", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } } }, "security": [ { "HTTPBearer": [] } ] } }, "/wallets/{walletId}": { "get": { "operationId": "wallet.get", "summary": "Get wallet", "description": "Get a wallet visible to the authenticated party.", "tags": [ "Wallets" ], "parameters": [ { "name": "walletId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^wal_[0-9a-f]{32}$", "description": "Wallet ID" } }, { "name": "X-Agent-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "description": "Agent ID (agt_xxx) identifying which agent is making the request." }, { "name": "X-Instance-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 1024 }, { "type": "null" } ] }, "description": "Required when X-Agent-ID is present. Session or conversation ID for agent observability." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "description": "Resource type", "type": "string", "enum": [ "wallet" ] }, "id": { "type": "string", "pattern": "^wal_[0-9a-f]{32}$", "description": "Resource ID" }, "attributes": { "type": "object", "properties": { "status": { "enum": [ "active", "frozen", "closed" ], "type": "string", "description": "Wallet readiness status" }, "walletType": { "enum": [ "standard", "vault" ], "type": "string", "description": "Wallet kind: a spendable standard wallet or the vault" }, "isDefault": { "type": "boolean", "description": "Whether this wallet is the party's default for unnamed operations" }, "createdAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "Wallet creation time; null when the upstream read omits it" }, "displayName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Human-readable wallet name, when set" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "User-facing wallet description, when set" }, "balance": { "anyOf": [ { "type": "object", "properties": { "available": { "type": "integer", "description": "Amount currently available to spend or withdraw (cents)" }, "total": { "type": "integer", "description": "Total wallet ledger balance (cents)" }, "currency": { "enum": [ "USD" ], "type": "string", "description": "Currency code" } }, "required": [ "available", "total", "currency" ], "additionalProperties": false, "title": "PublicWalletBalanceAttributes" }, { "type": "null" } ], "description": "Wallet ledger balance; null when the balance read failed transiently" }, "claims": { "type": "object", "properties": { "amount": { "type": "integer", "description": "Total unclaimed product-payment amount (cents)" }, "count": { "type": "integer", "description": "Number of unclaimed product payments" } }, "required": [ "amount", "count" ], "additionalProperties": false, "title": "WalletClaims", "description": "Claimable payment totals" }, "depositInstructions": { "anyOf": [ { "type": "object", "properties": { "bankName": { "type": "string", "description": "Name of the receiving bank" } }, "required": [ "bankName" ], "additionalProperties": false, "title": "PublicDepositInstructionsAttributes" }, { "type": "null" } ], "description": "ACH deposit-instruction metadata for this wallet, when available" } }, "required": [ "status", "walletType", "isDefault", "createdAt", "displayName", "description", "balance", "claims", "depositInstructions" ], "additionalProperties": false, "title": "WalletAttributes", "description": "Resource attributes" }, "relationships": { "type": "object", "properties": { "party": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "description": "Resource type", "type": "string", "enum": [ "party" ] }, "id": { "type": "string" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier" } }, "required": [ "data" ], "additionalProperties": false, "title": "ToOneRelationship", "description": "Party that owns the wallet" } }, "required": [ "party" ], "additionalProperties": false, "title": "WalletRelationships", "description": "Resource relationships" } }, "required": [ "type", "id", "attributes", "relationships" ], "additionalProperties": false, "title": "WalletResource" } }, "required": [ "data" ], "additionalProperties": false, "title": "WalletResponse" }, "examples": { "default": { "summary": "Default", "value": { "data": { "type": "wallet", "id": "wal_550e8400e29b41d4a716446655440000", "attributes": { "status": "active", "walletType": "standard", "isDefault": true, "createdAt": "2026-01-04T15:30:00Z", "displayName": "Operating", "description": null, "balance": { "available": 120000, "total": 125000, "currency": "USD" }, "claims": { "amount": 125000, "count": 2 }, "depositInstructions": { "bankName": "Bridge Financial" } }, "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "A request value is invalid.", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "email: Invalid email address", "status": "422", "source": { "pointer": "/data/attributes/email" }, "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "428": { "description": "Precondition Required", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "mfa_required", "detail": "MFA verification required", "status": "428", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "429": { "description": "Too Many Requests", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "rate_limited", "detail": "Too many requests. Please try again later.", "status": "429", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying", "schema": { "type": "integer" } }, "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" } } } }, "500": { "description": "Internal Server 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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "server_error", "detail": "Something went wrong.", "status": "500", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "501": { "description": "Not Implemented", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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_implemented", "detail": "This operation is not available.", "status": "501", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "502": { "description": "Bad Gateway", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "bad_gateway", "detail": "We couldn't complete that request because one of Natural's services returned an unexpected response. Please try again.", "status": "502", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "503": { "description": "Service Unavailable", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "service_unavailable", "detail": "The service is temporarily unavailable.", "status": "503", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } } }, "security": [ { "HTTPBearer": [] } ] } }, "/external-accounts/processor-token": { "post": { "operationId": "externalAccounts.createFromProcessorToken", "summary": "Create or refresh external account", "description": "Link an external account on behalf of your customer using a Plaid processor token. If the account is already linked, refresh the existing connection and return the same external account with a 201 response.", "tags": [ "External Accounts" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "attributes": { "type": "object", "properties": { "partyId": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$", "description": "Caller-owned end-customer party that will own the linked external account. Must be the caller's own party or a party with an approved delegated relationship carrying external_accounts.create." }, "processorToken": { "type": "string", "minLength": 1, "description": "Plaid processor token minted by the customer's own Plaid integration with /processor/token/create for processor \"natural\". Scoped to exactly one account." }, "institutionName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional institution display name to store with the linked external account." } }, "required": [ "partyId", "processorToken" ], "additionalProperties": false } }, "required": [ "attributes" ], "additionalProperties": false } }, "required": [ "data" ], "additionalProperties": false }, "examples": { "default": { "summary": "Default", "value": { "data": { "attributes": { "partyId": "pty_7c9e6679e29b41d4a716446655440001", "processorToken": "processor-sandbox-abc123", "institutionName": "Chase" } } } } } } } }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "type": { "description": "Resource type.", "type": "string", "enum": [ "externalAccount" ] }, "id": { "type": "string", "pattern": "^eac_[0-9a-f]{32}$", "description": "External account ID." }, "attributes": { "type": "object", "properties": { "lastFour": { "type": "string", "description": "Last four digits of the external bank account." }, "status": { "enum": [ "pending", "new", "active", "disabled", "deleted", "unknown" ], "type": "string", "description": "Lifecycle status of the external account." }, "connectionStatus": { "enum": [ "active", "login_required", "disconnected" ], "type": "string", "description": "Provider connection health for this external account. Poll this value to detect when the underlying provider connection requires attention." }, "createdAt": { "type": "string", "format": "date-time", "description": "Time when the external account was linked." }, "bankName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Bank institution name, when available." }, "accountName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Bank account display name, when available." }, "accountType": { "anyOf": [ { "enum": [ "checking", "savings", "unknown" ], "type": "string" }, { "type": "null" } ], "description": "Bank account type, when available." } }, "required": [ "lastFour", "status", "connectionStatus", "createdAt", "bankName", "accountName", "accountType" ], "additionalProperties": false, "title": "ExternalAccountAttributes", "description": "External account attributes." }, "relationships": { "type": "object", "properties": { "party": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "description": "Resource type", "type": "string", "enum": [ "party" ] }, "id": { "type": "string" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier" } }, "required": [ "data" ], "additionalProperties": false, "title": "ToOneRelationship", "description": "Party that owns the external account." } }, "required": [ "party" ], "additionalProperties": false, "title": "ExternalAccountRelationships", "description": "External account relationships." } }, "required": [ "type", "id", "attributes", "relationships" ], "additionalProperties": false, "title": "ExternalAccountResource" }, "description": "External accounts linked or refreshed by the request." }, "meta": { "type": "object", "properties": { "pagination": { "type": "object", "properties": { "hasMore": { "type": "boolean" }, "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "hasMore", "nextCursor" ], "additionalProperties": false, "title": "PaginationMeta" }, "rejectedAccounts": { "type": "array", "items": { "type": "object", "properties": { "accountId": { "type": "string", "description": "Aggregator account identifier for the rejected account." }, "accountName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Display name of the rejected account." }, "accountMask": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Last-four mask of the rejected account." }, "reason": { "enum": [ "profile_identity_missing", "bank_identity_unavailable", "bank_account_name_mismatch", "bank_account_address_mismatch", "bank_account_ownership_mismatch", "bank_account_verification_failed" ], "type": "string", "description": "Product-safe reason code explaining why the account was not linked." } }, "required": [ "accountId", "accountName", "accountMask", "reason" ], "additionalProperties": false, "title": "ExternalAccountRejectedAccount" }, "description": "Accounts Natural inspected but did not link." } }, "required": [ "pagination", "rejectedAccounts" ], "additionalProperties": false } }, "required": [ "data", "meta" ], "additionalProperties": false, "title": "ExternalAccountListWithRejectedAccountsResponse" }, "examples": { "default": { "summary": "Default", "value": { "data": [ { "type": "externalAccount", "id": "eac_550e8400e29b41d4a716446655440000", "attributes": { "bankName": "Chase", "accountName": "Plaid Checking", "accountType": "checking", "lastFour": "0000", "status": "active", "connectionStatus": "active", "createdAt": "2026-01-04T15:30:00Z" }, "relationships": { "party": { "data": { "type": "party", "id": "pty_7c9e6679e29b41d4a716446655440001" } } } } ], "meta": { "pagination": { "hasMore": false, "nextCursor": null }, "rejectedAccounts": [] } } } } } }, "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "A request value is invalid.", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "email: Invalid email address", "status": "422", "source": { "pointer": "/data/attributes/email" }, "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "428": { "description": "Precondition Required", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "mfa_required", "detail": "MFA verification required", "status": "428", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "429": { "description": "Too Many Requests", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "rate_limited", "detail": "Too many requests. Please try again later.", "status": "429", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying", "schema": { "type": "integer" } }, "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" } } } }, "500": { "description": "Internal Server 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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "server_error", "detail": "Something went wrong.", "status": "500", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "501": { "description": "Not Implemented", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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_implemented", "detail": "This operation is not available.", "status": "501", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "502": { "description": "Bad Gateway", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "bad_gateway", "detail": "We couldn't complete that request because one of Natural's services returned an unexpected response. Please try again.", "status": "502", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "503": { "description": "Service Unavailable", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "service_unavailable", "detail": "The service is temporarily unavailable.", "status": "503", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } } }, "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Unique key for idempotent request handling. If a request with the same key was already processed, the original response is returned." }, { "name": "X-Agent-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "description": "Agent ID (agt_xxx) identifying which agent is making the request." }, { "name": "X-Instance-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 1024 }, { "type": "null" } ] }, "description": "Required when X-Agent-ID is present. Session or conversation ID for agent observability." } ] } }, "/external-accounts": { "get": { "operationId": "externalAccounts.list", "summary": "List external accounts", "description": "List linked external accounts with cursor pagination.", "tags": [ "External Accounts" ], "parameters": [ { "name": "cursor", "in": "query", "schema": { "type": "string" }, "allowEmptyValue": true, "allowReserved": true }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 }, "allowEmptyValue": true, "allowReserved": true }, { "name": "X-Agent-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "description": "Agent ID (agt_xxx) identifying which agent is making the request." }, { "name": "X-Instance-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 1024 }, { "type": "null" } ] }, "description": "Required when X-Agent-ID is present. Session or conversation ID for agent observability." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "type": { "description": "Resource type.", "type": "string", "enum": [ "externalAccount" ] }, "id": { "type": "string", "pattern": "^eac_[0-9a-f]{32}$", "description": "External account ID." }, "attributes": { "type": "object", "properties": { "lastFour": { "type": "string", "description": "Last four digits of the external bank account." }, "status": { "enum": [ "pending", "new", "active", "disabled", "deleted", "unknown" ], "type": "string", "description": "Lifecycle status of the external account." }, "connectionStatus": { "enum": [ "active", "login_required", "disconnected" ], "type": "string", "description": "Provider connection health for this external account. Poll this value to detect when the underlying provider connection requires attention." }, "createdAt": { "type": "string", "format": "date-time", "description": "Time when the external account was linked." }, "bankName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Bank institution name, when available." }, "accountName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Bank account display name, when available." }, "accountType": { "anyOf": [ { "enum": [ "checking", "savings", "unknown" ], "type": "string" }, { "type": "null" } ], "description": "Bank account type, when available." } }, "required": [ "lastFour", "status", "connectionStatus", "createdAt", "bankName", "accountName", "accountType" ], "additionalProperties": false, "title": "ExternalAccountAttributes", "description": "External account attributes." }, "relationships": { "type": "object", "properties": { "party": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "description": "Resource type", "type": "string", "enum": [ "party" ] }, "id": { "type": "string" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier" } }, "required": [ "data" ], "additionalProperties": false, "title": "ToOneRelationship", "description": "Party that owns the external account." } }, "required": [ "party" ], "additionalProperties": false, "title": "ExternalAccountRelationships", "description": "External account relationships." } }, "required": [ "type", "id", "attributes", "relationships" ], "additionalProperties": false, "title": "ExternalAccountResource" } }, "meta": { "type": "object", "properties": { "pagination": { "type": "object", "properties": { "hasMore": { "type": "boolean" }, "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "hasMore", "nextCursor" ], "additionalProperties": false, "title": "PaginationMeta" } }, "required": [ "pagination" ], "additionalProperties": false } }, "required": [ "data", "meta" ], "additionalProperties": false, "title": "ExternalAccountListResponse" }, "examples": { "default": { "summary": "Default", "value": { "data": [ { "type": "externalAccount", "id": "eac_550e8400e29b41d4a716446655440000", "attributes": { "bankName": "Chase", "accountName": "Business Checking", "accountType": "checking", "lastFour": "6789", "status": "active", "connectionStatus": "active", "createdAt": "2026-01-04T15:30:00Z" }, "relationships": { "party": { "data": { "type": "party", "id": "pty_7c9e6679e29b41d4a716446655440001" } } } } ], "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "A request value is invalid.", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "email: Invalid email address", "status": "422", "source": { "pointer": "/data/attributes/email" }, "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "428": { "description": "Precondition Required", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "mfa_required", "detail": "MFA verification required", "status": "428", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "429": { "description": "Too Many Requests", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "rate_limited", "detail": "Too many requests. Please try again later.", "status": "429", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying", "schema": { "type": "integer" } }, "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" } } } }, "500": { "description": "Internal Server 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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "server_error", "detail": "Something went wrong.", "status": "500", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "501": { "description": "Not Implemented", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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_implemented", "detail": "This operation is not available.", "status": "501", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "502": { "description": "Bad Gateway", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "bad_gateway", "detail": "We couldn't complete that request because one of Natural's services returned an unexpected response. Please try again.", "status": "502", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "503": { "description": "Service Unavailable", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "service_unavailable", "detail": "The service is temporarily unavailable.", "status": "503", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } } }, "security": [ { "HTTPBearer": [] } ] } }, "/external-accounts/{externalAccountId}": { "get": { "operationId": "externalAccounts.get", "summary": "Get external account", "description": "Get a linked external account.", "tags": [ "External Accounts" ], "parameters": [ { "name": "externalAccountId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^eac_[0-9a-f]{32}$", "description": "External account ID" } }, { "name": "X-Agent-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "description": "Agent ID (agt_xxx) identifying which agent is making the request." }, { "name": "X-Instance-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 1024 }, { "type": "null" } ] }, "description": "Required when X-Agent-ID is present. Session or conversation ID for agent observability." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "description": "Resource type.", "type": "string", "enum": [ "externalAccount" ] }, "id": { "type": "string", "pattern": "^eac_[0-9a-f]{32}$", "description": "External account ID." }, "attributes": { "type": "object", "properties": { "lastFour": { "type": "string", "description": "Last four digits of the external bank account." }, "status": { "enum": [ "pending", "new", "active", "disabled", "deleted", "unknown" ], "type": "string", "description": "Lifecycle status of the external account." }, "connectionStatus": { "enum": [ "active", "login_required", "disconnected" ], "type": "string", "description": "Provider connection health for this external account. Poll this value to detect when the underlying provider connection requires attention." }, "createdAt": { "type": "string", "format": "date-time", "description": "Time when the external account was linked." }, "bankName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Bank institution name, when available." }, "accountName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Bank account display name, when available." }, "accountType": { "anyOf": [ { "enum": [ "checking", "savings", "unknown" ], "type": "string" }, { "type": "null" } ], "description": "Bank account type, when available." } }, "required": [ "lastFour", "status", "connectionStatus", "createdAt", "bankName", "accountName", "accountType" ], "additionalProperties": false, "title": "ExternalAccountAttributes", "description": "External account attributes." }, "relationships": { "type": "object", "properties": { "party": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "description": "Resource type", "type": "string", "enum": [ "party" ] }, "id": { "type": "string" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier" } }, "required": [ "data" ], "additionalProperties": false, "title": "ToOneRelationship", "description": "Party that owns the external account." } }, "required": [ "party" ], "additionalProperties": false, "title": "ExternalAccountRelationships", "description": "External account relationships." } }, "required": [ "type", "id", "attributes", "relationships" ], "additionalProperties": false, "title": "ExternalAccountResource" } }, "required": [ "data" ], "additionalProperties": false }, "examples": { "default": { "summary": "Default", "value": { "data": { "type": "externalAccount", "id": "eac_550e8400e29b41d4a716446655440000", "attributes": { "bankName": "Chase", "accountName": "Business Checking", "accountType": "checking", "lastFour": "6789", "status": "active", "connectionStatus": "active", "createdAt": "2026-01-04T15:30:00Z" }, "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "A request value is invalid.", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "email: Invalid email address", "status": "422", "source": { "pointer": "/data/attributes/email" }, "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "428": { "description": "Precondition Required", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "mfa_required", "detail": "MFA verification required", "status": "428", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "429": { "description": "Too Many Requests", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "rate_limited", "detail": "Too many requests. Please try again later.", "status": "429", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying", "schema": { "type": "integer" } }, "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" } } } }, "500": { "description": "Internal Server 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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "server_error", "detail": "Something went wrong.", "status": "500", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "501": { "description": "Not Implemented", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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_implemented", "detail": "This operation is not available.", "status": "501", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "502": { "description": "Bad Gateway", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "bad_gateway", "detail": "We couldn't complete that request because one of Natural's services returned an unexpected response. Please try again.", "status": "502", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "503": { "description": "Service Unavailable", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "service_unavailable", "detail": "The service is temporarily unavailable.", "status": "503", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } } }, "security": [ { "HTTPBearer": [] } ] }, "delete": { "operationId": "externalAccounts.remove", "summary": "Remove external account", "description": "Remove (unlink) a bank account.", "tags": [ "External Accounts" ], "parameters": [ { "name": "externalAccountId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^eac_[0-9a-f]{32}$", "description": "External account ID" } }, { "name": "X-Agent-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "description": "Agent ID (agt_xxx) identifying which agent is making the request." }, { "name": "X-Instance-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 1024 }, { "type": "null" } ] }, "description": "Required when X-Agent-ID is present. Session or conversation ID for agent observability." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "description": "Resource type.", "type": "string", "enum": [ "externalAccount" ] }, "id": { "type": "string", "pattern": "^eac_[0-9a-f]{32}$", "description": "External account ID." }, "attributes": { "type": "object", "properties": { "lastFour": { "type": "string", "description": "Last four digits of the external bank account." }, "status": { "enum": [ "pending", "new", "active", "disabled", "deleted", "unknown" ], "type": "string", "description": "Lifecycle status of the external account." }, "connectionStatus": { "enum": [ "active", "login_required", "disconnected" ], "type": "string", "description": "Provider connection health for this external account. Poll this value to detect when the underlying provider connection requires attention." }, "createdAt": { "type": "string", "format": "date-time", "description": "Time when the external account was linked." }, "bankName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Bank institution name, when available." }, "accountName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Bank account display name, when available." }, "accountType": { "anyOf": [ { "enum": [ "checking", "savings", "unknown" ], "type": "string" }, { "type": "null" } ], "description": "Bank account type, when available." } }, "required": [ "lastFour", "status", "connectionStatus", "createdAt", "bankName", "accountName", "accountType" ], "additionalProperties": false, "title": "ExternalAccountAttributes", "description": "External account attributes." }, "relationships": { "type": "object", "properties": { "party": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "description": "Resource type", "type": "string", "enum": [ "party" ] }, "id": { "type": "string" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier" } }, "required": [ "data" ], "additionalProperties": false, "title": "ToOneRelationship", "description": "Party that owns the external account." } }, "required": [ "party" ], "additionalProperties": false, "title": "ExternalAccountRelationships", "description": "External account relationships." } }, "required": [ "type", "id", "attributes", "relationships" ], "additionalProperties": false, "title": "ExternalAccountResource" }, "meta": { "type": "object", "properties": { "deleted": { "const": true, "description": "Indicates the resource was deleted" } }, "required": [ "deleted" ], "additionalProperties": false, "title": "DeletedMeta" } }, "required": [ "data", "meta" ], "additionalProperties": false, "title": "ExternalAccountDeleteResponse" }, "examples": { "default": { "summary": "Default", "value": { "data": { "type": "externalAccount", "id": "eac_550e8400e29b41d4a716446655440000", "attributes": { "bankName": null, "accountName": null, "accountType": null, "lastFour": "", "status": "disabled", "connectionStatus": "active", "createdAt": "0001-01-01T00:00:00.000Z" }, "relationships": { "party": { "data": { "type": "party", "id": "pty_7c9e6679e29b41d4a716446655440001" } } } }, "meta": { "deleted": true } } } } } }, "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "A request value is invalid.", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "email: Invalid email address", "status": "422", "source": { "pointer": "/data/attributes/email" }, "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "428": { "description": "Precondition Required", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "mfa_required", "detail": "MFA verification required", "status": "428", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "429": { "description": "Too Many Requests", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "rate_limited", "detail": "Too many requests. Please try again later.", "status": "429", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying", "schema": { "type": "integer" } }, "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" } } } }, "500": { "description": "Internal Server 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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "server_error", "detail": "Something went wrong.", "status": "500", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "501": { "description": "Not Implemented", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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_implemented", "detail": "This operation is not available.", "status": "501", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "502": { "description": "Bad Gateway", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "bad_gateway", "detail": "We couldn't complete that request because one of Natural's services returned an unexpected response. Please try again.", "status": "502", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "503": { "description": "Service Unavailable", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "service_unavailable", "detail": "The service is temporarily unavailable.", "status": "503", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } } }, "security": [ { "HTTPBearer": [] } ] } }, "/api-keys": { "get": { "operationId": "apiKeys.list", "summary": "List API keys", "description": "Get API keys for the user's party.", "tags": [ "API Keys" ], "parameters": [ { "name": "status", "in": "query", "schema": { "enum": [ "ACTIVE", "REVOKED" ], "type": "string", "description": "Filter by status (ACTIVE or REVOKED)" }, "allowEmptyValue": true, "allowReserved": true }, { "name": "cursor", "in": "query", "schema": { "type": "string", "description": "Cursor for pagination" }, "allowEmptyValue": true, "allowReserved": true }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50, "description": "Max items per page" }, "allowEmptyValue": true, "allowReserved": true }, { "name": "X-Agent-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "description": "Agent ID (agt_xxx) identifying which agent is making the request." }, { "name": "X-Instance-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 1024 }, { "type": "null" } ] }, "description": "Required when X-Agent-ID is present. Session or conversation ID for agent observability." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "type": { "description": "Resource type", "type": "string", "enum": [ "apiKey" ] }, "id": { "type": "string", "description": "Resource ID" }, "attributes": { "type": "object", "properties": { "apiKeyPrefix": { "type": "string", "description": "Non-secret prefix of the API key, e.g. `sk_ntl_live_abc123`. The final segment is random." }, "name": { "type": "string", "description": "Human-readable name" }, "scopes": { "type": "array", "items": { "type": "string" }, "description": "Authorized scopes" }, "environment": { "enum": [ "sandbox", "prod" ], "type": "string", "description": "Environment" }, "status": { "enum": [ "ACTIVE", "REVOKED" ], "type": "string", "description": "Status (ACTIVE or REVOKED)" }, "createdAt": { "type": "string", "format": "date-time", "description": "When this key was created" }, "lastUsedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "When this key was last used" }, "revokedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "When this key was revoked" }, "createdBy": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "User who created this key (usr_*)" }, "revokedBy": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "User who revoked this key (usr_*)" } }, "required": [ "apiKeyPrefix", "name", "scopes", "environment", "status", "createdAt", "lastUsedAt", "revokedAt", "createdBy", "revokedBy" ], "additionalProperties": false, "title": "ApiKeyAttributes", "description": "Resource attributes" }, "relationships": { "type": "object", "properties": { "party": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "description": "Resource type", "type": "string", "enum": [ "party" ] }, "id": { "type": "string" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier" } }, "required": [ "data" ], "additionalProperties": false, "title": "ToOneRelationship", "description": "Party that owns the API key" } }, "required": [ "party" ], "additionalProperties": false, "title": "ApiKeyRelationships", "description": "Resource relationships" } }, "required": [ "type", "id", "attributes", "relationships" ], "additionalProperties": false, "title": "ApiKeyResource" } }, "meta": { "type": "object", "properties": { "pagination": { "type": "object", "properties": { "hasMore": { "type": "boolean" }, "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "hasMore", "nextCursor" ], "additionalProperties": false, "title": "PaginationMeta" } }, "required": [ "pagination" ], "additionalProperties": false } }, "required": [ "data", "meta" ], "additionalProperties": false, "title": "ApiKeyListResponse" }, "examples": { "default": { "summary": "Default", "value": { "data": [ { "type": "apiKey", "id": "apy_550e8400e29b41d4a716446655440000", "attributes": { "apiKeyPrefix": "sk_ntl_prod_sxHp_FRoRTnDEmEH", "name": "Production Backend", "scopes": [ "payments.read", "payments.create" ], "environment": "prod", "status": "ACTIVE", "createdAt": "2026-01-04T15:30:00Z", "lastUsedAt": null, "revokedAt": null, "createdBy": "usr_550e8400e29b41d4a716446655440000", "revokedBy": null }, "relationships": { "party": { "data": { "type": "party", "id": "pty_7c9e6679e29b41d4a716446655440001" } } } }, { "type": "apiKey", "id": "apy_7f8e4d0012a64ef3bca4d21e44a5c001", "attributes": { "apiKeyPrefix": "sk_ntl_prod_Ab12Cd34Ef56Gh78", "name": "Reporting (read-only)", "scopes": [ "payments.read" ], "environment": "prod", "status": "ACTIVE", "createdAt": "2026-01-04T15:30:00Z", "lastUsedAt": null, "revokedAt": null, "createdBy": "usr_550e8400e29b41d4a716446655440000", "revokedBy": null }, "relationships": { "party": { "data": { "type": "party", "id": "pty_7c9e6679e29b41d4a716446655440001" } } } } ], "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "A request value is invalid.", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "email: Invalid email address", "status": "422", "source": { "pointer": "/data/attributes/email" }, "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "428": { "description": "Precondition Required", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "mfa_required", "detail": "MFA verification required", "status": "428", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "429": { "description": "Too Many Requests", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "rate_limited", "detail": "Too many requests. Please try again later.", "status": "429", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying", "schema": { "type": "integer" } }, "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" } } } }, "500": { "description": "Internal Server 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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "server_error", "detail": "Something went wrong.", "status": "500", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "501": { "description": "Not Implemented", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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_implemented", "detail": "This operation is not available.", "status": "501", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "502": { "description": "Bad Gateway", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "bad_gateway", "detail": "We couldn't complete that request because one of Natural's services returned an unexpected response. Please try again.", "status": "502", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "503": { "description": "Service Unavailable", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "service_unavailable", "detail": "The service is temporarily unavailable.", "status": "503", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } } }, "security": [ { "HTTPBearer": [] } ] }, "post": { "operationId": "apiKeys.create", "summary": "Create API key", "description": "Create a new API key. The full secret is returned only once.", "tags": [ "API Keys" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "attributes": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100, "description": "Human-readable name for the key" }, "scopes": { "type": "array", "minItems": 1, "items": { "enum": [ "party.read", "party.update", "invite.read", "invite.create", "invite.update", "invite.delete", "membership.create", "membership.read", "membership.update", "membership.delete", "payments.create", "payments.read", "external_accounts.create", "wallets.read", "wallets.create", "wallets.update", "wallets.delete", "wallets.fund", "wallets.withdraw", "delegations.read", "delegations.create", "delegations.update", "delegations.delete", "api_keys.read", "api_keys.create", "api_keys.delete", "agents.read", "agents.create", "agents.update", "agents.delete", "disputes.read", "disputes.create" ], "type": "string" }, "default": [ "party.read", "party.update", "invite.read", "invite.create", "invite.update", "invite.delete", "membership.create", "membership.read", "membership.update", "membership.delete", "payments.create", "payments.read", "external_accounts.create", "wallets.read", "wallets.create", "wallets.update", "wallets.delete", "wallets.fund", "wallets.withdraw", "delegations.read", "delegations.create", "delegations.update", "delegations.delete", "api_keys.read", "api_keys.create", "api_keys.delete", "agents.read", "agents.create", "agents.update", "agents.delete", "disputes.read", "disputes.create" ], "description": "Permission scopes for the API key. Defaults to all scopes if omitted." } }, "required": [ "name" ], "additionalProperties": false, "title": "ApiKeyCreateAttributes" } }, "required": [ "attributes" ], "additionalProperties": false, "title": "ApiKeyCreateData" } }, "required": [ "data" ], "additionalProperties": false, "title": "CreateApiKeyInput" }, "examples": { "default": { "summary": "Default", "value": { "data": { "attributes": { "name": "Production Backend", "scopes": [ "payments.read", "payments.create" ] } } } } } } } }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "description": "Resource type", "type": "string", "enum": [ "apiKey" ] }, "id": { "type": "string", "description": "Resource ID" }, "attributes": { "type": "object", "properties": { "apiKeyPrefix": { "type": "string", "description": "Non-secret prefix of the API key, e.g. `sk_ntl_live_abc123`. The final segment is random." }, "name": { "type": "string", "description": "Human-readable name" }, "scopes": { "type": "array", "items": { "type": "string" }, "description": "Authorized scopes" }, "environment": { "enum": [ "sandbox", "prod" ], "type": "string", "description": "Environment" }, "status": { "enum": [ "ACTIVE", "REVOKED" ], "type": "string", "description": "Status (ACTIVE or REVOKED)" }, "createdAt": { "type": "string", "format": "date-time", "description": "When this key was created" }, "lastUsedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "When this key was last used" }, "revokedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "When this key was revoked" }, "createdBy": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "User who created this key (usr_*)" }, "revokedBy": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "User who revoked this key (usr_*)" }, "apiKey": { "type": "string", "description": "Full API key secret (shown only once - store securely!)" } }, "required": [ "apiKeyPrefix", "name", "scopes", "environment", "status", "createdAt", "lastUsedAt", "revokedAt", "createdBy", "revokedBy", "apiKey" ], "additionalProperties": false, "title": "ApiKeyCreateResultAttributes", "description": "Resource attributes" }, "relationships": { "type": "object", "properties": { "party": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "description": "Resource type", "type": "string", "enum": [ "party" ] }, "id": { "type": "string" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier" } }, "required": [ "data" ], "additionalProperties": false, "title": "ToOneRelationship", "description": "Party that owns the API key" } }, "required": [ "party" ], "additionalProperties": false, "title": "ApiKeyRelationships", "description": "Resource relationships" } }, "required": [ "type", "id", "attributes", "relationships" ], "additionalProperties": false, "title": "ApiKeyCreateResource" } }, "required": [ "data" ], "additionalProperties": false, "title": "ApiKeyCreateSingleResponse" }, "examples": { "default": { "summary": "Default", "value": { "data": { "type": "apiKey", "id": "apy_550e8400e29b41d4a716446655440000", "attributes": { "apiKeyPrefix": "sk_ntl_prod_sxHp_FRoRTnDEmEH", "name": "Production Backend", "scopes": [ "payments.read", "payments.create" ], "environment": "prod", "status": "ACTIVE", "createdAt": "2026-01-04T15:30:00Z", "lastUsedAt": null, "revokedAt": null, "createdBy": "usr_550e8400e29b41d4a716446655440000", "revokedBy": null, "apiKey": "sk_ntl_prod_sxHp_FRoRTnDEmEHD8FKVJg7P0d3UJMSWCtzQe9GBxk" }, "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "A request value is invalid.", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "email: Invalid email address", "status": "422", "source": { "pointer": "/data/attributes/email" }, "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "428": { "description": "Precondition Required", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "mfa_required", "detail": "MFA verification required", "status": "428", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "429": { "description": "Too Many Requests", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "rate_limited", "detail": "Too many requests. Please try again later.", "status": "429", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying", "schema": { "type": "integer" } }, "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" } } } }, "500": { "description": "Internal Server 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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "server_error", "detail": "Something went wrong.", "status": "500", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "501": { "description": "Not Implemented", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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_implemented", "detail": "This operation is not available.", "status": "501", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "502": { "description": "Bad Gateway", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "bad_gateway", "detail": "We couldn't complete that request because one of Natural's services returned an unexpected response. Please try again.", "status": "502", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "503": { "description": "Service Unavailable", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "service_unavailable", "detail": "The service is temporarily unavailable.", "status": "503", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } } }, "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "X-Agent-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "description": "Agent ID (agt_xxx) identifying which agent is making the request." }, { "name": "X-Instance-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 1024 }, { "type": "null" } ] }, "description": "Required when X-Agent-ID is present. Session or conversation ID for agent observability." } ] } }, "/api-keys/{keyId}": { "get": { "operationId": "apiKeys.get", "summary": "Get API key", "description": "Get details of a specific API key.", "tags": [ "API Keys" ], "parameters": [ { "name": "keyId", "in": "path", "required": true, "schema": { "type": "string", "description": "API key ID (key_xxx)" } }, { "name": "X-Agent-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "description": "Agent ID (agt_xxx) identifying which agent is making the request." }, { "name": "X-Instance-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 1024 }, { "type": "null" } ] }, "description": "Required when X-Agent-ID is present. Session or conversation ID for agent observability." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "description": "Resource type", "type": "string", "enum": [ "apiKey" ] }, "id": { "type": "string", "description": "Resource ID" }, "attributes": { "type": "object", "properties": { "apiKeyPrefix": { "type": "string", "description": "Non-secret prefix of the API key, e.g. `sk_ntl_live_abc123`. The final segment is random." }, "name": { "type": "string", "description": "Human-readable name" }, "scopes": { "type": "array", "items": { "type": "string" }, "description": "Authorized scopes" }, "environment": { "enum": [ "sandbox", "prod" ], "type": "string", "description": "Environment" }, "status": { "enum": [ "ACTIVE", "REVOKED" ], "type": "string", "description": "Status (ACTIVE or REVOKED)" }, "createdAt": { "type": "string", "format": "date-time", "description": "When this key was created" }, "lastUsedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "When this key was last used" }, "revokedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "When this key was revoked" }, "createdBy": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "User who created this key (usr_*)" }, "revokedBy": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "User who revoked this key (usr_*)" } }, "required": [ "apiKeyPrefix", "name", "scopes", "environment", "status", "createdAt", "lastUsedAt", "revokedAt", "createdBy", "revokedBy" ], "additionalProperties": false, "title": "ApiKeyAttributes", "description": "Resource attributes" }, "relationships": { "type": "object", "properties": { "party": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "description": "Resource type", "type": "string", "enum": [ "party" ] }, "id": { "type": "string" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier" } }, "required": [ "data" ], "additionalProperties": false, "title": "ToOneRelationship", "description": "Party that owns the API key" } }, "required": [ "party" ], "additionalProperties": false, "title": "ApiKeyRelationships", "description": "Resource relationships" } }, "required": [ "type", "id", "attributes", "relationships" ], "additionalProperties": false, "title": "ApiKeyResource" } }, "required": [ "data" ], "additionalProperties": false, "title": "ApiKeySingleResponse" }, "examples": { "default": { "summary": "Default", "value": { "data": { "type": "apiKey", "id": "apy_550e8400e29b41d4a716446655440000", "attributes": { "apiKeyPrefix": "sk_ntl_prod_sxHp_FRoRTnDEmEH", "name": "Production Backend", "scopes": [ "payments.read", "payments.create" ], "environment": "prod", "status": "ACTIVE", "createdAt": "2026-01-04T15:30:00Z", "lastUsedAt": null, "revokedAt": null, "createdBy": "usr_550e8400e29b41d4a716446655440000", "revokedBy": 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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "A request value is invalid.", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "email: Invalid email address", "status": "422", "source": { "pointer": "/data/attributes/email" }, "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "428": { "description": "Precondition Required", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "mfa_required", "detail": "MFA verification required", "status": "428", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "429": { "description": "Too Many Requests", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "rate_limited", "detail": "Too many requests. Please try again later.", "status": "429", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying", "schema": { "type": "integer" } }, "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" } } } }, "500": { "description": "Internal Server 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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "server_error", "detail": "Something went wrong.", "status": "500", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "501": { "description": "Not Implemented", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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_implemented", "detail": "This operation is not available.", "status": "501", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "502": { "description": "Bad Gateway", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "bad_gateway", "detail": "We couldn't complete that request because one of Natural's services returned an unexpected response. Please try again.", "status": "502", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "503": { "description": "Service Unavailable", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "service_unavailable", "detail": "The service is temporarily unavailable.", "status": "503", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } } }, "security": [ { "HTTPBearer": [] } ] }, "delete": { "operationId": "apiKeys.revoke", "summary": "Revoke API key", "description": "Revoke an API key so it can no longer be used for authentication.", "tags": [ "API Keys" ], "parameters": [ { "name": "keyId", "in": "path", "required": true, "schema": { "type": "string", "description": "API key ID (key_xxx)" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Unique key for idempotent request handling. If a request with the same key was already processed, the original response is returned." }, { "name": "X-Agent-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "description": "Agent ID (agt_xxx) identifying which agent is making the request." }, { "name": "X-Instance-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 1024 }, { "type": "null" } ] }, "description": "Required when X-Agent-ID is present. Session or conversation ID for agent observability." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "description": "Resource type", "type": "string", "enum": [ "apiKey" ] }, "id": { "type": "string", "description": "Resource ID" }, "attributes": { "type": "object", "properties": { "apiKeyPrefix": { "type": "string", "description": "Non-secret prefix of the API key, e.g. `sk_ntl_live_abc123`. The final segment is random." }, "name": { "type": "string", "description": "Human-readable name" }, "scopes": { "type": "array", "items": { "type": "string" }, "description": "Authorized scopes" }, "environment": { "enum": [ "sandbox", "prod" ], "type": "string", "description": "Environment" }, "status": { "enum": [ "ACTIVE", "REVOKED" ], "type": "string", "description": "Status (ACTIVE or REVOKED)" }, "createdAt": { "type": "string", "format": "date-time", "description": "When this key was created" }, "lastUsedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "When this key was last used" }, "revokedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "When this key was revoked" }, "createdBy": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "User who created this key (usr_*)" }, "revokedBy": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "User who revoked this key (usr_*)" } }, "required": [ "apiKeyPrefix", "name", "scopes", "environment", "status", "createdAt", "lastUsedAt", "revokedAt", "createdBy", "revokedBy" ], "additionalProperties": false, "title": "ApiKeyAttributes", "description": "Resource attributes" }, "relationships": { "type": "object", "properties": { "party": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "description": "Resource type", "type": "string", "enum": [ "party" ] }, "id": { "type": "string" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier" } }, "required": [ "data" ], "additionalProperties": false, "title": "ToOneRelationship", "description": "Party that owns the API key" } }, "required": [ "party" ], "additionalProperties": false, "title": "ApiKeyRelationships", "description": "Resource relationships" } }, "required": [ "type", "id", "attributes", "relationships" ], "additionalProperties": false, "title": "ApiKeyResource" }, "meta": { "type": "object", "properties": { "deleted": { "const": true, "description": "Indicates the resource was deleted" } }, "required": [ "deleted" ], "additionalProperties": false, "title": "DeletedMeta" } }, "required": [ "data", "meta" ], "additionalProperties": false, "title": "ApiKeyRevokeResponse" }, "examples": { "default": { "summary": "Default", "value": { "data": { "type": "apiKey", "id": "apy_550e8400e29b41d4a716446655440000", "attributes": { "apiKeyPrefix": "sk_ntl_prod_sxHp_FRoRTnDEmEH", "name": "Production Backend", "scopes": [ "payments.read", "payments.create" ], "environment": "prod", "status": "REVOKED", "createdAt": "2026-01-04T15:30:00Z", "lastUsedAt": null, "revokedAt": "2026-01-05T10:00:00Z", "createdBy": "usr_550e8400e29b41d4a716446655440000", "revokedBy": "usr_550e8400e29b41d4a716446655440000" }, "relationships": { "party": { "data": { "type": "party", "id": "pty_7c9e6679e29b41d4a716446655440001" } } } }, "meta": { "deleted": true } } } } } }, "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "A request value is invalid.", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "email: Invalid email address", "status": "422", "source": { "pointer": "/data/attributes/email" }, "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "428": { "description": "Precondition Required", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "mfa_required", "detail": "MFA verification required", "status": "428", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "429": { "description": "Too Many Requests", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "rate_limited", "detail": "Too many requests. Please try again later.", "status": "429", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying", "schema": { "type": "integer" } }, "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" } } } }, "500": { "description": "Internal Server 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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "server_error", "detail": "Something went wrong.", "status": "500", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "501": { "description": "Not Implemented", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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_implemented", "detail": "This operation is not available.", "status": "501", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "502": { "description": "Bad Gateway", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "bad_gateway", "detail": "We couldn't complete that request because one of Natural's services returned an unexpected response. Please try again.", "status": "502", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "503": { "description": "Service Unavailable", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "service_unavailable", "detail": "The service is temporarily unavailable.", "status": "503", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } } }, "security": [ { "HTTPBearer": [] } ] } }, "/agent-keys": { "get": { "operationId": "agentKeys.list", "summary": "List agent keys", "description": "Get agent keys for the user's party, optionally filtered by agent.", "tags": [ "Agent Keys" ], "parameters": [ { "name": "agentId", "in": "query", "schema": { "type": "string", "pattern": "^agt_[0-9a-f]{32}$", "description": "Filter to keys bound to this agent (agt_*)" }, "allowEmptyValue": true, "allowReserved": true }, { "name": "cursor", "in": "query", "schema": { "type": "string", "description": "Cursor for pagination" }, "allowEmptyValue": true, "allowReserved": true }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50, "description": "Max items per page" }, "allowEmptyValue": true, "allowReserved": true }, { "name": "X-Agent-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "description": "Agent ID (agt_xxx) identifying which agent is making the request." }, { "name": "X-Instance-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 1024 }, { "type": "null" } ] }, "description": "Required when X-Agent-ID is present. Session or conversation ID for agent observability." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "type": { "description": "Resource type", "type": "string", "enum": [ "agentKey" ] }, "id": { "type": "string", "description": "Resource ID (agk_*)" }, "attributes": { "type": "object", "properties": { "agentKeyPrefix": { "type": "string", "description": "Non-secret prefix of the agent key, e.g. `ak_ntl_live_abc123`. The final segment is random." }, "status": { "enum": [ "ACTIVE", "REVOKED" ], "type": "string", "description": "Status (ACTIVE or REVOKED)" }, "createdAt": { "type": "string", "format": "date-time", "description": "When this key was created" }, "lastUsedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "When this key was last used" }, "revokedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "When this key was revoked" }, "createdBy": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "User who created this key (usr_*)" }, "revokedBy": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "User who revoked this key (usr_*)" } }, "required": [ "agentKeyPrefix", "status", "createdAt", "lastUsedAt", "revokedAt", "createdBy", "revokedBy" ], "additionalProperties": false, "title": "AgentKeyAttributes", "description": "Resource attributes" }, "relationships": { "type": "object", "properties": { "party": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "description": "Resource type", "type": "string", "enum": [ "party" ] }, "id": { "type": "string" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier" } }, "required": [ "data" ], "additionalProperties": false, "title": "ToOneRelationship", "description": "Party that owns the agent key" }, "agent": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "description": "Resource type", "type": "string", "enum": [ "agent" ] }, "id": { "type": "string" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier" } }, "required": [ "data" ], "additionalProperties": false, "title": "ToOneRelationship", "description": "Agent this key is bound to" } }, "required": [ "party", "agent" ], "additionalProperties": false, "title": "AgentKeyRelationships", "description": "Resource relationships" } }, "required": [ "type", "id", "attributes", "relationships" ], "additionalProperties": false, "title": "AgentKeyResource" } }, "meta": { "type": "object", "properties": { "pagination": { "type": "object", "properties": { "hasMore": { "type": "boolean" }, "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "hasMore", "nextCursor" ], "additionalProperties": false, "title": "PaginationMeta" } }, "required": [ "pagination" ], "additionalProperties": false } }, "required": [ "data", "meta" ], "additionalProperties": false, "title": "AgentKeyListResponse" }, "examples": { "default": { "summary": "Default", "value": { "data": [ { "type": "agentKey", "id": "agk_550e8400e29b41d4a716446655440000", "attributes": { "agentKeyPrefix": "ak_ntl_prod_sxHp_FRoRTnDEmEH", "status": "ACTIVE", "createdAt": "2026-01-04T15:30:00Z", "lastUsedAt": null, "revokedAt": null, "createdBy": "usr_550e8400e29b41d4a716446655440000", "revokedBy": null }, "relationships": { "party": { "data": { "type": "party", "id": "pty_7c9e6679e29b41d4a716446655440001" } }, "agent": { "data": { "type": "agent", "id": "agt_019cd1798d637a4da75dce386343931d" } } } }, { "type": "agentKey", "id": "agk_7f8e4d0012a64ef3bca4d21e44a5c001", "attributes": { "agentKeyPrefix": "ak_ntl_prod_Ab12Cd34Ef56Gh78", "status": "ACTIVE", "createdAt": "2026-01-05T09:00:00Z", "lastUsedAt": null, "revokedAt": null, "createdBy": "usr_550e8400e29b41d4a716446655440000", "revokedBy": null }, "relationships": { "party": { "data": { "type": "party", "id": "pty_7c9e6679e29b41d4a716446655440001" } }, "agent": { "data": { "type": "agent", "id": "agt_019cd1798d637a4da75dce386343931d" } } } } ], "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "A request value is invalid.", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "email: Invalid email address", "status": "422", "source": { "pointer": "/data/attributes/email" }, "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "428": { "description": "Precondition Required", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "mfa_required", "detail": "MFA verification required", "status": "428", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "429": { "description": "Too Many Requests", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "rate_limited", "detail": "Too many requests. Please try again later.", "status": "429", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying", "schema": { "type": "integer" } }, "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" } } } }, "500": { "description": "Internal Server 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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "server_error", "detail": "Something went wrong.", "status": "500", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "501": { "description": "Not Implemented", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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_implemented", "detail": "This operation is not available.", "status": "501", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "502": { "description": "Bad Gateway", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "bad_gateway", "detail": "We couldn't complete that request because one of Natural's services returned an unexpected response. Please try again.", "status": "502", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "503": { "description": "Service Unavailable", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "service_unavailable", "detail": "The service is temporarily unavailable.", "status": "503", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } } }, "security": [ { "HTTPBearer": [] } ] }, "post": { "operationId": "agentKeys.create", "summary": "Create agent key", "description": "Create a new agent key bound to an existing agent. The full secret is returned only once. Creating a replacement key does not revoke existing keys — rotation overlaps until the old key is revoked.", "tags": [ "Agent Keys" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "attributes": { "type": "object", "additionalProperties": false, "title": "AgentKeyCreateAttributes" }, "relationships": { "type": "object", "properties": { "agent": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "description": "Resource type", "type": "string", "enum": [ "agent" ] }, "id": { "type": "string", "pattern": "^agt_[0-9a-f]{32}$" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier" } }, "required": [ "data" ], "additionalProperties": false, "title": "ToOneRelationship", "description": "Existing agent the key is bound to" } }, "required": [ "agent" ], "additionalProperties": false, "title": "AgentKeyCreateRelationships" } }, "required": [ "attributes", "relationships" ], "additionalProperties": false, "title": "AgentKeyCreateData" } }, "required": [ "data" ], "additionalProperties": false, "title": "CreateAgentKeyInput" }, "examples": { "default": { "summary": "Default", "value": { "data": { "attributes": {}, "relationships": { "agent": { "data": { "type": "agent", "id": "agt_019cd1798d637a4da75dce386343931d" } } } } } } } } } }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "description": "Resource type", "type": "string", "enum": [ "agentKey" ] }, "id": { "type": "string", "description": "Resource ID (agk_*)" }, "attributes": { "type": "object", "properties": { "agentKeyPrefix": { "type": "string", "description": "Non-secret prefix of the agent key, e.g. `ak_ntl_live_abc123`. The final segment is random." }, "status": { "enum": [ "ACTIVE", "REVOKED" ], "type": "string", "description": "Status (ACTIVE or REVOKED)" }, "createdAt": { "type": "string", "format": "date-time", "description": "When this key was created" }, "lastUsedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "When this key was last used" }, "revokedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "When this key was revoked" }, "createdBy": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "User who created this key (usr_*)" }, "revokedBy": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "User who revoked this key (usr_*)" }, "agentKey": { "type": "string", "description": "Full agent key secret (shown only once - store securely!)" } }, "required": [ "agentKeyPrefix", "status", "createdAt", "lastUsedAt", "revokedAt", "createdBy", "revokedBy", "agentKey" ], "additionalProperties": false, "title": "AgentKeyCreateResultAttributes", "description": "Resource attributes" }, "relationships": { "type": "object", "properties": { "party": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "description": "Resource type", "type": "string", "enum": [ "party" ] }, "id": { "type": "string" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier" } }, "required": [ "data" ], "additionalProperties": false, "title": "ToOneRelationship", "description": "Party that owns the agent key" }, "agent": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "description": "Resource type", "type": "string", "enum": [ "agent" ] }, "id": { "type": "string" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier" } }, "required": [ "data" ], "additionalProperties": false, "title": "ToOneRelationship", "description": "Agent this key is bound to" } }, "required": [ "party", "agent" ], "additionalProperties": false, "title": "AgentKeyRelationships", "description": "Resource relationships" } }, "required": [ "type", "id", "attributes", "relationships" ], "additionalProperties": false, "title": "AgentKeyCreateResource" } }, "required": [ "data" ], "additionalProperties": false, "title": "AgentKeyCreateSingleResponse" }, "examples": { "default": { "summary": "Default", "value": { "data": { "type": "agentKey", "id": "agk_550e8400e29b41d4a716446655440000", "attributes": { "agentKeyPrefix": "ak_ntl_prod_sxHp_FRoRTnDEmEH", "status": "ACTIVE", "createdAt": "2026-01-04T15:30:00Z", "lastUsedAt": null, "revokedAt": null, "createdBy": "usr_550e8400e29b41d4a716446655440000", "revokedBy": null, "agentKey": "ak_ntl_prod_sxHp_FRoRTnDEmEHD8FKVJg7P0d3UJMSWCtzQe9GBxk" }, "relationships": { "party": { "data": { "type": "party", "id": "pty_7c9e6679e29b41d4a716446655440001" } }, "agent": { "data": { "type": "agent", "id": "agt_019cd1798d637a4da75dce386343931d" } } } } } } } } }, "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "A request value is invalid.", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "email: Invalid email address", "status": "422", "source": { "pointer": "/data/attributes/email" }, "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "428": { "description": "Precondition Required", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "mfa_required", "detail": "MFA verification required", "status": "428", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "429": { "description": "Too Many Requests", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "rate_limited", "detail": "Too many requests. Please try again later.", "status": "429", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying", "schema": { "type": "integer" } }, "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" } } } }, "500": { "description": "Internal Server 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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "server_error", "detail": "Something went wrong.", "status": "500", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "501": { "description": "Not Implemented", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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_implemented", "detail": "This operation is not available.", "status": "501", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "502": { "description": "Bad Gateway", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "bad_gateway", "detail": "We couldn't complete that request because one of Natural's services returned an unexpected response. Please try again.", "status": "502", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "503": { "description": "Service Unavailable", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "service_unavailable", "detail": "The service is temporarily unavailable.", "status": "503", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } } }, "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "X-Agent-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "description": "Agent ID (agt_xxx) identifying which agent is making the request." }, { "name": "X-Instance-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 1024 }, { "type": "null" } ] }, "description": "Required when X-Agent-ID is present. Session or conversation ID for agent observability." } ] } }, "/agent-keys/{keyId}": { "delete": { "operationId": "agentKeys.revoke", "summary": "Revoke agent key", "description": "Revoke an agent key so it can no longer be used for authentication. Other active keys for the same agent keep working.", "tags": [ "Agent Keys" ], "parameters": [ { "name": "keyId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^agk_[0-9a-f]{32}$", "description": "Agent key ID (agk_*)" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Unique key for idempotent request handling. If a request with the same key was already processed, the original response is returned." }, { "name": "X-Agent-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "description": "Agent ID (agt_xxx) identifying which agent is making the request." }, { "name": "X-Instance-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 1024 }, { "type": "null" } ] }, "description": "Required when X-Agent-ID is present. Session or conversation ID for agent observability." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "description": "Resource type", "type": "string", "enum": [ "agentKey" ] }, "id": { "type": "string", "description": "Resource ID (agk_*)" }, "attributes": { "type": "object", "properties": { "agentKeyPrefix": { "type": "string", "description": "Non-secret prefix of the agent key, e.g. `ak_ntl_live_abc123`. The final segment is random." }, "status": { "enum": [ "ACTIVE", "REVOKED" ], "type": "string", "description": "Status (ACTIVE or REVOKED)" }, "createdAt": { "type": "string", "format": "date-time", "description": "When this key was created" }, "lastUsedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "When this key was last used" }, "revokedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "When this key was revoked" }, "createdBy": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "User who created this key (usr_*)" }, "revokedBy": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "User who revoked this key (usr_*)" } }, "required": [ "agentKeyPrefix", "status", "createdAt", "lastUsedAt", "revokedAt", "createdBy", "revokedBy" ], "additionalProperties": false, "title": "AgentKeyAttributes", "description": "Resource attributes" }, "relationships": { "type": "object", "properties": { "party": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "description": "Resource type", "type": "string", "enum": [ "party" ] }, "id": { "type": "string" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier" } }, "required": [ "data" ], "additionalProperties": false, "title": "ToOneRelationship", "description": "Party that owns the agent key" }, "agent": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "description": "Resource type", "type": "string", "enum": [ "agent" ] }, "id": { "type": "string" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier" } }, "required": [ "data" ], "additionalProperties": false, "title": "ToOneRelationship", "description": "Agent this key is bound to" } }, "required": [ "party", "agent" ], "additionalProperties": false, "title": "AgentKeyRelationships", "description": "Resource relationships" } }, "required": [ "type", "id", "attributes", "relationships" ], "additionalProperties": false, "title": "AgentKeyResource" }, "meta": { "type": "object", "properties": { "deleted": { "const": true, "description": "Indicates the resource was deleted" } }, "required": [ "deleted" ], "additionalProperties": false, "title": "DeletedMeta" } }, "required": [ "data", "meta" ], "additionalProperties": false, "title": "AgentKeyRevokeResponse" }, "examples": { "default": { "summary": "Default", "value": { "data": { "type": "agentKey", "id": "agk_550e8400e29b41d4a716446655440000", "attributes": { "agentKeyPrefix": "ak_ntl_prod_sxHp_FRoRTnDEmEH", "status": "REVOKED", "createdAt": "2026-01-04T15:30:00Z", "lastUsedAt": null, "revokedAt": "2026-01-06T10:00:00Z", "createdBy": "usr_550e8400e29b41d4a716446655440000", "revokedBy": "usr_550e8400e29b41d4a716446655440000" }, "relationships": { "party": { "data": { "type": "party", "id": "pty_7c9e6679e29b41d4a716446655440001" } }, "agent": { "data": { "type": "agent", "id": "agt_019cd1798d637a4da75dce386343931d" } } } }, "meta": { "deleted": true } } } } } }, "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "A request value is invalid.", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "email: Invalid email address", "status": "422", "source": { "pointer": "/data/attributes/email" }, "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "428": { "description": "Precondition Required", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "mfa_required", "detail": "MFA verification required", "status": "428", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "429": { "description": "Too Many Requests", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "rate_limited", "detail": "Too many requests. Please try again later.", "status": "429", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying", "schema": { "type": "integer" } }, "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" } } } }, "500": { "description": "Internal Server 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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "server_error", "detail": "Something went wrong.", "status": "500", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "501": { "description": "Not Implemented", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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_implemented", "detail": "This operation is not available.", "status": "501", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "502": { "description": "Bad Gateway", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "bad_gateway", "detail": "We couldn't complete that request because one of Natural's services returned an unexpected response. Please try again.", "status": "502", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "503": { "description": "Service Unavailable", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "service_unavailable", "detail": "The service is temporarily unavailable.", "status": "503", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } } }, "security": [ { "HTTPBearer": [] } ] } }, "/webhooks": { "post": { "operationId": "webhooks.create", "summary": "Create webhook", "description": "Create a new webhook endpoint. The signing secret is returned only once.", "tags": [ "Webhooks" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "attributes": { "type": "object", "properties": { "url": { "type": "string", "format": "uri", "description": "Webhook endpoint URL" }, "description": { "type": "string", "maxLength": 500, "description": "Human-readable description" }, "enabledEvents": { "type": "array", "minItems": 1, "items": { "enum": [ "*", "party.updated", "compliance_case.updated", "wallet.created", "external_account.connected", "agent_delegation_invitation.created", "agent_delegation_invitation.accepted", "agent_delegation_invitation.declined", "agent_delegation_invitation.canceled", "agent_delegation.revoked", "delegation.activated", "delegation.revoked", "deposit.created", "deposit.completed", "deposit.failed", "deposit.returned", "deposit.canceled", "deposit.approval_denied", "withdrawal.created", "withdrawal.completed", "withdrawal.failed", "withdrawal.returned", "withdrawal.canceled", "withdrawal.approval_denied", "payment.created", "payment.completed", "payment.failed", "payment.returned", "payment.canceled", "payment.approval_denied", "approval.required", "approval.approved", "approval.denied", "approval.canceled", "payment_request.created", "payment_request.completed", "payment_request.canceled", "payment_request.declined", "payment_request.incoming" ], "type": "string" }, "description": "Event types to subscribe to" }, "tags": { "type": "object", "propertyNames": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[a-zA-Z0-9_]+$" }, "additionalProperties": { "type": "string", "minLength": 1, "maxLength": 256 }, "description": "Custom metadata tags (max 30 keys; keys 1-128 characters, alphanumeric and underscores; values 1-256 characters). Visible to any party authorized to read the resource; do not store sensitive data." } }, "required": [ "url", "enabledEvents" ], "additionalProperties": false, "title": "WebhookCreateAttributes" } }, "required": [ "attributes" ], "additionalProperties": false, "title": "WebhookCreateData" } }, "required": [ "data" ], "additionalProperties": false, "title": "CreateWebhookInput" }, "examples": { "default": { "summary": "Default", "value": { "data": { "attributes": { "url": "https://example.com/webhooks/natural", "description": "Production webhook for wallet and party events", "enabledEvents": [ "wallet.created", "party.updated", "delegation.activated" ], "tags": { "env": "prod", "team": "payments" } } } } } } } } }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "description": "Resource type", "type": "string", "enum": [ "webhook" ] }, "id": { "type": "string", "description": "Resource ID (whk_xxx)" }, "attributes": { "type": "object", "properties": { "url": { "type": "string", "format": "uri", "description": "Webhook endpoint URL" }, "description": { "type": "string", "description": "Human-readable description" }, "status": { "enum": [ "ENABLED", "DISABLED" ], "type": "string", "description": "Webhook status" }, "enabledEvents": { "type": "array", "items": { "enum": [ "*", "party.updated", "compliance_case.updated", "wallet.created", "external_account.connected", "agent_delegation_invitation.created", "agent_delegation_invitation.accepted", "agent_delegation_invitation.declined", "agent_delegation_invitation.canceled", "agent_delegation.revoked", "delegation.activated", "delegation.revoked", "deposit.created", "deposit.completed", "deposit.failed", "deposit.returned", "deposit.canceled", "deposit.approval_denied", "withdrawal.created", "withdrawal.completed", "withdrawal.failed", "withdrawal.returned", "withdrawal.canceled", "withdrawal.approval_denied", "payment.created", "payment.completed", "payment.failed", "payment.returned", "payment.canceled", "payment.approval_denied", "approval.required", "approval.approved", "approval.denied", "approval.canceled", "payment_request.created", "payment_request.completed", "payment_request.canceled", "payment_request.declined", "payment_request.incoming" ], "type": "string" }, "description": "Event types this webhook listens to" }, "tags": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" }, "description": "Custom metadata tags. Visible to any party authorized to read the resource." }, "createdAt": { "type": "string", "format": "date-time", "description": "Creation timestamp (ISO 8601)" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Last update timestamp (ISO 8601)" }, "signingSecret": { "type": "string", "description": "Webhook signing secret (shown only once — store securely!)" } }, "required": [ "url", "description", "status", "enabledEvents", "tags", "createdAt", "updatedAt", "signingSecret" ], "additionalProperties": false, "title": "WebhookCreateResultAttributes", "description": "Resource attributes" }, "relationships": { "type": "object", "properties": { "party": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "description": "Resource type", "type": "string", "enum": [ "party" ] }, "id": { "type": "string" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier" } }, "required": [ "data" ], "additionalProperties": false, "title": "ToOneRelationship", "description": "Party that owns the webhook" } }, "required": [ "party" ], "additionalProperties": false, "title": "WebhookRelationships", "description": "Resource relationships" } }, "required": [ "type", "id", "attributes", "relationships" ], "additionalProperties": false, "title": "WebhookCreateResource" } }, "required": [ "data" ], "additionalProperties": false, "title": "WebhookCreateSingleResponse" }, "examples": { "default": { "summary": "Default", "value": { "data": { "type": "webhook", "id": "whk_0192abc1def2789034567890abcdef12", "attributes": { "url": "https://example.com/webhooks/natural", "description": "Production webhook for wallet and party events", "status": "ENABLED", "enabledEvents": [ "wallet.created", "party.updated", "delegation.activated" ], "tags": { "env": "prod", "team": "payments" }, "createdAt": "2026-03-16T12:00:00Z", "updatedAt": "2026-03-16T12:00:00Z", "signingSecret": "whsec_3JZ8aQpL2vR7nXdE5fW1cT0yK6mB4hG9" }, "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "A request value is invalid.", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "email: Invalid email address", "status": "422", "source": { "pointer": "/data/attributes/email" }, "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "428": { "description": "Precondition Required", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "mfa_required", "detail": "MFA verification required", "status": "428", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "429": { "description": "Too Many Requests", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "rate_limited", "detail": "Too many requests. Please try again later.", "status": "429", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying", "schema": { "type": "integer" } }, "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" } } } }, "500": { "description": "Internal Server 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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "server_error", "detail": "Something went wrong.", "status": "500", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "501": { "description": "Not Implemented", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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_implemented", "detail": "This operation is not available.", "status": "501", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "502": { "description": "Bad Gateway", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "bad_gateway", "detail": "We couldn't complete that request because one of Natural's services returned an unexpected response. Please try again.", "status": "502", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "503": { "description": "Service Unavailable", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "service_unavailable", "detail": "The service is temporarily unavailable.", "status": "503", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } } }, "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Unique key for idempotent request handling. If a request with the same key was already processed, the original response is returned." }, { "name": "X-Agent-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "description": "Agent ID (agt_xxx) identifying which agent is making the request." }, { "name": "X-Instance-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 1024 }, { "type": "null" } ] }, "description": "Required when X-Agent-ID is present. Session or conversation ID for agent observability." } ] }, "get": { "operationId": "webhooks.list", "summary": "List webhooks", "description": "List webhook endpoints for the authenticated party.", "tags": [ "Webhooks" ], "parameters": [ { "name": "status", "in": "query", "schema": { "enum": [ "ENABLED", "DISABLED" ], "type": "string", "description": "Filter by status" }, "allowEmptyValue": true, "allowReserved": true }, { "name": "cursor", "in": "query", "schema": { "type": "string", "description": "Cursor for keyset pagination" }, "allowEmptyValue": true, "allowReserved": true }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50, "description": "Max items per page (1-100)" }, "allowEmptyValue": true, "allowReserved": true }, { "name": "X-Agent-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "description": "Agent ID (agt_xxx) identifying which agent is making the request." }, { "name": "X-Instance-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 1024 }, { "type": "null" } ] }, "description": "Required when X-Agent-ID is present. Session or conversation ID for agent observability." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "type": { "description": "Resource type", "type": "string", "enum": [ "webhook" ] }, "id": { "type": "string", "description": "Resource ID (whk_xxx)" }, "attributes": { "type": "object", "properties": { "url": { "type": "string", "format": "uri", "description": "Webhook endpoint URL" }, "description": { "type": "string", "description": "Human-readable description" }, "status": { "enum": [ "ENABLED", "DISABLED" ], "type": "string", "description": "Webhook status" }, "enabledEvents": { "type": "array", "items": { "enum": [ "*", "party.updated", "compliance_case.updated", "wallet.created", "external_account.connected", "agent_delegation_invitation.created", "agent_delegation_invitation.accepted", "agent_delegation_invitation.declined", "agent_delegation_invitation.canceled", "agent_delegation.revoked", "delegation.activated", "delegation.revoked", "deposit.created", "deposit.completed", "deposit.failed", "deposit.returned", "deposit.canceled", "deposit.approval_denied", "withdrawal.created", "withdrawal.completed", "withdrawal.failed", "withdrawal.returned", "withdrawal.canceled", "withdrawal.approval_denied", "payment.created", "payment.completed", "payment.failed", "payment.returned", "payment.canceled", "payment.approval_denied", "approval.required", "approval.approved", "approval.denied", "approval.canceled", "payment_request.created", "payment_request.completed", "payment_request.canceled", "payment_request.declined", "payment_request.incoming" ], "type": "string" }, "description": "Event types this webhook listens to" }, "tags": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" }, "description": "Custom metadata tags. Visible to any party authorized to read the resource." }, "createdAt": { "type": "string", "format": "date-time", "description": "Creation timestamp (ISO 8601)" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Last update timestamp (ISO 8601)" } }, "required": [ "url", "description", "status", "enabledEvents", "tags", "createdAt", "updatedAt" ], "additionalProperties": false, "title": "WebhookAttributes", "description": "Resource attributes" }, "relationships": { "type": "object", "properties": { "party": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "description": "Resource type", "type": "string", "enum": [ "party" ] }, "id": { "type": "string" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier" } }, "required": [ "data" ], "additionalProperties": false, "title": "ToOneRelationship", "description": "Party that owns the webhook" } }, "required": [ "party" ], "additionalProperties": false, "title": "WebhookRelationships", "description": "Resource relationships" } }, "required": [ "type", "id", "attributes", "relationships" ], "additionalProperties": false, "title": "WebhookResource" } }, "meta": { "type": "object", "properties": { "pagination": { "type": "object", "properties": { "hasMore": { "type": "boolean" }, "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "hasMore", "nextCursor" ], "additionalProperties": false, "title": "PaginationMeta" } }, "required": [ "pagination" ], "additionalProperties": false } }, "required": [ "data", "meta" ], "additionalProperties": false, "title": "WebhookListResponse" }, "examples": { "default": { "summary": "Default", "value": { "data": [ { "type": "webhook", "id": "whk_0192abc1def2789034567890abcdef12", "attributes": { "url": "https://example.com/webhooks/natural", "description": "Production webhook for wallet and party events", "status": "ENABLED", "enabledEvents": [ "wallet.created", "party.updated", "delegation.activated" ], "tags": { "env": "prod", "team": "payments" }, "createdAt": "2026-03-16T12:00:00Z", "updatedAt": "2026-03-16T12:00:00Z" }, "relationships": { "party": { "data": { "type": "party", "id": "pty_7c9e6679e29b41d4a716446655440001" } } } }, { "type": "webhook", "id": "whk_0192def4abc1789034567890abcdef34", "attributes": { "url": "https://example.com/webhooks/funding", "description": "External account notifications", "status": "DISABLED", "enabledEvents": [ "external_account.connected" ], "tags": { "env": "prod" }, "createdAt": "2026-03-10T09:00:00Z", "updatedAt": "2026-03-14T18:30:00Z" }, "relationships": { "party": { "data": { "type": "party", "id": "pty_7c9e6679e29b41d4a716446655440001" } } } } ], "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "A request value is invalid.", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "email: Invalid email address", "status": "422", "source": { "pointer": "/data/attributes/email" }, "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "428": { "description": "Precondition Required", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "mfa_required", "detail": "MFA verification required", "status": "428", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "429": { "description": "Too Many Requests", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "rate_limited", "detail": "Too many requests. Please try again later.", "status": "429", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying", "schema": { "type": "integer" } }, "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" } } } }, "500": { "description": "Internal Server 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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "server_error", "detail": "Something went wrong.", "status": "500", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "501": { "description": "Not Implemented", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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_implemented", "detail": "This operation is not available.", "status": "501", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "502": { "description": "Bad Gateway", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "bad_gateway", "detail": "We couldn't complete that request because one of Natural's services returned an unexpected response. Please try again.", "status": "502", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "503": { "description": "Service Unavailable", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "service_unavailable", "detail": "The service is temporarily unavailable.", "status": "503", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } } }, "security": [ { "HTTPBearer": [] } ] } }, "/webhooks/{webhookId}": { "get": { "operationId": "webhooks.get", "summary": "Get webhook", "description": "Get details of a specific webhook endpoint.", "tags": [ "Webhooks" ], "parameters": [ { "name": "webhookId", "in": "path", "required": true, "schema": { "type": "string", "description": "Webhook ID (whk_xxx)" } }, { "name": "X-Agent-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "description": "Agent ID (agt_xxx) identifying which agent is making the request." }, { "name": "X-Instance-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 1024 }, { "type": "null" } ] }, "description": "Required when X-Agent-ID is present. Session or conversation ID for agent observability." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "description": "Resource type", "type": "string", "enum": [ "webhook" ] }, "id": { "type": "string", "description": "Resource ID (whk_xxx)" }, "attributes": { "type": "object", "properties": { "url": { "type": "string", "format": "uri", "description": "Webhook endpoint URL" }, "description": { "type": "string", "description": "Human-readable description" }, "status": { "enum": [ "ENABLED", "DISABLED" ], "type": "string", "description": "Webhook status" }, "enabledEvents": { "type": "array", "items": { "enum": [ "*", "party.updated", "compliance_case.updated", "wallet.created", "external_account.connected", "agent_delegation_invitation.created", "agent_delegation_invitation.accepted", "agent_delegation_invitation.declined", "agent_delegation_invitation.canceled", "agent_delegation.revoked", "delegation.activated", "delegation.revoked", "deposit.created", "deposit.completed", "deposit.failed", "deposit.returned", "deposit.canceled", "deposit.approval_denied", "withdrawal.created", "withdrawal.completed", "withdrawal.failed", "withdrawal.returned", "withdrawal.canceled", "withdrawal.approval_denied", "payment.created", "payment.completed", "payment.failed", "payment.returned", "payment.canceled", "payment.approval_denied", "approval.required", "approval.approved", "approval.denied", "approval.canceled", "payment_request.created", "payment_request.completed", "payment_request.canceled", "payment_request.declined", "payment_request.incoming" ], "type": "string" }, "description": "Event types this webhook listens to" }, "tags": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" }, "description": "Custom metadata tags. Visible to any party authorized to read the resource." }, "createdAt": { "type": "string", "format": "date-time", "description": "Creation timestamp (ISO 8601)" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Last update timestamp (ISO 8601)" } }, "required": [ "url", "description", "status", "enabledEvents", "tags", "createdAt", "updatedAt" ], "additionalProperties": false, "title": "WebhookAttributes", "description": "Resource attributes" }, "relationships": { "type": "object", "properties": { "party": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "description": "Resource type", "type": "string", "enum": [ "party" ] }, "id": { "type": "string" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier" } }, "required": [ "data" ], "additionalProperties": false, "title": "ToOneRelationship", "description": "Party that owns the webhook" } }, "required": [ "party" ], "additionalProperties": false, "title": "WebhookRelationships", "description": "Resource relationships" } }, "required": [ "type", "id", "attributes", "relationships" ], "additionalProperties": false, "title": "WebhookResource" } }, "required": [ "data" ], "additionalProperties": false, "title": "WebhookSingleResponse" }, "examples": { "default": { "summary": "Default", "value": { "data": { "type": "webhook", "id": "whk_0192abc1def2789034567890abcdef12", "attributes": { "url": "https://example.com/webhooks/natural", "description": "Production webhook for wallet and party events", "status": "ENABLED", "enabledEvents": [ "wallet.created", "party.updated", "delegation.activated" ], "tags": { "env": "prod", "team": "payments" }, "createdAt": "2026-03-16T12:00:00Z", "updatedAt": "2026-03-16T12:00:00Z" }, "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "A request value is invalid.", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "email: Invalid email address", "status": "422", "source": { "pointer": "/data/attributes/email" }, "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "428": { "description": "Precondition Required", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "mfa_required", "detail": "MFA verification required", "status": "428", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "429": { "description": "Too Many Requests", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "rate_limited", "detail": "Too many requests. Please try again later.", "status": "429", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying", "schema": { "type": "integer" } }, "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" } } } }, "500": { "description": "Internal Server 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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "server_error", "detail": "Something went wrong.", "status": "500", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "501": { "description": "Not Implemented", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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_implemented", "detail": "This operation is not available.", "status": "501", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "502": { "description": "Bad Gateway", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "bad_gateway", "detail": "We couldn't complete that request because one of Natural's services returned an unexpected response. Please try again.", "status": "502", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "503": { "description": "Service Unavailable", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "service_unavailable", "detail": "The service is temporarily unavailable.", "status": "503", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } } }, "security": [ { "HTTPBearer": [] } ] }, "put": { "operationId": "webhooks.update", "summary": "Update webhook", "description": "Partially update a webhook endpoint.", "tags": [ "Webhooks" ], "parameters": [ { "name": "webhookId", "in": "path", "required": true, "schema": { "type": "string", "description": "Webhook ID (whk_xxx)" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Unique key for idempotent request handling. If a request with the same key was already processed, the original response is returned." }, { "name": "X-Agent-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "description": "Agent ID (agt_xxx) identifying which agent is making the request." }, { "name": "X-Instance-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 1024 }, { "type": "null" } ] }, "description": "Required when X-Agent-ID is present. Session or conversation ID for agent observability." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "attributes": { "type": "object", "properties": { "url": { "type": "string", "format": "uri", "description": "New webhook endpoint URL" }, "description": { "type": "string", "maxLength": 500, "description": "New description" }, "status": { "enum": [ "ENABLED", "DISABLED" ], "type": "string", "description": "New status" }, "enabledEvents": { "type": "array", "minItems": 1, "items": { "enum": [ "*", "party.updated", "compliance_case.updated", "wallet.created", "external_account.connected", "agent_delegation_invitation.created", "agent_delegation_invitation.accepted", "agent_delegation_invitation.declined", "agent_delegation_invitation.canceled", "agent_delegation.revoked", "delegation.activated", "delegation.revoked", "deposit.created", "deposit.completed", "deposit.failed", "deposit.returned", "deposit.canceled", "deposit.approval_denied", "withdrawal.created", "withdrawal.completed", "withdrawal.failed", "withdrawal.returned", "withdrawal.canceled", "withdrawal.approval_denied", "payment.created", "payment.completed", "payment.failed", "payment.returned", "payment.canceled", "payment.approval_denied", "approval.required", "approval.approved", "approval.denied", "approval.canceled", "payment_request.created", "payment_request.completed", "payment_request.canceled", "payment_request.declined", "payment_request.incoming" ], "type": "string" }, "description": "Event types to subscribe to" }, "tags": { "type": "object", "propertyNames": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[a-zA-Z0-9_]+$" }, "additionalProperties": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 256 }, { "type": "null" } ] }, "description": "Tag updates (set a key to null to remove it)" } }, "additionalProperties": false, "title": "WebhookUpdateAttributes" } }, "required": [ "attributes" ], "additionalProperties": false, "title": "WebhookUpdateData" } }, "required": [ "data" ], "additionalProperties": false, "title": "UpdateWebhookInput" }, "examples": { "default": { "summary": "Default", "value": { "data": { "attributes": { "description": "Production webhook — wallet, party, and delegation events", "status": "DISABLED", "enabledEvents": [ "wallet.created", "party.updated" ], "tags": { "env": "staging", "team": null } } } } } } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "description": "Resource type", "type": "string", "enum": [ "webhook" ] }, "id": { "type": "string", "description": "Resource ID (whk_xxx)" }, "attributes": { "type": "object", "properties": { "url": { "type": "string", "format": "uri", "description": "Webhook endpoint URL" }, "description": { "type": "string", "description": "Human-readable description" }, "status": { "enum": [ "ENABLED", "DISABLED" ], "type": "string", "description": "Webhook status" }, "enabledEvents": { "type": "array", "items": { "enum": [ "*", "party.updated", "compliance_case.updated", "wallet.created", "external_account.connected", "agent_delegation_invitation.created", "agent_delegation_invitation.accepted", "agent_delegation_invitation.declined", "agent_delegation_invitation.canceled", "agent_delegation.revoked", "delegation.activated", "delegation.revoked", "deposit.created", "deposit.completed", "deposit.failed", "deposit.returned", "deposit.canceled", "deposit.approval_denied", "withdrawal.created", "withdrawal.completed", "withdrawal.failed", "withdrawal.returned", "withdrawal.canceled", "withdrawal.approval_denied", "payment.created", "payment.completed", "payment.failed", "payment.returned", "payment.canceled", "payment.approval_denied", "approval.required", "approval.approved", "approval.denied", "approval.canceled", "payment_request.created", "payment_request.completed", "payment_request.canceled", "payment_request.declined", "payment_request.incoming" ], "type": "string" }, "description": "Event types this webhook listens to" }, "tags": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" }, "description": "Custom metadata tags. Visible to any party authorized to read the resource." }, "createdAt": { "type": "string", "format": "date-time", "description": "Creation timestamp (ISO 8601)" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Last update timestamp (ISO 8601)" } }, "required": [ "url", "description", "status", "enabledEvents", "tags", "createdAt", "updatedAt" ], "additionalProperties": false, "title": "WebhookAttributes", "description": "Resource attributes" }, "relationships": { "type": "object", "properties": { "party": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "description": "Resource type", "type": "string", "enum": [ "party" ] }, "id": { "type": "string" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier" } }, "required": [ "data" ], "additionalProperties": false, "title": "ToOneRelationship", "description": "Party that owns the webhook" } }, "required": [ "party" ], "additionalProperties": false, "title": "WebhookRelationships", "description": "Resource relationships" } }, "required": [ "type", "id", "attributes", "relationships" ], "additionalProperties": false, "title": "WebhookResource" } }, "required": [ "data" ], "additionalProperties": false, "title": "WebhookSingleResponse" }, "examples": { "default": { "summary": "Default", "value": { "data": { "type": "webhook", "id": "whk_0192abc1def2789034567890abcdef12", "attributes": { "url": "https://example.com/webhooks/natural", "description": "Production webhook — wallet, party, and delegation events", "status": "DISABLED", "enabledEvents": [ "wallet.created", "party.updated" ], "tags": { "env": "staging" }, "createdAt": "2026-03-16T12:00:00Z", "updatedAt": "2026-03-17T08:15:00Z" }, "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "A request value is invalid.", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "email: Invalid email address", "status": "422", "source": { "pointer": "/data/attributes/email" }, "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "428": { "description": "Precondition Required", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "mfa_required", "detail": "MFA verification required", "status": "428", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "429": { "description": "Too Many Requests", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "rate_limited", "detail": "Too many requests. Please try again later.", "status": "429", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying", "schema": { "type": "integer" } }, "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" } } } }, "500": { "description": "Internal Server 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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "server_error", "detail": "Something went wrong.", "status": "500", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "501": { "description": "Not Implemented", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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_implemented", "detail": "This operation is not available.", "status": "501", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "502": { "description": "Bad Gateway", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "bad_gateway", "detail": "We couldn't complete that request because one of Natural's services returned an unexpected response. Please try again.", "status": "502", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "503": { "description": "Service Unavailable", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "service_unavailable", "detail": "The service is temporarily unavailable.", "status": "503", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } } }, "security": [ { "HTTPBearer": [] } ] }, "delete": { "operationId": "webhooks.remove", "summary": "Delete webhook", "description": "Soft-delete a webhook endpoint.", "tags": [ "Webhooks" ], "parameters": [ { "name": "webhookId", "in": "path", "required": true, "schema": { "type": "string", "description": "Webhook ID (whk_xxx)" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Unique key for idempotent request handling. If a request with the same key was already processed, the original response is returned." }, { "name": "X-Agent-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "description": "Agent ID (agt_xxx) identifying which agent is making the request." }, { "name": "X-Instance-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 1024 }, { "type": "null" } ] }, "description": "Required when X-Agent-ID is present. Session or conversation ID for agent observability." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "description": "Resource type", "type": "string", "enum": [ "webhook" ] }, "id": { "type": "string", "description": "Resource ID (whk_xxx)" }, "attributes": { "type": "object", "properties": { "url": { "type": "string", "format": "uri", "description": "Webhook endpoint URL" }, "description": { "type": "string", "description": "Human-readable description" }, "status": { "enum": [ "ENABLED", "DISABLED" ], "type": "string", "description": "Webhook status" }, "enabledEvents": { "type": "array", "items": { "enum": [ "*", "party.updated", "compliance_case.updated", "wallet.created", "external_account.connected", "agent_delegation_invitation.created", "agent_delegation_invitation.accepted", "agent_delegation_invitation.declined", "agent_delegation_invitation.canceled", "agent_delegation.revoked", "delegation.activated", "delegation.revoked", "deposit.created", "deposit.completed", "deposit.failed", "deposit.returned", "deposit.canceled", "deposit.approval_denied", "withdrawal.created", "withdrawal.completed", "withdrawal.failed", "withdrawal.returned", "withdrawal.canceled", "withdrawal.approval_denied", "payment.created", "payment.completed", "payment.failed", "payment.returned", "payment.canceled", "payment.approval_denied", "approval.required", "approval.approved", "approval.denied", "approval.canceled", "payment_request.created", "payment_request.completed", "payment_request.canceled", "payment_request.declined", "payment_request.incoming" ], "type": "string" }, "description": "Event types this webhook listens to" }, "tags": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" }, "description": "Custom metadata tags. Visible to any party authorized to read the resource." }, "createdAt": { "type": "string", "format": "date-time", "description": "Creation timestamp (ISO 8601)" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Last update timestamp (ISO 8601)" } }, "required": [ "url", "description", "status", "enabledEvents", "tags", "createdAt", "updatedAt" ], "additionalProperties": false, "title": "WebhookAttributes", "description": "Resource attributes" }, "relationships": { "type": "object", "properties": { "party": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "description": "Resource type", "type": "string", "enum": [ "party" ] }, "id": { "type": "string" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier" } }, "required": [ "data" ], "additionalProperties": false, "title": "ToOneRelationship", "description": "Party that owns the webhook" } }, "required": [ "party" ], "additionalProperties": false, "title": "WebhookRelationships", "description": "Resource relationships" } }, "required": [ "type", "id", "attributes", "relationships" ], "additionalProperties": false, "title": "WebhookResource" }, "meta": { "type": "object", "properties": { "deleted": { "const": true, "description": "Indicates the resource was deleted" } }, "required": [ "deleted" ], "additionalProperties": false, "title": "DeletedMeta" } }, "required": [ "data", "meta" ], "additionalProperties": false, "title": "WebhookDeleteResponse" }, "examples": { "default": { "summary": "Default", "value": { "data": { "type": "webhook", "id": "whk_0192abc1def2789034567890abcdef12", "attributes": { "url": "https://example.com/webhooks/natural", "description": "Production webhook for wallet and party events", "status": "ENABLED", "enabledEvents": [ "wallet.created", "party.updated", "delegation.activated" ], "tags": { "env": "prod", "team": "payments" }, "createdAt": "2026-03-16T12:00:00Z", "updatedAt": "2026-03-16T12:00:00Z" }, "relationships": { "party": { "data": { "type": "party", "id": "pty_7c9e6679e29b41d4a716446655440001" } } } }, "meta": { "deleted": true } } } } } }, "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "A request value is invalid.", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "email: Invalid email address", "status": "422", "source": { "pointer": "/data/attributes/email" }, "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "428": { "description": "Precondition Required", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "mfa_required", "detail": "MFA verification required", "status": "428", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "429": { "description": "Too Many Requests", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "rate_limited", "detail": "Too many requests. Please try again later.", "status": "429", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying", "schema": { "type": "integer" } }, "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" } } } }, "500": { "description": "Internal Server 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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "server_error", "detail": "Something went wrong.", "status": "500", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "501": { "description": "Not Implemented", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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_implemented", "detail": "This operation is not available.", "status": "501", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "502": { "description": "Bad Gateway", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "bad_gateway", "detail": "We couldn't complete that request because one of Natural's services returned an unexpected response. Please try again.", "status": "502", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "503": { "description": "Service Unavailable", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "service_unavailable", "detail": "The service is temporarily unavailable.", "status": "503", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } } }, "security": [ { "HTTPBearer": [] } ] } }, "/webhooks/{webhookId}/rotate-secret": { "post": { "operationId": "webhooks.rotateSecret", "summary": "Rotate webhook signing secret", "description": "Generate a new signing secret. The previous secret remains valid for the specified grace period. Requires Idempotency-Key header.", "tags": [ "Webhooks" ], "parameters": [ { "name": "webhookId", "in": "path", "required": true, "schema": { "type": "string", "description": "Webhook ID (whk_xxx)" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Unique key for idempotent request handling. If a request with the same key was already processed, the original response is returned." }, { "name": "X-Agent-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "description": "Agent ID (agt_xxx) identifying which agent is making the request." }, { "name": "X-Instance-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 1024 }, { "type": "null" } ] }, "description": "Required when X-Agent-ID is present. Session or conversation ID for agent observability." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "attributes": { "type": "object", "properties": { "expiresInSeconds": { "type": "integer", "minimum": 0, "maximum": 86400, "description": "Grace period in seconds for the previous secret (0 = immediate cutover, max 86400)" } }, "required": [ "expiresInSeconds" ], "additionalProperties": false, "title": "RotateSecretAttributes" } }, "required": [ "attributes" ], "additionalProperties": false, "title": "RotateSecretData" } }, "required": [ "data" ], "additionalProperties": false, "title": "RotateSecretInput" }, "examples": { "default": { "summary": "Default", "value": { "data": { "attributes": { "expiresInSeconds": 3600 } } } } } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "description": "Resource type", "type": "string", "enum": [ "webhook" ] }, "id": { "type": "string", "description": "Resource ID (whk_xxx)" }, "attributes": { "type": "object", "properties": { "signingSecret": { "type": "string", "description": "New webhook signing secret (shown only once — store securely!)" }, "previousSecretExpiresAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "When the previous secret expires (null if immediate cutover)" } }, "required": [ "signingSecret", "previousSecretExpiresAt" ], "additionalProperties": false, "title": "RotateSecretResponseAttributes", "description": "Resource attributes" }, "relationships": { "type": "object", "properties": { "party": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "description": "Resource type", "type": "string", "enum": [ "party" ] }, "id": { "type": "string" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier" } }, "required": [ "data" ], "additionalProperties": false, "title": "ToOneRelationship", "description": "Party that owns the webhook" } }, "required": [ "party" ], "additionalProperties": false, "title": "WebhookRelationships", "description": "Resource relationships" } }, "required": [ "type", "id", "attributes", "relationships" ], "additionalProperties": false, "title": "RotateSecretResource" } }, "required": [ "data" ], "additionalProperties": false, "title": "RotateSecretResponse" }, "examples": { "default": { "summary": "Default", "value": { "data": { "type": "webhook", "id": "whk_0192abc1def2789034567890abcdef12", "attributes": { "signingSecret": "whsec_7Yp2KdN9wL4xT8rE1cV5bM0aQ6hJ3fG8", "previousSecretExpiresAt": "2026-03-17T09:15:00Z" }, "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "A request value is invalid.", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "email: Invalid email address", "status": "422", "source": { "pointer": "/data/attributes/email" }, "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "428": { "description": "Precondition Required", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "mfa_required", "detail": "MFA verification required", "status": "428", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "429": { "description": "Too Many Requests", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "rate_limited", "detail": "Too many requests. Please try again later.", "status": "429", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying", "schema": { "type": "integer" } }, "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" } } } }, "500": { "description": "Internal Server 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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "server_error", "detail": "Something went wrong.", "status": "500", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "501": { "description": "Not Implemented", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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_implemented", "detail": "This operation is not available.", "status": "501", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "502": { "description": "Bad Gateway", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "bad_gateway", "detail": "We couldn't complete that request because one of Natural's services returned an unexpected response. Please try again.", "status": "502", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "503": { "description": "Service Unavailable", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "service_unavailable", "detail": "The service is temporarily unavailable.", "status": "503", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } } }, "security": [ { "HTTPBearer": [] } ] } }, "/events": { "get": { "operationId": "events.list", "summary": "List events", "description": "List events for the authenticated party, or for a delegated party if partyId is provided.", "tags": [ "Events" ], "parameters": [ { "name": "partyId", "in": "query", "schema": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$", "description": "Party ID to list events for (defaults to caller's party)" }, "allowEmptyValue": true, "allowReserved": true }, { "name": "eventType", "in": "query", "schema": { "enum": [ "party.updated", "compliance_case.updated", "wallet.created", "external_account.connected", "agent_delegation_invitation.created", "agent_delegation_invitation.accepted", "agent_delegation_invitation.declined", "agent_delegation_invitation.canceled", "agent_delegation.revoked", "delegation.activated", "delegation.revoked", "deposit.created", "deposit.completed", "deposit.failed", "deposit.returned", "deposit.canceled", "deposit.approval_denied", "withdrawal.created", "withdrawal.completed", "withdrawal.failed", "withdrawal.returned", "withdrawal.canceled", "withdrawal.approval_denied", "payment.created", "payment.completed", "payment.failed", "payment.returned", "payment.canceled", "payment.approval_denied", "approval.required", "approval.approved", "approval.denied", "approval.canceled", "payment_request.created", "payment_request.completed", "payment_request.canceled", "payment_request.declined", "payment_request.incoming" ], "type": "string", "description": "Filter by event type" }, "allowEmptyValue": true, "allowReserved": true }, { "name": "createdAfter", "in": "query", "schema": { "type": "string", "format": "date-time", "description": "Return events created after this timestamp (ISO 8601)" }, "allowEmptyValue": true, "allowReserved": true }, { "name": "createdBefore", "in": "query", "schema": { "type": "string", "format": "date-time", "description": "Return events created before this timestamp (ISO 8601)" }, "allowEmptyValue": true, "allowReserved": true }, { "name": "cursor", "in": "query", "schema": { "type": "string", "description": "Cursor for keyset pagination" }, "allowEmptyValue": true, "allowReserved": true }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50, "description": "Max items per page (1-100)" }, "allowEmptyValue": true, "allowReserved": true }, { "name": "X-Agent-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "description": "Agent ID (agt_xxx) identifying which agent is making the request." }, { "name": "X-Instance-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 1024 }, { "type": "null" } ] }, "description": "Required when X-Agent-ID is present. Session or conversation ID for agent observability." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "type": { "description": "Resource type", "type": "string", "enum": [ "event" ] }, "id": { "type": "string", "description": "Resource ID (evt_xxx)" }, "attributes": { "type": "object", "properties": { "eventType": { "enum": [ "party.updated", "compliance_case.updated", "wallet.created", "external_account.connected", "agent_delegation_invitation.created", "agent_delegation_invitation.accepted", "agent_delegation_invitation.declined", "agent_delegation_invitation.canceled", "agent_delegation.revoked", "delegation.activated", "delegation.revoked", "deposit.created", "deposit.completed", "deposit.failed", "deposit.returned", "deposit.canceled", "deposit.approval_denied", "withdrawal.created", "withdrawal.completed", "withdrawal.failed", "withdrawal.returned", "withdrawal.canceled", "withdrawal.approval_denied", "payment.created", "payment.completed", "payment.failed", "payment.returned", "payment.canceled", "payment.approval_denied", "approval.required", "approval.approved", "approval.denied", "approval.canceled", "payment_request.created", "payment_request.completed", "payment_request.canceled", "payment_request.declined", "payment_request.incoming" ], "type": "string", "description": "Type of event" }, "resourceId": { "type": "string", "description": "ID of the resource that triggered the event" }, "resourceType": { "type": "string", "description": "Type of the resource (e.g. wallet, payment)" }, "payload": { "type": "object", "properties": { "object": { "description": "Point-in-time resource snapshot" } }, "additionalProperties": {}, "description": "Event payload containing the resource snapshot. Additional keys may be added in the future." }, "createdAt": { "type": "string", "format": "date-time", "description": "Creation timestamp (ISO 8601)" } }, "required": [ "eventType", "resourceId", "resourceType", "payload", "createdAt" ], "additionalProperties": false, "title": "EventAttributes", "description": "Resource attributes" }, "relationships": { "type": "object", "properties": { "party": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "description": "Resource type", "type": "string", "enum": [ "party" ] }, "id": { "type": "string" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier" } }, "required": [ "data" ], "additionalProperties": false, "title": "ToOneRelationship", "description": "Party that owns the event" } }, "required": [ "party" ], "additionalProperties": false, "title": "EventRelationships", "description": "Resource relationships" } }, "required": [ "type", "id", "attributes", "relationships" ], "additionalProperties": false, "title": "EventResource" } }, "meta": { "type": "object", "properties": { "pagination": { "type": "object", "properties": { "hasMore": { "type": "boolean" }, "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "hasMore", "nextCursor" ], "additionalProperties": false, "title": "PaginationMeta" } }, "required": [ "pagination" ], "additionalProperties": false } }, "required": [ "data", "meta" ], "additionalProperties": false }, "examples": { "default": { "summary": "Default", "value": { "data": [ { "type": "event", "id": "evt_0192abc1def2789034567890abcdef12", "attributes": { "eventType": "wallet.created", "resourceId": "wal_7c9e6679e29b41d4a716446655440001", "resourceType": "wallet", "payload": { "object": { "partyId": "pty_7c9e6679e29b41d4a716446655440001", "tier": "standard", "status": "active", "displayName": "My Wallet", "supportedAssets": [ "usd" ], "freezeDetails": null, "createdAt": "2026-03-16T12:00:00Z", "updatedAt": "2026-03-16T12:00:00Z", "createdBy": "usr_550e8400e29b41d4a716446655440000", "version": 1 } }, "createdAt": "2026-03-16T12:00:00Z" }, "relationships": { "party": { "data": { "type": "party", "id": "pty_7c9e6679e29b41d4a716446655440001" } } } } ], "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "A request value is invalid.", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "email: Invalid email address", "status": "422", "source": { "pointer": "/data/attributes/email" }, "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "428": { "description": "Precondition Required", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "mfa_required", "detail": "MFA verification required", "status": "428", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "429": { "description": "Too Many Requests", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "rate_limited", "detail": "Too many requests. Please try again later.", "status": "429", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying", "schema": { "type": "integer" } }, "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" } } } }, "500": { "description": "Internal Server 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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "server_error", "detail": "Something went wrong.", "status": "500", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "501": { "description": "Not Implemented", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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_implemented", "detail": "This operation is not available.", "status": "501", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "502": { "description": "Bad Gateway", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "bad_gateway", "detail": "We couldn't complete that request because one of Natural's services returned an unexpected response. Please try again.", "status": "502", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "503": { "description": "Service Unavailable", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "service_unavailable", "detail": "The service is temporarily unavailable.", "status": "503", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } } }, "security": [ { "HTTPBearer": [] } ] } }, "/events/{eventId}": { "get": { "operationId": "events.get", "summary": "Get event", "description": "Get details of a specific event.", "tags": [ "Events" ], "parameters": [ { "name": "eventId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^evt_[0-9a-f]{32}$", "description": "Event ID (evt_xxx)" } }, { "name": "partyId", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^pty_[0-9a-f]{32}$", "description": "Party context for delegation" }, "allowEmptyValue": true, "allowReserved": true }, { "name": "X-Agent-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "description": "Agent ID (agt_xxx) identifying which agent is making the request." }, { "name": "X-Instance-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 1024 }, { "type": "null" } ] }, "description": "Required when X-Agent-ID is present. Session or conversation ID for agent observability." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "description": "Resource type", "type": "string", "enum": [ "event" ] }, "id": { "type": "string", "description": "Resource ID (evt_xxx)" }, "attributes": { "type": "object", "properties": { "eventType": { "enum": [ "party.updated", "compliance_case.updated", "wallet.created", "external_account.connected", "agent_delegation_invitation.created", "agent_delegation_invitation.accepted", "agent_delegation_invitation.declined", "agent_delegation_invitation.canceled", "agent_delegation.revoked", "delegation.activated", "delegation.revoked", "deposit.created", "deposit.completed", "deposit.failed", "deposit.returned", "deposit.canceled", "deposit.approval_denied", "withdrawal.created", "withdrawal.completed", "withdrawal.failed", "withdrawal.returned", "withdrawal.canceled", "withdrawal.approval_denied", "payment.created", "payment.completed", "payment.failed", "payment.returned", "payment.canceled", "payment.approval_denied", "approval.required", "approval.approved", "approval.denied", "approval.canceled", "payment_request.created", "payment_request.completed", "payment_request.canceled", "payment_request.declined", "payment_request.incoming" ], "type": "string", "description": "Type of event" }, "resourceId": { "type": "string", "description": "ID of the resource that triggered the event" }, "resourceType": { "type": "string", "description": "Type of the resource (e.g. wallet, payment)" }, "payload": { "type": "object", "properties": { "object": { "description": "Point-in-time resource snapshot" } }, "additionalProperties": {}, "description": "Event payload containing the resource snapshot. Additional keys may be added in the future." }, "createdAt": { "type": "string", "format": "date-time", "description": "Creation timestamp (ISO 8601)" } }, "required": [ "eventType", "resourceId", "resourceType", "payload", "createdAt" ], "additionalProperties": false, "title": "EventAttributes", "description": "Resource attributes" }, "relationships": { "type": "object", "properties": { "party": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "description": "Resource type", "type": "string", "enum": [ "party" ] }, "id": { "type": "string" } }, "required": [ "type", "id" ], "additionalProperties": false, "title": "ResourceIdentifier", "description": "Related resource identifier" } }, "required": [ "data" ], "additionalProperties": false, "title": "ToOneRelationship", "description": "Party that owns the event" } }, "required": [ "party" ], "additionalProperties": false, "title": "EventRelationships", "description": "Resource relationships" } }, "required": [ "type", "id", "attributes", "relationships" ], "additionalProperties": false, "title": "EventResource" } }, "required": [ "data" ], "additionalProperties": false }, "examples": { "default": { "summary": "Default", "value": { "data": { "type": "event", "id": "evt_0192abc1def2789034567890abcdef12", "attributes": { "eventType": "wallet.created", "resourceId": "wal_7c9e6679e29b41d4a716446655440001", "resourceType": "wallet", "payload": { "object": { "partyId": "pty_7c9e6679e29b41d4a716446655440001", "tier": "standard", "status": "active", "displayName": "My Wallet", "supportedAssets": [ "usd" ], "freezeDetails": null, "createdAt": "2026-03-16T12:00:00Z", "updatedAt": "2026-03-16T12:00:00Z", "createdBy": "usr_550e8400e29b41d4a716446655440000", "version": 1 } }, "createdAt": "2026-03-16T12:00:00Z" }, "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "A request value is invalid.", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "email: Invalid email address", "status": "422", "source": { "pointer": "/data/attributes/email" }, "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "428": { "description": "Precondition Required", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "mfa_required", "detail": "MFA verification required", "status": "428", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "429": { "description": "Too Many Requests", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "rate_limited", "detail": "Too many requests. Please try again later.", "status": "429", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying", "schema": { "type": "integer" } }, "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" } } } }, "500": { "description": "Internal Server 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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "server_error", "detail": "Something went wrong.", "status": "500", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "501": { "description": "Not Implemented", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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_implemented", "detail": "This operation is not available.", "status": "501", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "502": { "description": "Bad Gateway", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "bad_gateway", "detail": "We couldn't complete that request because one of Natural's services returned an unexpected response. Please try again.", "status": "502", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } }, "503": { "description": "Service Unavailable", "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" }, "parameter": { "type": "string" }, "header": { "type": "string" } }, "additionalProperties": false }, "meta": { "type": "object", "description": "Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata.", "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", "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": "service_unavailable", "detail": "The service is temporarily unavailable.", "status": "503", "meta": { "supportId": "req_a1b2c3d4e5f6" } } ] } } } } } } }, "security": [ { "HTTPBearer": [] } ] } } }, "tags": [ { "name": "Agents", "description": "Agent management" }, { "name": "Customers", "description": "Customer management" }, { "name": "Counterparties", "description": "Counterparty management" }, { "name": "Payments", "description": "Payment operations" }, { "name": "Transactions", "description": "Transaction activity and history operations" }, { "name": "Transfers", "description": "Deposit and withdrawal operations" }, { "name": "PaymentRequests", "description": "Payment-request management" }, { "name": "Approvals", "description": "Approval review operations" }, { "name": "Invitations", "description": "Party invitation management" }, { "name": "Identity", "description": "Caller identity introspection" }, { "name": "Parties", "description": "Party and organization management" }, { "name": "Wallets", "description": "Wallet balance, deposits, withdrawals, and external accounts" }, { "name": "External Accounts", "description": "Linked external bank accounts" }, { "name": "API Keys", "description": "API key management" }, { "name": "Agent Keys", "description": "Agent key management" }, { "name": "Webhooks", "description": "Webhook endpoint management" }, { "name": "Events", "description": "Webhook event log access" } ] }