Public API Policy

Last Updated: January 31, 2024

Tulip provides a set of public APIs which enable users to interact programmatically with the Tulip platform. Tulip organizes its APIs into groups called Namespaces which broadly represent functional areas of the Tulip product (e.g. Apps, Automations, Users, etc.). Each API Namespace is given a label called its version (of the form “v1”, “v2”, “v3”, etc.). All API endpoints contained in a Namespace are versioned together as a unit.

As Tulip develops new features, improves existing features, and fixes problems, we may release updates to these APIs which either change an existing version of the API or introduce a new version of the API (the rules that dictate what types of changes necessitate a new version are described in the Stability section). API updates are released with each Tulip platform release and will be described in Tulip’s release notes. Multiple versions of a given Namespace may be available at any given time. Users are encouraged to use the most up-to-date version of the APIs, but previous versions are maintained for a period of time (see the Support section for more on the lifecycle of versions). Any rights to use Tulip APIs are as set forth in Tulip’s API License Agreement.

When a version of a Tulip API Namespace is considered stable, Tulip may release changes to the API, but such changes must be backwards-compatible. In the context of Tulip APIs, a change is generally considered backwards-compatible if it does not break the functionality of existing integrations using that API. Specifically, the following types of changes are considered backwards-compatible:

• Adding a new endpoint to a Namespace.

• Adding an optional request body field, query parameter, or HTTP header, such that the meaning of other fields, parameters, or headers are unchanged when the optional field is omitted. Note that unrecognized fields of request bodies are generally ignored, so a field that previously had no meaning (which would not cause an error) may gain meaning in a subsequent release without being considered a breaking change.

• Adding an accepted request body content-type to an endpoint. If the new content-type represents structured data (JSON, YAML, CSV, etc.), it must adhere to the documented structure of the request body. If the new content-type is unstructured data (image, video, PDF, plain text, other binary data), it must adhere to any documented constraints in the request body description.

• Changing the type or validation rules of a request body field, query parameter, or HTTP header such that all previously valid values are still considered valid.

• Adding a new response body field or HTTP header.

• Adding a new error response HTTP status code (4xx, 5xx).

• Removing possible values from the type of a response body field or HTTP header, such that the meaning of other fields or response headers are unchanged.

• Changing the documentation of a type, error code, field, or endpoint in a way that does not affect the behavior of the API.

• Changing the text of the error description presented in error responses.

• Changing the display names or other textual content of any Tulip-defined resources.

• Changing rate, size, or resource count limits enforced on endpoints.

• Fixing a bug in order to align the actual behavior of an endpoint with its documented behavior.

• Fixing a security vulnerability by any means necessary, including with changes that would otherwise be considered breaking. In the event that Tulip needs to release a critical security fix that results in a breaking API change, we will try to work with our customers to update their integrations to prevent downtime as much as possible.

• Adding, removing, or changing any endpoints, parameters, or types which are not publicly documented.

Occasionally, Tulip may need to release a change to an API that is not backwards-compatible. This is referred to as a breaking change or a backwards-incompatible change. Tulip will only release breaking changes to stable APIs in a new version of its API Namespace (with the exception of critical security fixes, as described above). The following types of changes are considered backwards-incompatible:

• Removing an endpoint from a Namespace.

• Removing a request body field, query parameter, or HTTP header.

• Removing an accepted request body content-type from an endpoint.

• Changing the response body content-type of an endpoint.

• Changing the type or validation rules of a request body field, query parameter, or HTTP header such that some inputs are no longer considered valid.

• Changing the default value of an optional request body field, query parameter, or HTTP header.

• Adding a required request body field, query parameter, or HTTP header.

• Adding an optional request body field, query parameter, or HTTP header such that the meaning of any other fields, parameters, or headers are changed as well.

• Adding possible values to the type of a response body field or HTTP header.

• Adding a new success response HTTP status code (1xx, 2xx, 3xx).

• Removing a response body field or HTTP header.

• Significantly changing the documented semantics or functionality of an endpoint, even if the interface is unchanged.

The Tulip API enforces various types of limits in order to protect shared resources (API servers, databases, etc.) from excessive load which can impact quality of service for other users and other customers. Such limits include (these are illustrative examples only):

• Rate limits: By default a given client cannot make requests to a given endpoint more than some number of times per second.

• Size limits: The name of a resource cannot exceed a certain number of characters, or the size of an uploaded file cannot exceed a certain file size.

• Resource count limits: No more than a certain number of workspaces can be created.

While Tulip may provide documentation on some of these limits, they are not considered part of the stable API and may change at any time based on current load conditions, evolving product requirements, user preferences, and other factors. Clients should use information provided by Tulip API responses (status codes, error codes, and error fields) to handle limiting errors. Tulip reserves the right to disable clients that repeatedly disregard these limits.

Tulip provides support for its APIs which is similar to the support we provide for other Tulip products. Full support includes maintaining documentation, answering questions, troubleshooting issues, releasing bug fixes, and releasing security fixes for these APIs. Tulip does not provide support for undocumented APIs. The level of support that Tulip provides for a public API Namespace version varies based on how it is labeled in the API documentation:

• Alpha - Tulip will provide limited support for this API and may release breaking changes to this API at any time.

• Beta - Tulip fully supports this API, but may release breaking changes to this API at any time. We will communicate any breaking changes with Beta customers.

• Stable - Tulip fully supports this API and considers it stable, as defined in the Stability section.

• Deprecated - Tulip intends to remove this API in the near future. Tulip will provide full support for this API, but users should plan on updating any integrations using it to a newer version of the API, which Tulip will provide guidance for. Deprecated APIs will generally not receive updates except critical security or bug fixes.

• End of Support - Tulip will not provide any support for this API, including critical security fixes. Unsupported APIs may cease to function at any time without notice.

Stable API Namespaces will remain stable for at least one LTS release cycle before being marked as deprecated. Deprecated API Namespaces will remain supported for at least two LTS release cycles before being marked as unsupported.