{"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","img"]},"type":"markdown"},"seo":{"title":"Working with labware and deck configuration","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":"working-with-labware-and-deck-configuration"},"children":["Working with labware and deck configuration"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Understanding labware and deck configuration is essential for creating and running protocols on the Prep. This guide explains how to query available labware, understand labware properties, work with deck positions, and manage labware in protocols via the API."]},{"$$mdtype":"Tag","name":"section","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{"className":"note"},"children":["Before creating protocols, familiarize yourself with the available labware in your system and their properties to ensure that the appropriate labware is selected for your application."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"id":"53272462475","level":2},"children":["About labware "]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Labware represents the physical plates, tip racks, and other items used on the Prep deck. Each labware item has specific properties that define its characteristics and capabilities."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"id":"53272467083","level":3},"children":["Key concepts "]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["When working with labware via the API:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Name vs DisplayName"]},": The ",{"$$mdtype":"Tag","name":"span","attributes":{"className":"item"},"children":["Name"]}," field is the unique identifier used in API calls, while ",{"$$mdtype":"Tag","name":"span","attributes":{"className":"item"},"children":["DisplayName"]}," is the human-readable name for display purposes."]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["ID-based references"]},": Each labware has a unique numeric ",{"$$mdtype":"Tag","name":"span","attributes":{"className":"item"},"children":["ID"]}," that can be used to reference it."]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Classification"]},": Labware is categorized by type (e.g., Plate, TipRack, Trough) which determines how it can be used in protocols."]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Dimensions"]},": The ",{"$$mdtype":"Tag","name":"span","attributes":{"className":"item"},"children":["Rows"]}," and ",{"$$mdtype":"Tag","name":"span","attributes":{"className":"item"},"children":["Columns"]}," properties define the grid layout (e.g., 8×12 for a 96-well plate)."]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Volume capacity"]},": The ",{"$$mdtype":"Tag","name":"span","attributes":{"className":"item"},"children":["Volume"]}," property indicates the capacity of wells or containers."]}]}]},{"$$mdtype":"Tag","name":"section","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{"className":"note"},"children":["For a complete list of labware properties, refer to the ",{"$$mdtype":"Tag","name":"span","attributes":{"className":"item"},"children":["LabwareSummaryDto"]}," and ",{"$$mdtype":"Tag","name":"span","attributes":{"className":"item"},"children":["LabwareDto"]}," schemas in the ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"https://developer.hamiltoncompany.com/products/prep/api/openapi","target":"_blank"},"children":["ML Prep OpenAPI documentation"]},"."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"id":"53272454539","level":2},"children":["Retrieving labware information "]},{"$$mdtype":"Tag","name":"Heading","attributes":{"id":"53272468235","level":3},"children":["Get all available labware "]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Retrieve the complete catalog of labware available in your system using the ",{"$$mdtype":"Tag","name":"span","attributes":{"className":"item"},"children":["GetLabware"]}," endpoint. This returns a summary of all labware with their IDs, names, classifications, and key properties."]},{"$$mdtype":"Tag","name":"section","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{"className":"note"},"children":["The labware catalog can contain many items, which may slow down the call. Cache this data, when possible, to regularly access the list of all labware."]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Split","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use this endpoint to:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Discover available labware before creating protocols."]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Build a labware selection interface in your application."]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Filter labware by classification or other properties."]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Populate a local cache of available labware."]}]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"OpenApiCodeSample","attributes":{"descriptionFile":"oas-products/prep/api/openapi.yaml","operationId":"GetLabware","parameters":{},"environments":{}},"children":[]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"id":"53272469387","level":3},"children":["Get labware by name "]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["After accessing the specific labware name, use the ",{"$$mdtype":"Tag","name":"span","attributes":{"className":"item"},"children":["GetLabwareByName"]}," endpoint to retrieve its details directly."]},{"$$mdtype":"Tag","name":"Image","attributes":{"src":"/assets/labware-name.2e78826ace7dd443ece5e546d440208d1d523272ee8128400e1cc2316cb9e5a5.86b22610.png","alt":"labware-name","withLightbox":false,"width":"40%"},"children":[]},{"$$mdtype":"Tag","name":"Split","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The name must match exactly as it appears in the system. This endpoint is useful when:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A labware name in the Prep software is known."]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Using standardized labware across multiple protocols."]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Validating that a specific labware exists."]}]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"OpenApiCodeSample","attributes":{"descriptionFile":"oas-products/prep/api/openapi.yaml","operationId":"GetLabwareByName","parameters":{},"environments":{}},"children":[]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"id":"53272534539","level":3},"children":["Get labware by ID "]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["After accessing the numeric labware ID, use the ",{"$$mdtype":"Tag","name":"span","attributes":{"className":"item"},"children":["GetLabwareById"]}," endpoint to retrieve the full labware details."]},{"$$mdtype":"Tag","name":"Split","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This is the preferred method when:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Labware IDs were cached from a previous catalog query."]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Labware references are stored in your application."]}]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"OpenApiCodeSample","attributes":{"descriptionFile":"oas-products/prep/api/openapi.yaml","operationId":"GetLabwareById","parameters":{},"environments":{}},"children":[]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"id":"53272495115","level":2},"children":["About deck positions "]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The Prep deck consists of eight positions arranged in a specific layout. When creating protocols via the API, specify which labware occupies each deck position."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"id":"53272535691","level":3},"children":["Deck layout "]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Deck positions are numbered from 1 to 8:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Positions 1-4"]},": Left column (top to bottom)"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Positions 5-8"]},": Right column (top to bottom)"]}]}]},{"$$mdtype":"Tag","name":"section","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{"className":"note"},"children":["Not all positions need to be filled for every protocol. Exclude any empty positions from the deck configuration."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"id":"53272536843","level":3},"children":["Planning the deck layout "]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Consider the following when planning the deck configuration programmatically:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Physical restrictions"]},": Some labware have specific placement requirements (e.g., tip pedestals for framed tip racks)."]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Accessibility"]},": Consider pipetting head movement patterns for efficient access to frequently used labware."]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"id":"53272537995","level":2},"children":["Working with labware in protocols "]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["When creating a protocol via the API, specify the deck configuration, including which labware is placed at each position."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"id":"53272539147","level":3},"children":["Labware groups "]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Labware groups are containers that associate labware with additional metadata and configuration. Every labware placed on the deck must be part of a labware group, even if it's a single item."]},{"$$mdtype":"Tag","name":"section","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{"className":"note"},"children":["For tip racks, labware groups are commonly called \"tip groups\" and have special significance for tip reuse behavior. Go to ",{"$$mdtype":"Tag","name":"a","attributes":{"className":"schema-iframe-link","href":"prep_guide_tip_groups"},"children":["Working with tip groups"]}," for more information."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"id":"53272540299","level":3},"children":["Deck configuration structure "]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The deck configuration consists of an array of positions, each containing:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"span","attributes":{"className":"item"},"children":["Position"]},": The deck position number (1-8)."]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"span","attributes":{"className":"item"},"children":["PositionName"]},": A descriptive name for the position in this protocol."]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"span","attributes":{"className":"item"},"children":["LabwareGroup"]},": The labware group object containing the labware and its configuration."]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"span","attributes":{"className":"item"},"children":["LiquidVolume"]},": The amount of liquid in the position."]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"span","attributes":{"className":"item"},"children":["LabwarePositions"]},": For tube racks or trough carriers, this array represents each slot for tubes or troughs."]}]}]},{"$$mdtype":"Tag","name":"section","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{"className":"note"},"children":["Refer to the ",{"$$mdtype":"Tag","name":"span","attributes":{"className":"item"},"children":["DeckPositionPostPutDto"]}," and ",{"$$mdtype":"Tag","name":"span","attributes":{"className":"item"},"children":["LabwareGroupPostPutDto"]}," schemas in the ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"https://developer.hamiltoncompany.com/products/prep/api/openapi","target":"_blank"},"children":["ML Prep OpenAPI documentation"]}," for details."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"id":"53272541451","level":3},"children":["Example: Creating a protocol with labware "]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["When creating a protocol, specify labware groups for each occupied deck position:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":" {\n  \"name\": \"Sample Protocol\",\n  \"deck\": {\n   \"positions\": [\n    {\n     \"position\": 2,\n     \"positionName\": \"Tip Rack\",\n     \"labwareGroup\": {\n      \"groupName\": \"300uL Tips\",\n      \"labwareId\": 123,\n      \"reuseTipsBetweenSteps\": false\n     }\n    },\n    {\n     \"position\": 6,\n     \"positionName\": \"Reagent Resevior\",\n     \"labwareGroup\": {\n      \"groupName\": \"reagent\",\n      \"labwareId\": 456,\n      \"liquidName\": \"reagent\",\n      \"liquidType\": \"Aqueous\"\n     }\n    }\n   ]\n  }\n }\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For detailed examples of protocol creation workflows, go to ",{"$$mdtype":"Tag","name":"a","attributes":{"className":"schema-iframe-link","href":"prep_recipe_protocol_create"},"children":["Create a Prep protocol"]},"."]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"id":"53272542603","level":2},"children":["Best practices "]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["When working with labware and deck configuration via the API:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Cache labware data"]},": Query the labware catalog once and cache the results to reduce API calls and improve performance."]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Check labware properties"]},": Verify that labware dimensions and volume capacity match your protocol requirements."]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Consider physical constraints"]},": Be aware of labware-specific placement requirements."]}]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"id":"53272543755","level":2},"children":["Related Resources "]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"a","attributes":{"className":"schema-iframe-link","href":"prep_recipe_protocol_create"},"children":["Create a Prep protocol"]}]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"a","attributes":{"className":"schema-iframe-link","href":"prep_recipe_protocol_start"},"children":["Start a protocol run"]}]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"a","attributes":{"className":"schema-iframe-link","href":"prep_guide_tip_groups"},"children":["Working with tip groups"]}]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"a","attributes":{"className":"schema-iframe-link","href":"prep_guide_access_swagger"},"children":["Access OpenAPI documentation"]}]}]}]}]},"headings":[{"value":"Working with labware and deck configuration","id":"working-with-labware-and-deck-configuration","depth":1},{"value":"About labware","id":"53272462475","depth":2},{"value":"Key concepts","id":"53272467083","depth":3},{"value":"Retrieving labware information","id":"53272454539","depth":2},{"value":"Get all available labware","id":"53272468235","depth":3},{"value":"Get labware by name","id":"53272469387","depth":3},{"value":"Get labware by ID","id":"53272534539","depth":3},{"value":"About deck positions","id":"53272495115","depth":2},{"value":"Deck layout","id":"53272535691","depth":3},{"value":"Planning the deck layout","id":"53272536843","depth":3},{"value":"Working with labware in protocols","id":"53272537995","depth":2},{"value":"Labware groups","id":"53272539147","depth":3},{"value":"Deck configuration structure","id":"53272540299","depth":3},{"value":"Example: Creating a protocol with labware","id":"53272541451","depth":3},{"value":"Best practices","id":"53272542603","depth":2},{"value":"Related Resources","id":"53272543755","depth":2}],"frontmatter":{"seo":{"title":"Working with labware and deck configuration"}},"lastModified":"2026-07-30T19:22:04.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/pages/prep_guide_labware_management","userData":{"isAuthenticated":false,"teams":["anonymous"]}}