{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-products/prep/sidebars.yaml","oas-products/prep/api/openapi.yaml":"oas-products/prep/api/openapi.yaml"},"props":{"metadata":{"markdoc":{"tagList":["split","openapi-code-sample"]},"type":"markdown"},"seo":{"title":"Getting started","description":"Hamilton's Developer Portal is used to help reference and understand the APIs of Hamilton products.","llmstxt":{"hide":false,"sections":[{"title":"Table of contents","includeFiles":["**/*"],"excludeFiles":[]}],"excludeFiles":[]}},"dynamicMarkdocComponents":["openapi"],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"getting-started"},"children":["Getting started"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This page provides the simplest path for quickly using the API to get a protocol running."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"id":"51665787787","level":2},"children":["Establish connection "]},{"$$mdtype":"Tag","name":"Split","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Perform this GET request to determine if the API is available and ready to accept other requests."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Go to ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"https://developer.hamiltoncompany.com/products/prep/api/openapi/systemready","target":"_blank"},"children":["Check if the system is ready"]}," for more information."]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"OpenApiCodeSample","attributes":{"descriptionFile":"oas-products/prep/api/openapi.yaml","operationId":"SystemReady","parameters":{},"environments":{}},"children":[]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"id":"51666160395","level":2},"children":["Verify that user management is enabled "]},{"$$mdtype":"Tag","name":"Split","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Before continuing, verify that user management is enabled to determine whether authentication is necessary."]},{"$$mdtype":"Tag","name":"section","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{"className":"note"},"children":["If user management is disabled, authentication can be skipped."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Go to ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"https://developer.hamiltoncompany.com/products/prep/api/openapi/settings/updateenableusermanagement","target":"_blank"},"children":["Enable or disable user management"]}," for more information."]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"OpenApiCodeSample","attributes":{"descriptionFile":"oas-products/prep/api/openapi.yaml","operationId":"GetEnableUserManagement","parameters":{},"environments":{}},"children":[]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"id":"51666161547","level":2},"children":["Authenticate "]},{"$$mdtype":"Tag","name":"Split","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Authenticate a user for privileged, actionable operations (e.g., running protocols). Go to the ",{"$$mdtype":"Tag","name":"a","attributes":{"className":"schema-iframe-link","href":"prep_recipe_authentication"},"children":["Authentication"]}," recipe for more information about authenticating."]},{"$$mdtype":"Tag","name":"section","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{"className":"note"},"children":["If user management is disabled, skip this step."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Go to ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"https://developer.hamiltoncompany.com/products/prep/api/openapi/authenticate/authenticate","target":"_blank"},"children":["Authenticate the user"]}," for more information."]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"OpenApiCodeSample","attributes":{"descriptionFile":"oas-products/prep/api/openapi.yaml","operationId":"AuthenticateUser","parameters":{},"environments":{}},"children":[]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"id":"51666163467","level":2},"children":["Retrieve protocol list "]},{"$$mdtype":"Tag","name":"Split","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Before running a protocol, review the protocols in the system to obtain the protocol ID of the desired protocol to run."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Go to ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"https://developer.hamiltoncompany.com/products/prep/api/openapi/protocols/getprotocolsummaries","target":"_blank"},"children":["Retrieve the list of protocols"]}," for more information."]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"OpenApiCodeSample","attributes":{"descriptionFile":"oas-products/prep/api/openapi.yaml","operationId":"GetProtocolSummaries","parameters":{},"environments":{}},"children":[]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"id":"51702076043","level":2},"children":["Create a protocol run "]},{"$$mdtype":"Tag","name":"Split","attributes":{},"children":[{"$$mdtype":"Tag","name":"div","attributes":{"className":"textmodule","id":"51702114443"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["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."]}]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"textmodule","id":"52750798603"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Go to ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"https://developer.hamiltoncompany.com/products/prep/api/openapi/protocolrun/createrun","target":"_blank"},"children":["Create a new run, schedule, and populate load instructions"]}," for more information."]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"OpenApiCodeSample","attributes":{"descriptionFile":"oas-products/prep/api/openapi.yaml","operationId":"CreateRun","parameters":{},"environments":{}},"children":[]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"id":"51666166283","level":2},"children":["Poll run state "]},{"$$mdtype":"Tag","name":"Split","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Before loading the deck, verify that the Prep software has finished preparing the protocol run. Wait until ",{"$$mdtype":"Tag","name":"span","attributes":{"className":"item"},"children":["protocolRunState"]}," changes to ",{"$$mdtype":"Tag","name":"span","attributes":{"className":"value"},"children":["20"]},", meaning it is in the loading state. "]},{"$$mdtype":"Tag","name":"section","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{"className":"note"},"children":["A more advanced and efficient approach for this would be listening for events to determine when the correct state is reached."]}]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"textmodule","id":"52750845835"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Go to ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"https://developer.hamiltoncompany.com/products/prep/api/openapi/protocolrun/getrunstatus","target":"_blank"},"children":["Get the current run status"]}," for more information."]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"OpenApiCodeSample","attributes":{"descriptionFile":"oas-products/prep/api/openapi.yaml","operationId":"GetRunStatus","parameters":{},"environments":{}},"children":[]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"id":"51702097547","level":2},"children":["Get load instructions "]},{"$$mdtype":"Tag","name":"Split","attributes":{},"children":[{"$$mdtype":"Tag","name":"div","attributes":{"className":"textmodule","id":"52750837515"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Retrieve the load instructions to verify the labware the protocol is expecting. "]}]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"textmodule","id":"52750833547"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Go to ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"https://developer.hamiltoncompany.com/products/prep/api/openapi/protocolrun/getloadinstructions","target":"_blank"},"children":["Retrieve the load instructions"]},{"$$mdtype":"Tag","name":"a","attributes":{"href":"https://developer.hamiltoncompany.com/products/prep/api/openapi/protocolrun/getloadinstructions","target":"_blank"},"children":[]}," for more information."]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"OpenApiCodeSample","attributes":{"descriptionFile":"oas-products/prep/api/openapi.yaml","operationId":"GetRunStatus","parameters":{},"environments":{}},"children":[]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"id":"51702168843","level":2},"children":["Complete protocol loading "]},{"$$mdtype":"Tag","name":"Split","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["After labware is properly loaded onto the deck, complete protocol loading to start executing the run."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Go to ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"https://developer.hamiltoncompany.com/products/prep/api/openapi/protocolrun/loadcomplete","target":"_blank"},"children":["Complete the loading for the run"]}," for more information."]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"OpenApiCodeSample","attributes":{"descriptionFile":"oas-products/prep/api/openapi.yaml","operationId":"LoadComplete","parameters":{},"environments":{}},"children":[]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"id":"51702188683","level":2},"children":["Poll protocol status until completion "]},{"$$mdtype":"Tag","name":"Split","attributes":{},"children":[{"$$mdtype":"Tag","name":"div","attributes":{"className":"textmodule","id":"51702116875"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["After all steps have been followed, wait for protocol execution to complete. Poll for the ",{"$$mdtype":"Tag","name":"span","attributes":{"className":"item"},"children":["protocolRunState"]}," to be ",{"$$mdtype":"Tag","name":"span","attributes":{"className":"value"},"children":["0"]}," (idle), or until ",{"$$mdtype":"Tag","name":"span","attributes":{"className":"item"},"children":["isRunInProgress"]}," is ",{"$$mdtype":"Tag","name":"span","attributes":{"className":"value"},"children":["false"]},". "]},{"$$mdtype":"Tag","name":"section","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{"className":"note"},"children":["A more advanced and efficient approach for this would be listening for events to determine when the correct state is reached."]}]}]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"textmodule","id":"52750845835"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Go to ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"https://developer.hamiltoncompany.com/products/prep/api/openapi/protocolrun/getrunstatus","target":"_blank"},"children":["Get the current run status"]}," for more information."]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"OpenApiCodeSample","attributes":{"descriptionFile":"oas-products/prep/api/openapi.yaml","operationId":"GetRunStatus","parameters":{},"environments":{}},"children":[]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]}]},"headings":[{"value":"Getting started","id":"getting-started","depth":1},{"value":"Establish connection","id":"51665787787","depth":2},{"value":"Verify that user management is enabled","id":"51666160395","depth":2},{"value":"Authenticate","id":"51666161547","depth":2},{"value":"Retrieve protocol list","id":"51666163467","depth":2},{"value":"Create a protocol run","id":"51702076043","depth":2},{"value":"Poll run state","id":"51666166283","depth":2},{"value":"Get load instructions","id":"51702097547","depth":2},{"value":"Complete protocol loading","id":"51702168843","depth":2},{"value":"Poll protocol status until completion","id":"51702188683","depth":2}],"frontmatter":{"seo":{"title":"Getting started"}},"lastModified":"2026-07-30T19:22:04.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/pages/prep_recipe_getting_started","userData":{"isAuthenticated":false,"teams":["anonymous"]}}