Skip to main content
folk’s API uses versioning to ensure backward compatibility. By default, every request is made to the latest version of the API. You can specify the API version you want to use through the X-API-Version header.
Providing an invalid version will return a 400 Bad Request error. It’s recommended to always specify the API version in your requests to avoid unexpected changes in the request or response format. We strive to improve the API and add new features regularly. Every time a breaking change is introduced, a new version of the API is released. You can find the list of changes in the changelog section.

​
Additive changes

Changes that only add to the API are not considered breaking. They can happen within an existing version and are announced in the changelog:
  • new endpoints, and new optional parameters or request properties on existing endpoints
  • new properties in a response
  • new values in an enumerated response field, such as a new interaction activityType
  • new variants in a response union, such as a new interactionType on interactions
  • new response headers
Build your integration to tolerate additions: ignore response properties you do not know, and handle an unknown enum value or an unknown variant without rejecting the whole response. Validating responses strictly against a snapshot of the schema will break on the next addition.

​
Endpoint availability

We ensure that each endpoint remains available for at least 1 year from its release date. When we plan to remove or replace an endpoint, we provide a 6-month deprecation notice before it is discontinued. Deprecation notices are published in the changelog.

​
Deprecated endpoints

When an operation is deprecated:
  • The response includes a Deprecation header with the date deprecation started, and a Sunset header with the date the endpoint will stop being available — both formatted as HTTP dates.
  • The deprecation message is included in the response body’s deprecations array.
  • The endpoint is marked with a “Deprecated” badge and a warning banner in this documentation.
Deprecation is informational only. A deprecated endpoint keeps working exactly as before until it’s removed, at which point it follows the same endpoint availability policy as any other change.