Skip to content
Recipes
/
Getting started
Last updated

Getting started

This page provides the simplest path for quickly using the API to get a protocol running.

Establish connection

Perform this GET request to determine if the API is available and ready to accept other requests.

Go to Check if the system is ready for more information.

curl -i -X GET \
  'http://{{your_prep_ip_address}}/api/v1/system-ready' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'
Response
No response example

Verify that user management is enabled

Before continuing, verify that user management is enabled to determine whether authentication is necessary.

If user management is disabled, authentication can be skipped.

Go to Enable or disable user management for more information.

curl -i -X GET \
  'http://{{your_prep_ip_address}}/api/v1/settings/enable-user-management' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'
Response
application/json
"string"

Authenticate

Authenticate a user for privileged, actionable operations (e.g., running protocols). Go to the Authentication recipe for more information about authenticating.

If user management is disabled, skip this step.

Go to Authenticate the user for more information.

curl -i -X POST \
  'http://{{your_prep_ip_address}}/api/v1/authenticate' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json-patch+json' \
  -d '{
    "username": "string",
    "password": "string"
  }'
Response
application/json
{
  "userName": "_userName1_",
  "userId": "1142c805484f4ffb9f1b92a66b47ef71",
  "token": "Z5UmVtb3RlU2V0dGluZ3MiLCJNb2RpZnlCYXNlU2V0dGluZ3MiLCJNb2RpZnlUZWNobmljYWxTZXR0aW5ncyIsIkV4ZWN1dGVWYWxpZGF0ZWRJdGVtcyIsIkV4ZWN1dGVOb25WYWxpZGF0ZWRJdGVtcyIsIkVkaXRTY2hlZHVsZSIsIlZpZXdGdW5jdGlvbnMiLCJWaWV3VXNlcnMiLCJWaWV3Um9sZXMiLCJNb2RpZnlQcmludFNldHRpbmdzIiwiQ3JlYXRlVXNlckRvY3VtZW50cyIsIyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJuYW1laWQiOiIzMTQyOGM4ZmQ0Yzk0MzljYmI3NTAzYzdiMGViOTU0MCIsImdpdmVuX25hbWUiOiJfX21scHJlcF9fIiwicm9sZSI6WyJDaGFuZ2VBY3RpdmVTeXN0ZW1Db25maWd1cmF0aW9uIiwiTW9kaWZ5Um9sZXMiLCJNb2RpZnlVc2VycyIsIk1vZGlmeUxhYm9yYXRvcnlTZXR0aW5ncyIsIk1vZGlmeVYmTVNldHRpbmdzIiwiTW9k",
  "inactiveLogout": 60,
  "logoutCountdown": 10,
  "expiresIn": 5,
  "passwordExpiresInDays": 0,
  "notifyPasswordExpiresSoon": false
}

Retrieve protocol list

Before running a protocol, review the protocols in the system to obtain the protocol ID of the desired protocol to run.

Go to Retrieve the list of protocols for more information.

curl -i -X GET \
  'http://{{your_prep_ip_address}}/api/v1/protocols' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'
Response
application/json
[
  {
    "id": 0,
    "name": "string",
    "favorite": true,
    "dateModified": "2019-08-24T14:15:22Z",
    "dateRun": "2019-08-24T14:15:22Z"
  }
]

Create a protocol run

Creating a protocol run prepares the system for protocol execution and loads the deck. Use a protocol ID found in the protocol list to send this request.

curl -i -X POST \
  'http://{{your_prep_ip_address}}/api/v1/protocol-run/create' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json-patch+json' \
  -d '{
    "protocolId": 0,
    "simulate": true,
    "recompile": true
  }'
Response
No content

Poll run state

Before loading the deck, verify that the Prep software has finished preparing the protocol run. Wait until protocolRunState changes to 20, meaning it is in the loading state.

A more advanced and efficient approach for this would be listening for events to determine when the correct state is reached.

Go to Get the current run status for more information.

curl -i -X GET \
  'http://{{your_prep_ip_address}}/api/v1/protocol-run' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'
Response
application/json
{
  "protocolId": 0,
  "runDatalId": "string",
  "isRunInProgress": true,
  "isSimulation": true,
  "protocolRunState": "Idle",
  "startTime": "2019-08-24T14:15:22Z",
  "estimatedEndTime": "2019-08-24T14:15:22Z",
  "endPauseTime": "2019-08-24T14:15:22Z",
  "protocolName": "string",
  "currentStep": 0,
  "preLoadThermalDeviceUsed": "Hhs",
  "preLoadHepaFiltration": true
}

Get load instructions

Retrieve the load instructions to verify the labware the protocol is expecting.

Go to Retrieve the load instructions for more information.

curl -i -X GET \
  'http://{{your_prep_ip_address}}/api/v1/protocol-run' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'
Response
application/json
{
  "protocolId": 0,
  "runDatalId": "string",
  "isRunInProgress": true,
  "isSimulation": true,
  "protocolRunState": "Idle",
  "startTime": "2019-08-24T14:15:22Z",
  "estimatedEndTime": "2019-08-24T14:15:22Z",
  "endPauseTime": "2019-08-24T14:15:22Z",
  "protocolName": "string",
  "currentStep": 0,
  "preLoadThermalDeviceUsed": "Hhs",
  "preLoadHepaFiltration": true
}

Complete protocol loading

After labware is properly loaded onto the deck, complete protocol loading to start executing the run.

Go to Complete the loading for the run for more information.

curl -i -X PUT \
  'http://{{your_prep_ip_address}}/api/v1/protocol-run/load-complete' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "protocolId": 0,
    "simulate": true,
    "loadCompleteAction": "Run",
    "residualTips": [
      {
        "deckPosition": 0,
        "residualTipData": {
          "useAllAddresses": true,
          "addresses": [
            {
              "row": 1,
              "column": 1
            }
          ]
        }
      }
    ],
    "barcodes": [
      {
        "deckPosition": 0,
        "address": {
          "row": 0,
          "column": 0
        },
        "barcodeValue": "string"
      }
    ],
    "liquidVolumes": [
      {
        "deckPosition": 0,
        "positionOnSite": 0,
        "row": 0,
        "column": 0,
        "volume": 0.1
      }
    ]
  }'
Response
No content

Poll protocol status until completion

After all steps have been followed, wait for protocol execution to complete. Poll for the protocolRunState to be 0 (idle), or until isRunInProgress is false.

A more advanced and efficient approach for this would be listening for events to determine when the correct state is reached.

Go to Get the current run status for more information.

curl -i -X GET \
  'http://{{your_prep_ip_address}}/api/v1/protocol-run' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'
Response
application/json
{
  "protocolId": 0,
  "runDatalId": "string",
  "isRunInProgress": true,
  "isSimulation": true,
  "protocolRunState": "Idle",
  "startTime": "2019-08-24T14:15:22Z",
  "estimatedEndTime": "2019-08-24T14:15:22Z",
  "endPauseTime": "2019-08-24T14:15:22Z",
  "protocolName": "string",
  "currentStep": 0,
  "preLoadThermalDeviceUsed": "Hhs",
  "preLoadHepaFiltration": true
}
Previous page
Next page