Introduction

Tulip API

This documentation describes the public Tulip API, which gives customers programmatic access to their Tulip data as well as tools for generating content and configuring their Tulip instance. Not all parts of the Tulip platform are currently available in public APIs, but new APIs are planned to be released in the future. If you would like to request API access to a particular part of the Tulip platform, please post a product suggestion in the Tulip Community.

See Tulip's Public API Policy for more information on compatibility, limits, and support.

For guides and how-to articles on using the API, see Work with APIs.

Organization

The Tulip Next-Gen API is divided into sections called namespaces which broadly represent areas of the Tulip platform such as apps, tables, connectors, stations, and automations. Each API namespace is versioned separately in order to allow Tulip to develop improvements to parts of the API without affecting others. All Tulip APIs start with a path such as /api/{namespace}/{version}, where {version} is a version identifier of the form v1, v2, v3, etc. Refer to the Public API Policy for information on versioning semantics.

Previous versions of the Tulip API used a slightly different versioning scheme which did not use namespaces. These endpoints start with /api/v2 or /api/v3.

Authentication

Access to the Tulip API requires the use of HTTP Basic Authentication using the credentials of an active Tulip API Token. All requests require the Authorization HTTP header with the Basic scheme to provide API credentials unless otherwise noted.

Authorization

API tokens can be configured with a set of scopes which determine what parts of the API that specific token has access to. Security best practices dictate that API credentials be given the minimum set of capabilities required to fulfill their intended purpose. For example, an API token created for use in an integration that is only designed to use the Stations API should probably only be given the stations:read and stations:write scopes. In this way you can minimize risk in the event that API credentials are compromised. API endpoints will document what API token scopes are required to access that endpoint in their descriptions. If a request is made to an endpoint with an API token which does not have the required scopes, the response will be an authorization error.

Workspaces

Most Tulip API endpoints require a workspace context in order to specify what workspace the data should be queried in. For example, Tulip apps always exist in the context of a particular workspace, so if you have an app which exists in a particular workspace, making any request which involves that app in the context of a different workspace will result in the data not being found. If you are using a workspace-scoped API token in your request, the workspace context is automatically inferred from the token's workspace. If you are using a global API token, you will need to provide the workspace context yourself in the request. There are two ways of doing this:

• Prefix the request path after the namespace version with /w/{workspaceId} (for example /api/stations/v1/interfaces becomes /api/stations/v1/w/{workspaceId}/interfaces; /api/v3/appGroups becomes /api/v3/w/{workspaceId}/appGroups).
• Set the HTTP header X-Tulip-Workspace-ID to the workspace ID.
• If both a path prefix and a header are provided, the header takes precedence.

To find the ID of your workspace, you can copy it from the URL of any workspace-scoped page in Tulip, where it also appears as a path prefix of the form /w/{workspaceId}. Note that the first workspace in any Tulip instance has the ID DEFAULT.