At Finch, we are committed to ensuring API stability. We design our APIs with backward compatibility in mind, and we want to make it clear what types of changes we consider non-breaking - changes that should not impact existing client integrations. This page outlines the changes we may introduce without a new API version or advance warning.

​
Additive Changes

  • Adding new optional request fields: We may introduce new fields that are not required. Your existing requests will continue to work as-is.
  • Adding new response fields: You may start seeing additional fields in API responses. These will not change the structure of existing fields and can be safely ignored by clients that don’t use them.
  • Introducing new endpoints: New endpoints do not interfere with existing functionality.
  • Adding new enum values: If you’re using enums, we may add new values. Make sure your implementation doesn’t break when unknown enum values are returned.
  • Adding new errors: New error types and codes can be added to accurately indicate the success or failure of a task. These will not change existing errors.

​
Documentation Updates

  • Clarifying descriptions: We may refine or clarify descriptions, usage examples, or error codes in our documentation.
  • Improving examples or formatting: These changes help improve readability and developer experience, but do not impact functionality.

​
Performance Upgrades

  • Improving response time: Backend optimizations or caching mechanisms that improve performance without changing behavior.
  • Upgrading infrastructure: These are internal changes and do not affect how the API behaves or how it should be used.
To ensure your integration with Finch is as robust as possible, we recommend:
  • Use tolerant JSON parsers that ignore unknown fields
  • Don’t rely on the exact order of response fields
  • Make your code resilient to new enum values or unexpected optional fields