API Reference

Tokens for Invert's external API are issued through Auth0. The same authentication flow applies to both the Core and DSP views.

Receive a token from Auth0

In order to get a valid token use the following command:

curl --request POST \
  --url https://invert.eu.auth0.com/oauth/token \
  --header 'content-type: application/json' \
  --data '{
    "client_id": "<CLIENT_ID>",
    "client_secret": "<CLIENT_SECRET>",
    "audience": "https://api.invertbio.com/",
    "grant_type": "client_credentials"
  }'

CLIENT_ID and CLIENT_SECRET will be shared with you separately. The token returned by Auth0 will be valid for 24 hours and will need to be sent along with each SQL request.

The response will look like this:

{
  "access_token": "<ACCESS_TOKEN>",
  "expires_in": 86400,
  "token_type": "Bearer"
}

Using the token

Include the token in the Authorization header of every request:

curl -H "Authorization: Bearer <ACCESS_TOKEN>" \
 -H "Content-Type: application/json" \
 -X POST \
 -d '{"statement": "SELECT * FROM v_bioprocesses LIMIT 1"}' \
 https://api.invertbio.com/external/v1/statements/

If the token is invalid or expired, the response will be:

{
  "message": "Unauthorized"
}

Get a new Auth0 token and retry.

The Core external API provides SQL access to bioprocess data in Invert. See Authentication for how to obtain an access token.

Available Views

v_bioprocesses

Note: parents of bioprocesses (aka experiments) have been moved to a separate table called experiments

curl -H "Authorization: Bearer <AUTH0_TOKEN>" \
 -H "Content-Type: application/json" \
 -X POST \
 -d '{"statement": "SELECT * FROM v_bioprocesses LIMIT 1"}' \
 https://api.invertbio.com/external/v1/statements/

Field Name	Type	Description
id	String	Unique identifier for the bioprocess
external_id	String	An external identifier for the bioprocess
name	String	Name of the bioprocess
parent_id	String or null	Identifier of the parent bioprocess, if this is a child process
scheduled_start_timestamp	String or null	Scheduled start time (ISO 8601)
scheduled_end_timestamp	String or null	Scheduled end time (ISO 8601)
start_timestamp	String	Record start time (ISO 8601 with timezone)
run_start_timestamp	String or null	Start time of the bioprocess run
run_end_timestamp	String or null	End time of the bioprocess run
end_timestamp	String	Record end time (ISO 8601 with timezone)
duration_ms	Number	Duration of the bioprocess in milliseconds
status	String	Draft / Requested / Scheduled / In-progress / Completed
qc	Object	Quality control information: {status, failure_mode}
data	Array	List of data objects associated with the bioprocess
events	Array	List of events associated with the bioprocess
induction_event	Object or null	Information about the induction event
attachments	Array	List of attachments
lineage	Object or null	Lineage information
last_updated_at	String	Timestamp of the last update (ISO 8601)

Common Event Types

DbObservationEvent

Field	Type	Description
note	String	Textual observation or comment

DbAdditionEvent

Field	Type	Description
lot_number	String or null	Lot number of the added material
reagent_name	String or null	Name of the reagent added
addition_type	String	Type of addition (e.g., "Reagent Bolus", "Feed Start", "Induction", "Inoculation")
volume	Object	{unit: string, value: number}

DbRemovalEvent

Field	Type	Description
volume	Object	{unit: string, value: number}
lot_number	String or null	Lot number associated with the removal
sample_name	String or null	Name or identifier of the sample removed
removal_type	String	Type of removal (e.g., "Sample", "Harvest")

DbBioprocessPhaseEvent

Field	Type	Description
phase	String	Name of the bioprocess phase (e.g., "growth", "production")
time_point	String	Indicator of the phase timing (e.g., "start", "end")

v_timeseries

curl -H "Authorization: Bearer <AUTH0_TOKEN>" \
 -H "Content-Type: application/json" \
 -X POST \
 -d '{"statement": "SELECT * FROM v_timeseries LIMIT 1"}' \
 https://api.invertbio.com/external/v1/statements/

Field Name	Type	Description
id	String	Unique identifier for the timeseries
bioprocess_id	String	Identifier of the associated bioprocess
quantity_id	String	Identifier of the associated quantity
start_timestamp	String	Start time (ISO 8601 with timezone)
end_timestamp	String	End time (ISO 8601 with timezone)
duration_ms	Number	Duration in milliseconds
unit	String	Unit of measurement
statistics	Object	Statistical summary (see below)
last_updated_at	String	Timestamp of last update (ISO 8601)

statistics object:

Field	Type	Description
max	Number or null	Maximum value
min	Number or null	Minimum value
sum	Number	Sum of all values
last	Number or null	Last value
count	Number	Number of data points
first	Number or null	First value
arithmetic_mean	Number or null	Average of all values
standard_deviation	Number or null	Standard deviation

v_timeseries_data

curl -H "Authorization: Bearer <AUTH0_TOKEN>" \
 -H "Content-Type: application/json" \
 -X POST \
 -d '{"statement": "SELECT * FROM v_timeseries_data LIMIT 1"}' \
 https://api.invertbio.com/external/v1/statements/

Field Name	Type	Description
id	String	Identifier of the timeseries this data point belongs to (ref to v_timeseries.id)
timestamp	String	Timestamp of the data point (ISO 8601)
value	Number or null	The recorded value at this timestamp
data_item_id	String or null	Optional identifier for the specific data item

v_quantities

curl -H "Authorization: Bearer <AUTH0_TOKEN>" \
 -H "Content-Type: application/json" \
 -X POST \
 -d '{"statement": "SELECT * FROM v_quantities LIMIT 1"}' \
 https://api.invertbio.com/external/v1/statements/

Field Name	Type	Description
id	String	Unique identifier
name	String	Primary name of the quantity
alternative_names	Array of Strings	List of alternative names
is_timeseries	Boolean	Whether this quantity represents time series data
data_type	String	The data type
default_unit	String	The default display unit
default_ingestion_unit	String	The default unit used when ingesting data
base_units	Object	Base units object
molar_mass	Number or null	The molar mass, if applicable
notes	String or null	Additional notes
last_updated_at	String	Timestamp of last update (ISO 8601)

v_formulas

curl -H "Authorization: Bearer <AUTH0_TOKEN>" \
 -H "Content-Type: application/json" \
 -X POST \
 -d '{"statement": "SELECT * FROM v_formulas LIMIT 1"}' \
 https://api.invertbio.com/external/v1/statements/

Field Name	Type	Description
id	String	Unique identifier
name	String	Name of the formula
formula	String	The actual formula/calculation
log_scale	Boolean	Whether to apply on a logarithmic scale
disable_interpolation	Boolean	Whether interpolation is disabled
default_unit	String or null	Default unit for the result
run_phase	String or null	Phase during which this formula is applicable
notes	String or null	Additional notes
state	String	Current state (e.g., "ready")
last_updated_at	String	Timestamp of last update (ISO 8601)

Example formula types:

1. Simple references: A, B
2. Basic arithmetic: (A+B+C)/3, A+B
3. More complex: (A*3)*B/100
4. Time-based: time_derivative_hours(A), time_integral_hours(A*2)
5. Advanced statistical: log_linear_regression(A)

v_formula_results

Field Name	Type	Description
id	String	Unique identifier
formula_id	String	Identifier of the formula used
bioprocess_id	String	Identifier of the associated bioprocess
unit	String	Unit of measurement
data	Object or null	Single value result (if not a time series)
timeseries	Object or null	Time series data (if formula produces multiple values)
timeseries_start_timestamp	String	Start time of the time series
timeseries_offset_ms	Number	Time offset in milliseconds
timeseries_statistics_min	Number	Minimum value
timeseries_statistics_max	Number	Maximum value
timeseries_statistics_arithmetic_mean	Number	Arithmetic mean
timeseries_statistics_standard_deviation	Number	Standard deviation
timeseries_statistics_sum	Number	Sum of all values
timeseries_statistics_first	Number	First value
timeseries_statistics_last	Number	Last value
timeseries_statistics_count	Number	Number of data points
last_updated_at	String	Timestamp of last update

When timeseries is not null: {data: Array<Number>, times_ms: Array<Number>}

v_archived_records

Field Name	Type	Description
record_id	String	Unique identifier for the archived record
table_name	String	Name of the source table
archived_at	String	Timestamp of archival (ISO 8601)

v_experiments

Field Name	Type	Description
id	String	Unique identifier
external_id	String	An external identifier
scheduled_start_timestamp	String or null	Scheduled start time (ISO 8601)
scheduled_end_timestamp	String or null	Scheduled end time (ISO 8601)
last_updated_at	String	Timestamp of last update (ISO 8601)

Example Queries

Delta Loads

Request data produced after a given date:

curl -H "Authorization: Bearer <ACCESS_TOKEN>" \
 -H "Content-Type: application/json" \
 -X POST \
 -d '{"statement": "SELECT * FROM v_bioprocesses WHERE last_updated_at > '"'"'2024-07-29'"'"' LIMIT 1"}' \
 https://api.invertbio.com/external/v1/statements/

Get timeseries updated since a bioprocess was last updated:

curl -H "Authorization: Bearer <ACCESS_TOKEN>" \
 -H "Content-Type: application/json" \
 -X POST \
 -d '{"statement": "SELECT * FROM v_timeseries WHERE last_updated_at > (SELECT MAX(last_updated_at) FROM v_bioprocesses)"}' \
 https://api.invertbio.com/external/v1/statements/

View Joins

Get bioprocesses associated to a timeseries:

curl -H "Authorization: Bearer <ACCESS_TOKEN>" \
 -H "Content-Type: application/json" \
 -X POST \
 -d '{"statement": "SELECT t.*, b.* FROM v_timeseries t LEFT JOIN v_bioprocesses b ON t.bioprocess_id = b.id LIMIT 1"}' \
 https://api.invertbio.com/external/v1/statements/

Error States

Timeouts

Long running requests (>30 seconds) will be terminated and return a 504. Modify your query to reduce/chunk the amount of data.

SQL execution errors

No data returned:

{
  "data": [],
  "status": {
    "state": "success",
    "message": "Statement executed successfully, but returned no results."
  }
}

Non-existent view:

{
  "data": [],
  "status": {
    "state": "error",
    "message": "relation \"v_non_existent_view\" does not exist"
  }
}

Syntax errors: JSON decode error — be careful about use of single vs double quotation marks.

Unexpected exceptions

{
  "data": [],
  "status": {
    "state": "error",
    "message": "Error executing statement"
  }
}

The DSP external API provides SQL access to material streams, unit operations, and bioprocess data. See Authentication for how to obtain an access token.

Available Views (DSP)

The DSP API exposes all the same views as the upstream API (v_bioprocesses, v_timeseries, v_timeseries_data, v_quantities, v_formulas, v_formula_results, v_experiments), plus the following additional views:

v_material_streams

curl -H "Authorization: Bearer <AUTH0_TOKEN>" \
 -H "Content-Type: application/json" \
 -X POST \
 -d '{"statement": "SELECT * FROM v_material_streams LIMIT 1"}' \
 https://api.invertbio.com/external/v1/statements/

Field Name	Type	Description
id	String	Unique identifier
name	String	Name of the material stream
start_timestamp	String or null	Start time (ISO 8601)
end_timestamp	String or null	End time (ISO 8601)
unit_operation_id	String or null	Identifier of the associated unit operation
is_global_material_stream	Boolean	true = data belonging to a unit operation; false = material stream data
data	Array	List of data objects
last_updated_at	String	Timestamp of last update (ISO 8601)

v_unit_operations

curl -H "Authorization: Bearer <AUTH0_TOKEN>" \
 -H "Content-Type: application/json" \
 -X POST \
 -d '{"statement": "SELECT * FROM v_unit_operations LIMIT 1"}' \
 https://api.invertbio.com/external/v1/statements/

Field Name	Type	Description
id	String	Unique identifier
external_id	String	External identifier
name	String	Name of the unit operation
experiment_id	String or null	Identifier of the associated experiment
run_start_timestamp	String or null	Start time of the run
run_end_timestamp	String or null	End time of the run
status	String	Draft / Requested / Scheduled / In-progress / Completed
qc_status	String	Quality control status
qc_failure_mode	String	Quality control failure mode
unit_operation_type_id	Object or null	Identifier of the associated unit operation type
last_updated_at	String	Timestamp of last update (ISO 8601)

v_unit_operation_types

curl -H "Authorization: Bearer <AUTH0_TOKEN>" \
 -H "Content-Type: application/json" \
 -X POST \
 -d '{"statement": "SELECT * FROM v_unit_operation_types LIMIT 1"}' \
 https://api.invertbio.com/external/v1/statements/

Field Name	Type	Description
id	String	Unique identifier
name	String	Name of the unit operation type
icon	String or null	Name of the icon
last_updated_at	String	Timestamp of last update (ISO 8601)

Example Queries and Error States

Queries, delta load patterns, view joins, and error state handling are identical between the Core and DSP views. See Core views for details.