Skip to main content
The Natural API is unversioned. There is one version, and we do not make backwards-incompatible changes to existing endpoints. The API evolves through additive, non-breaking changes only.

​
Backwards-compatible changes

These changes can happen at any time without notice:
  • Adding new API endpoints
  • Adding new optional request parameters to existing endpoints
  • Adding new fields to response objects
  • Adding new values to existing enums (e.g., new payment statuses)
  • Adding new error codes
  • Changing the order of fields in responses
  • Changing the length or format of opaque strings (IDs, cursors, tokens)

​
Breaking changes

These require advance notice and a migration path:
  • Removing or renaming existing endpoints
  • Removing or renaming response fields
  • Changing the type of an existing field
  • Making a previously optional parameter required
  • Changing the meaning of an existing field or parameter
  • Removing supported values from enums
  • Changing authentication mechanisms
  • Changing error response structure

​
Writing resilient integrations

  • Ignore unknown fields in responses. New fields may be added at any time.
  • Handle unknown enum values gracefully. New statuses or types may appear.
  • Don’t hard-code cursor formats. Treat cursors as opaque strings.
  • Use idempotency keys for payment operations to safely retry on failure.