API Reference

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.

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/

Common Event Types

DbObservationEvent

DbAdditionEvent

DbRemovalEvent

DbBioprocessPhaseEvent

v_bioprocess_quantity_data

A flat, top-level view of per-bioprocess quantity data — one row per (bioprocess, quantity).

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

Join to bioprocesses via v_bioprocess_quantity_data.bioprocess_id = v_bioprocesses.id.

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/

statistics object:

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/

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/

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/

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

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

v_archived_records

v_experiments

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"
  }
}

Available Views (DSP)

The DSP API exposes all the same views as the upstream API (v_bioprocesses, v_bioprocess_quantity_data, 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/

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/

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/

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.