Navbar

API Conventions

All endpoints adhere to a set of standard names, structures, and formats for consistency and predictability across the entirety of the API.

Projects and Teams

For historical reasons, Projects and Teams are referred to as "Lists" and "Workspaces", respectively, within the API. The terms "project" and "team" are client-side translations and do not apply to endpoints or attributes in the Flow API.

Keep this in mind while building your payloads and requests; you will be sent and will be required to send attributes such as workspace_id and list_id and call endpoints such as /lists.

Content Types

For POST and PUT requests, you will need to specify a Content-Type header with your request to ensure the JSON you send is parsed correctly.

Simply include the Content-Type header:

Content-Type: application/vnd.flow.v2+json

API Versions

The Public API is version 2 of the Flow API. Thus, Public API tokens are locked only to Version 2, so you'll need to make sure you are specifying it correctly when making requests.

There are two methods to specifying API version; feel free to choose whichever method is easiest for you to implement.

Specifying version via the Accept header

The most transparent way is to ensure you set the Accept HTTP header to our custom content-type declaration, which includes a version string. For v2, should look like:

Accept: application/vnd.flow.v2+json

Specifying version via the URI

If you don't want to set headers, you can also specify API version as the first section of the URI when making a request. Simply prefix any path with /v2. For example:

GET /v2/lists/1234
POST /v2/tasks
[etc.]

Query Views

A common concept between all endpoints on the V2 API is "Views": a predefined set of filters and modifying parameters to restrict the returned results of the request for common use cases. Views have been optimized by the Flow API team for maximum performance, and thus using a View may result in better performance.

For example, the /tasks endpoint has a View named "upcoming", which, if specified, limits the request to return only tasks which have a due-date, saving you from having to add or develop this constraint yourself.

To use a View, simply specify it in the ?view parameter. To continue with the previous example on the /tasks endpoint:

GET /tasks?organization_id=52&view=upcoming

Every endpoint has a "default" View (as the name suggests, it is used when no View is specified), which returns all results. For some simple endpoints, this may be the only View available.

You are free to ignore Views completely, and specify constraints manually, however we ask that you try to use a View as it allows us to better optimize the resulting queries behind the scenes.

The API Reference documentation exhaustively lists all available Views and their behaviour for each endpoint. Some Views may also provide additional parameters of their own to allow greater customization.

Error payloads

Sometimes things don't work how you expect. Perhaps you're missing a required attribute, or perhaps the resource you're trying to access is not available to you--in any case, we have tried to craft error responses to be as helpful as possible.

Here's an example error message:

{
  "request_uuid": "8a72bead-8d69-44c2-be4a-0a355b1ad4a0",
  "status": "error",
  "errors": [
    {
      "message": "param is missing or the value is empty: organization_id",
      "code": "missing_param",
      "link": "https://developer.getflow.com/errors/missing_param",
      "description": "param is missing or the value is empty: organization_id",
      "attribute": "organization_id"
    }
  ]
}

For more in-depth explanations and documentation of every type of error we may send, please refer to the errors documentation.

Dates & Times

All dates and time passed to the API must be ISO8601 formatted. For example,

Request IDs

A request_id is returned for most requests in the base json object. If you're running into trouble with a certain request, including the Request ID in your message to support helps us debug the issue much easier.

Pagination

We use cursor and limit for pagination of results. By default, cursor is 0 and limit is 25.

Example:

GET /tasks?organization_id=52&limit=30&cursor=60

Clients will not typically need to include a cursor parameter on the initial request to the activities API. Without a cursor, the API will return the most recent activity. The response will include a Link header with the URL of the next page (including the requisite cursor parameter). In most cases, clients should never need to manually set the cursor parameter.

To have related resources returned with your request, most endpoint support using the include param.

For example,

GET /tasks?organization_id=52&include=accounts,memberships

... will include all of the related account and membership records along with the tasks as accounts and memberships in the root object. See each endpoint's specific documentation for more details, including which resources are supported on each endpoint.