Documentation
Request a Demo

API - Overview

Project Folder Navigation

List all Project Folders

GET /api/project_folders

This will return a list of JSON objects describing all Project Folders for which the requesting user is a collaborator.


{
 "project_folders": [
    {
         "id": <int>,
         "name": <str>
    },
    ...
 ]
}

project_folders (array[object]):

An array of JSON objects describing project folders. Each object contains two fields:

  • id (int): The ID of the project folder, required for API calls specific to this folder.
  • name (str): The name of the folder as it was configured in the Redbird UI.

List all Collections within a Project Folder

GET /api/project_folders/<PROJECT FOLDER ID>/collections

This will return a list of JSON objects describing all Collections within the specified Project Folder.

Required URL Substitutions:

  • PROJECT FOLDER ID: ID of the Project Folder from which to retrieve Collections,

{
 "collections": [
    {
         "id": <int>,
         "name": <str>,
         "project_folder_id": <int>,
         "created_date": <str>,
         "csv_path": <str>,
         "column_count": <int>
    },
    ...
 ]
}

collections (array[object]):

An array of JSON objects describing Collections. Each object contains the following fields:

  • id (int): The ID of the Collection, is required for other API calls against this specific Collection.
  • name (str): The name of the Collection as it was configured in the Redbird UI.
  • project_folder_id (int): The ID of the parent Project Folder, is the same as the one provided in the URL
  • created_date (str): A string representing the date that the Collection was created
  • csv_path (str): A string containing a path to the underlying CSV of the Collection, from which the requesting process may download the file.
  • column_count (int): The number of columns that this Collection has.

List all Datasets within a Project Folder

GET /api/project_folders/<PROJECT FOLDER ID>/datasets

This will return a list of JSON objects describing all Datasets within the specified Project Folder.

Required URL Substitutions:

PROJECT FOLDER ID: ID of the Project Folder from which to retrieve Datasets.


{
 "collections": [
    {
         "id": <int>,
         "name": <str>,
         "project_folder_id": <int>,
         "created_date": <str>,
         "csv_path": <str>,
         "column_count": <int>
    },
    ...
 ]
}

datasets (array[object]): An array of JSON objects describing Datasets. Each object contains the following fields:

  • id (int): The ID of the Dataset is required for other API calls against this specific Dataset.
  • name (str): The name of the Dataset as it was configured in the Redbird UI.
  • project_folder_id (int): The ID of the parent Project Folder, is the same as the one provided in the URL
  • created_date (str): A string representing the date that the Dataset was created
  • csv_path (str): A string containing a path to the underlying CSV of the Dataset, from which the requesting process may download the file.
  • column_count (int): The number of columns that this Dataset has.


Collection Navigation

GET /api/collections/<COLLECTION ID>

This will return a JSON object summarizing the details of a Collection. These are the same fields provided for each collection listed within a Project Folder (see "List all Collections within a Project Folder").

Required URL Substitutions:

  • COLLECTION ID: ID of the Collection to retrieve summary data for.

{
 "id": <int>,
 "name": <str>,
 "project_folder_id": <int>,
 "created_date": <str>,
 "csv_path": <str>,
 "column_count": <int>
}

  • id (int): The ID of the Collection, required for other API calls against this specific Collection; is identical to the one provided in the requesting URL.
  • name (str): The name of the Collection as it was configured in the Redbird UI.
  • project_folder_id (int): The ID of the parent Project Folder of this Collection.
  • created_date (str): A string representing the date that the Collection was created.
  • csv_path (str): A string containing a path to the underlying CSV of the Collection, from which the requesting process may download the file.
  • column_count (int): The number of columns that this Collection has.

List all Columns on a Collection

GET /api/collections/<COLLECTION ID>/columns

This will return a list of JSON objects describing all Columns attached to a Collection.

Required URL Substitutions:

  • COLLECTION ID: ID of the Collection to retrieve column data for.

{
 "columns": [
    {
         "id": <int>,
         "name": <str>,
         "type": <str>,
         "position": <int>
    },
    ...
 ]
}

columns (array[object]):
An array of JSON objects describing Columns on the Collection. Each object contains the following fields:

  • id (int): The ID of the Column within the Redbird system.
  • name (str): The name of the Column as it was configured in the Redbird UI.
  • type (str): The data type of the column. One of:
    • Text
    • Number
    • Binary
    • Date
  • position (int): The zero-indexed, left-to-right position that the column occupies within the Collection.

Dataset Navigation and Querying

Get a Dataset Summary

GET /api/datasets/<DATASET ID>

This will return a JSON object summarizing the details of a Dataset. These are the same fields provided for each Dataset listed within a Project Folder (see "List all Datasets within a Project Folder").

Required URL Substitutions:

  • DATASET ID: ID of the Dataset to retrieve summary data for.

{
 "id": <int>,
 "name": <str>,
 "project_folder_id": <int>,
 "created_date": <str>,
 "csv_path": <str>,
 "column_count": <int>
}

  • id (int): The ID of the Dataset, required for other API calls against this specific Dataset; identical to the one provided in the requesting URL.
  • name (str): The name of the Dataset as it was configured in the Redbird UI.
  • project_folder_id (int): The ID of the parent Project Folder of this Dataset.
  • created_date (str): A string representing the date that the Dataset was created.
  • csv_path (str): A string containing a path to the underlying CSV of the Dataset, from which the requesting process may download the file.
  • column_count (int): The number of columns that this Dataset has.

List all Columns on a Dataset

GET /api/datasets/<DATASET ID>/columns

This will return a list of JSON objects describing all Columns attached to a Dataset.

Required URL Substitutions:

  • DATASET ID: ID of the Dataset to retrieve column data for.

{
 "columns": [
    {
         "id": <int>,
         "name": <str>,
         "type": <str>,
         "position": <int>
    },
    ...
 ]
}

columns (array[object]):
An array of JSON objects describing Columns on the Dataset. Each object contains the following fields:

  • id (int): The ID of the Dataset within the Redbird system. Necessary for selecting columns to pull when querying Datasets (see "Querying a Dataset").
  • name (str): The name of the Column as it was configured in the Redbird UI.
  • type (str): The data type of the column.
  • position (int): The zero-indexed, left-to-right position that the column occupies within the Dataset.

Querying a Dataset

GET /api/datasets/<DATASET ID>/query?format=<str>&limit=<int>&offset=<int>...

This endpoint provides access to a subset of rows and columns within the specified Dataset. The filtering parameters are provided via query string parameters, as described below.

Required URL Substitutions:

  • DATASET ID: ID of the Dataset to retrieve summary data for.

Query String Parameters:

  • format (required): The format in which to return results. Currently, the only accepted value is "json" (without quotes), but is required to allow for future formatting options.
  • limit (required): Required when requesting JSON, with a maximum of 2000 rows per request. To retrieve unfiltered data as a CSV, please see the "csv_path" field of the Dataset summary object (described in "Get a Dataset Summary" and "List all Datasets in a Project Folder"). To retrieve more than 2000 rows as JSON, submit multiple requests using the related "offset" parameter.
  • offset (required): Required when requesting JSON, and used in conjunction with "limit" to allow retrieval and pagination of results that exceed the 2000 row limit. When an offset value is provided in the request, the response will include dataset rows starting at the offset index and ending at an index of offset + limit. Offsets begin at zero for the first page of results.
  • col_id (optional, repeatable): May be specified one or more times in the query string to indicate specific column IDs to be pulled (see "List all Columns on a Dataset"). If provided, any columns not specified will be excluded. Result columns will be in the same order that they are specified within the query string. If omitted, all columns of the Dataset are returned in the order that they are configured in the Redbird UI.
  • sort_id (optional): The ID of a Column within the Dataset to use for sorting in ascending order (see "List all Columns on a Dataset"). If not provided, results will be sorted using an internal ID to ensure consistent ordering across paginated results.

{
  "results": <array[array[str]]>
}

  • results (array[array[str]]): A two-dimensional JSON array representing the requested data, with all values as strings. In the two-dimensional array, the first dimension represents rows, and the second dimension represents the values within each row corresponding to the requested columns.

Collection Augmentation

Overview

Adding rows to an existing Collection consists of three main steps:

  1. Create an UpdateSet: Create a new UpdateSet object to represent the batch of rows to be added.
  2. Add Rows to an UpdateSet: Repeatedly add rows to that UpdateSet object to stage them for commitment.
  3. Commit an UpdateSet to a Collection: Committing the staged UpdateSet rows to the associated Collection, altering the Collection, and deleting the UpdateSet.

Each step is represented by its own endpoint and explored in further detail in that endpoint’s documentation.

Create an UpdateSet

POST /api/collections/<COLLECTION ID>/update_sets

This call must be made before any other calls to UpdateSet endpoints. This will create an empty UpdateSet to which rows can later be added. No changes are made to the associated Collection until the UpdateSet is committed (see “Commit an UpdateSet to a Collection”).

Required URL Substitutions:

  • COLLECTION ID: ID of the Collection to update.

{
  "update_set_id": <int>
}

  • update_set_id (int): The ID of the newly created UpdateSet, for use in subsequent calls to add rows and commit.

Add Rows to an UpdateSet

POST /api/update_sets/<UPDATE SET ID>/rows

This endpoint may be invoked as many times as necessary to add rows to the UpdateSet in batches, before finally committing those rows to the associated Collection via the commit endpoint (see “Commit an UpdateSet to a Collection”).

This endpoint accepts data either from a remote CSV (which must be publicly accessible without authentication) or JSON included within the request itself.

Required URL Substitutions:

  • UPDATE SET ID: ID of a previously created UpdateSet to add rows to.

//For updates from remote CSV files:
{
  "csv_url": <str: required>,
  "has_header": <boolean: required>,
  "delimiter": <str: optional>,
  "quotechar": <str: optional>
}

  • csv_url (str, required): URL pointing to a publicly accessible CSV file to stream rows from
  • has_header (boolean, required): Boolean indicating whether or not the supplied CSV has a header row. If true, the first row of the CSV will be ignored during ingestion.
  • delimiter (str, optional): A string indicating the delimiter used within the provided CSV file. If not provided, the default separator is a comma (",", without quotes).
  • quotechar (str, optional): A string indicating the quote character used within the provided CSV file. If not provided, the default quote character is double-quotes ('"', without the surrounding single quotes).

//For updates from inline JSON:
{
  "row_data": <array[array[str]]: required>
}

  • row_data (array[array[str|int]], required): A two-dimensional JSON array representing the rows to add to the UpdateSet. Maximum of 1000 rows per request.

Response (JSON): A 200 OK response containing only an empty JSON object, unless there was an error (see "Error Handling").


Commit an UpdateSet to a Collection

POST /api/update_sets/<UPDATE SET ID>/commit

This endpoint must be called once all desired rows have been added to the UpdateSet. This endpoint will take the data gathered within the UpdateSet and add it to a Collection, adhering to the update policy for that Collection that was configured in the Redbird UI (i.e. append vs. replace/overwrite).

Once the data has been added to the Collection, the UpdateSet (and its now-redundant row data) is deleted and can no longer be interacted with. To make additional changes to the Collection, create a new UpdateSet and begin adding rows to it.

Required URL Substitutions:

  • COLLECTION ID: ID of the Collection to which the UpdateSet is attached.
  • UPDATE SET ID: ID of a previously created UpdateSet to add rows to.

Response (JSON): A 200 OK response containing only an empty JSON object, unless there was an error (see "Error Handling").

Error Handling

For non-5xx errors, in addition to the appropriate HTTP status code, the server will return a JSON response containing specific information about what went wrong, when possible. The object will have the following form:


{
  "error": <str>
}

Status codes that will return with the above JSON object include:

HTTP 409 - Conflict

HTTP 400 - Bad Request

For non-5xx errors, the issue can often be resolved with changes to the parameters provided in the request, as indicated by the error messages returned.

5xx-series errors will in general indicate an issue on the Redbird backend that will require contacting customer support to resolve.


Workflow Canvas Navigation

List all Workflow Canvases

GET /api/workflow_canvases

This will return a list of JSON objects describing all Workflow Canvases for which the requesting user is a collaborator (as owner, editor, or viewer).


{
  "workflow_canvases": [
    {
      "id": <int>,
      "name": <str>,
      "status": <str>,
      "project_folder_id": <int>
    },
    ...
  ]
}

workflow_canvases (array[object]):

An array of JSON objects describing Workflow Canvases. Each object contains the following fields:

  • id (int): The ID of the Workflow Canvas, required for API calls specific to this canvas.
  • name (str): The name of the Workflow Canvas as it was configured in the Redbird UI.
  • status (str): The current status of the Workflow Canvas.
  • project_folder_id (int): The ID of the Project Folder that contains this Workflow Canvas.

List all Nodes on a Workflow Canvas

GET /api/workflow_canvases/<WORKFLOW CANVAS ID>/nodes

This will return a list of JSON objects describing all Nodes on the specified Workflow Canvas.

Required URL Substitutions:

  • WORKFLOW CANVAS ID: ID of the Workflow Canvas from which to retrieve Nodes.

{
  "nodes": [
    {
      "id": <int>,
      "name": <str>,
      "type": <str>,
      "workflow_canvas_id": <int>
    },
    ...
  ]
}

nodes (array[object]):

An array of JSON objects describing Nodes on the Workflow Canvas. Each object contains the following fields:

  • id (int): The ID of the Node, required for API calls targeting this specific Node.
  • name (str): The name of the Node as it was configured in the Redbird UI.
  • type (str): The type of the Node (e.g., collect, process, utilize).
  • workflow_canvas_id (int): The ID of the parent Workflow Canvas, identical to the one provided in the URL.

List all Automated Runs on a Workflow Canvas

GET /api/workflow_canvases/<WORKFLOW CANVAS ID>/automated_runs

This will return a list of JSON objects describing all Automated Runs configured on the specified Workflow Canvas.

Required URL Substitutions:

  • WORKFLOW CANVAS ID: ID of the Workflow Canvas from which to retrieve Automated Runs.

{
  "automated_runs": [
    {
      "id": <int>,
      "name": <str>,
      "run_mode": <str>,
      "next_run_time": <str>,
      "workflow_canvas_id": <int>
    },
    ...
  ]
}

automated_runs (array[object]):

An array of JSON objects describing Automated Runs. Each object contains the following fields:

  • id (int): The ID of the Automated Run, required for API calls targeting this specific Automated Run.
  • name (str): The name of the Automated Run as it was configured in the Redbird UI.
  • run_mode (str): The run mode of this Automated Run schedule.
  • next_run_time (str): A string representing the next scheduled execution time for this Automated Run, or null if not scheduled.
  • workflow_canvas_id (int): The ID of the parent Workflow Canvas, identical to the one provided in the URL.

List all Automated Runs

GET /api/automated_runs

This will return a list of JSON objects describing all Automated Runs across every Workflow Canvas for which the requesting user is a collaborator. The response shape is identical to the one described in "List all Automated Runs on a Workflow Canvas".


{
  "automated_runs": [
    {
      "id": <int>,
      "name": <str>,
      "run_mode": <str>,
      "next_run_time": <str>,
      "workflow_canvas_id": <int>
    },
    ...
  ]
}

Workflow Canvas Execution

Run a Workflow Node

POST /api/workflow_canvases/<WORKFLOW CANVAS ID>/nodes/<NODE ID>/run

This endpoint triggers an immediate run of a single Node on a Workflow Canvas. The run is executed asynchronously; the response returns a run ID that can be used to poll for status (see "Get Workflow Run Status").

Required URL Substitutions:

  • WORKFLOW CANVAS ID: ID of the Workflow Canvas containing the Node.
  • NODE ID: ID of the Node to run.

{
  "run_id": <int>
}

  • run_id (int): The ID of the newly created Workflow Run.

Run an Automated Run

POST /api/workflow_canvases/<WORKFLOW CANVAS ID>/automated_runs/<AUTOMATED RUN ID>/run

This endpoint triggers an immediate, ad-hoc execution of an Automated Run configuration. Like running a Node, the execution is asynchronous and a run ID is returned for status polling (see "Get Workflow Run Status").

Required URL Substitutions:

  • WORKFLOW CANVAS ID: ID of the Workflow Canvas containing the Automated Run.
  • AUTOMATED RUN ID: ID of the Automated Run to execute.

{
  "run_id": <int>
}

  • run_id (int): The ID of the newly created Workflow Run.

Workflow Run Status

Get Workflow Run Status

GET /api/workflow_runs/<WORKFLOW RUN ID>/status

This endpoint returns the current status and timing information for a specific Workflow Run. It is intended to be polled after triggering a run via the execution endpoints above.

Required URL Substitutions:

  • WORKFLOW RUN ID: ID of the Workflow Run to retrieve status for.

{
  "id": <int>,
  "status": <str>,
  "run_time_scheduled": <str>,
  "run_time_start": <str>,
  "run_time_end": <str>
}

  • id (int): The ID of the Workflow Run; identical to the one provided in the requesting URL.
  • status (str): The current display status of the Workflow Run (e.g., "Running", "Complete", "Failed").
  • run_time_scheduled (str): A string representing the time at which the run was scheduled, or null if not applicable.
  • run_time_start (str): A string representing the time at which the run began executing, or null if it has not yet started.
  • run_time_end (str): A string representing the time at which the run finished, or null if still in progress.

Updated 20 days ago

What’s Next