Sereact logo

API Reference

Welcome to the Capto API Manual, your go-to resource for setting up and utilizing the Capto API to manage system behavior and robot tasks. This API adheres to the JSON-RPC 2.0 Specification, accessible at https://www.jsonrpc.org/specification, and operates through a single HTTP POST endpoint for sending commands with parameters. All API calls are synchronous, blocking until the system completes the execution of the specified function.

API Entryoint

  • URL: http://<ip_address>:<port>/api
    • ip_address: The ip_address is the address of the executing machine, it can also be the localhost
    • port: The port for calling API. The default value is 5000
    • Example URL: http://localhost:5000/api
  • HTTP Method: POST

Robot - Homing

This API call will get the robot to the homing position with a specific speed.

Request Payload

{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "robot.homing",
    "params": {
        "speed": 50
    }
}

Parameters

  • Method:: Specifies the action to be performed by the robot. Set to "robot.homing" for initiating the homing process.
  • params (object): Contains specific parameters for the homing action.
    • speed (integer): Speed at which the robot should execute the homing process.

Example Request

import requests

res = requests.post("http://localhost:5000/api", json={
    "method": "robot.homing",
    "params": {
        "speed": 50
    }
})

Expected Result

{
    "jsonrpc": "2.0",
    "result": {
        "success": true,
    }
}
  • After the call, robot should go to homing position:
    • success: A boolean indicating whether the API method was called successful.

Robot - Call Grasp

This method will call the robot grasp from a bin and place to another bin.

Request Payload

{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "robot.grasp",
    "params": {
        "speed": 40,
        "no_items": 2,
        "pick_area": "pick_1",
        "place_area": "place_1",
        "metadata":
        {
            "tote_barcode": "abc",
        }
    }
}
  • Method: robot.grasp
  • Params:
    • no_items (integer): Number of items the robot should grasp and subsequently place.
    • place_area (string): Designated area for placing the grasped items.
    • pick_area (string): Designated area for picking items.
    • speed (float): Speed at which the robot should execute the grasp action, the speed is in percentage (0%-100%).
    • metadata (object): Additional metadata for the task.
      • tote_barcode (string): Barcode associated with the tote or container.

Example Request (Python)

import requests

speed = 10  # Replace with the desired speed value
res = requests.post("http://localhost:5000/api", json={
    "jsonrpc": "2.0",
    "id": 1,
    "method": "robot.grasp",
    "params": {
        "no_items": 2,
        "place_area": "place_1",
        "pick_area": "pick_1",
        "speed": speed,
        "metadata": {
        }
    }
})

Expected Result

{
    "jsonrpc": "2.0",
    "result": {
        "success": true,
        "payload": {
            "picks": [
                {
                    "id": "ffc69c1b-9d87-4c19-8dac-c09ca857e3fc",
                    "success": true,
                    "bin_empty": false,
                    "grasp_success": true,
                    "place_success":true,
                    "item_dropped": false,
                    "place_bin_full": false, 
                    "object_not_fit": false, 
                    "rearranged": false,
                    "barcodes": [], 
                    "object_size": [0.13636983931064606, 0.20544570684432983, 0.030224323272705078],
                    "retry": 0
                },
                {
                    "id": "6caa46c0-dfc4-4eb3-a17f-2db45cebaa40",
                    "success": true,
                    "bin_empty": false,
                    "grasp_success": true,
                    "place_success":true,
                    "item_dropped": false,
                    "place_bin_full": false, 
                    "object_not_fit": false, 
                    "rearranged": false,
                    "barcodes": [], 
                    "object_size": [0.13636983931064606, 0.20544570684432983, 0.030224323272705078],
                    "retry": 0
                }
            ],
            "task_success": true,
            "items_picked": 2, 
            "barcodes": []
        }
    }
}

The result field in the response contains detailed information about the outcome of the "robot.grasp" operation. Key elements include:

  • success: A boolean indicating whether the API method was called successful.

  • payload: Additional details about the results, including:

    • picks: An array containing information about each item picked. Each entry includes details such as:

      • id: Unique identifier for the picked item.
      • success: Boolean indicating whether the pick and place operation was successful.
      • grasp_success: Boolean indicating whether the grasp was successful.
      • place_success: Boolean indicating whether the placing operation was successful.
      • item_dropped: Boolean indicating whether the item was dropped during the operation.
      • place_bin_full: Boolean indicating whether the placing is full or not.
      • object_not_fit: Boolean indicating whether the object is fit with the compartment or not.
      • rearranged: Boolean indicating whether the object is rearranged or not.
      • retry: The number of retries for the pick operation.
      • object_size: List of three float indicates the grasped object size [length, width, height]. If the bin is empty, this field is not available.

    • task_success: A boolean indicating the overall success of the grasping task.

    • items_picked: The total number of items picked.

    • barcodes: An array containing barcodes associated with the picked items.

Robot - Pick from compartment

This API will call a robot grasp from a bin and place to a bin with compartments. The layout of the compartments and the specific placing compartment must be defined in this call.

Request Payload

{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "robot.grasp",
    "params": {
        "speed": 40,
        "no_items": 2,
        "pick_area": "pick_1",
        "place_area": "place_1",
        "pick_compartment": {
            "layout": "2x4",
            "compartment": "0,0"
        }
    }
}

Parameters

  • method (string): Specifies the action to be performed by the robot. Set to "robot.grasp" for initiating the grasping process.
  • params (object): Contains specific parameters for the grasping action.
    • speed (integer): Speed at which the robot should execute the grasping process.
    • no_items (integer): Number of items the robot should grasp and subsequently place.
    • pick_area (string): Designated area for picking items.
    • place_area (string): Designated area for placing the grasped items.
    • pick_compartment (object): Configuration for the packing compartment.
      • layout (string): Layout of the packing compartment (e.g., "2x4").
      • compartment (string): Specific compartment coordinates (e.g., "0,0").

Example Request

import requests

res = requests.post("http://localhost:5000/api", json={
    "jsonrpc": "2.0",
    "id": 1,
    "method": "robot.grasp",
    "params": {
        "speed": 40,
        "no_items": 2,
        "pick_area": "pick_1",
        "place_area": "place_1",
        "pick_compartment": {
            "layout": "2x4",
            "compartment": "0,0"
        }
    }
})

Expected Result

{
    "jsonrpc": "2.0",
    "id": 1,
    "result": {
        "success": true,
        "payload": {
            "picks": [
                {
                    "id": "ffc69c1b-9d87-4c19-8dac-c09ca857e3fc",
                    "success": true,
                    "bin_empty": false,
                    "grasp_success": true,
                    "place_success":true,
                    "item_dropped": false,
                    "place_bin_full": false,
                    "object_not_fit": false,
                    "retry": 0,
                    "rearranged": false,
                    "object_size": [0.13636983931064606, 0.20544570684432983, 0.030224323272705078]
                },
                {
                    "id": "6caa46c0-dfc4-4eb3-a17f-2db45cebaa40",
                    "success": true,
                    "bin_empty": false,
                    "grasp_success": true,
                    "place_success":true,
                    "item_dropped": false,
                    "place_bin_full": false,
                    "object_not_fit": false,
                    "retry": 0,
                    "rearranged": false,
                    "object_size": [0.13636983931064606, 0.20544570684432983, 0.030224323272705078]
                }
            ],
            "task_success": true,
            "items_picked": 2, 
            "barcodes": []
        }
    }
}

The result field in the response contains detailed information about the outcome of the "robot.grasp" operation. Key elements include:

  • success: A boolean indicating whether the API method was called successful.

  • payload: Additional details about the results, including:

    • picks: An array containing information about each item picked. Each entry includes details such as:

      • id: Unique identifier for the picked item.
      • success: Boolean indicating whether the pick and place operation was successful.
      • grasp_success: Boolean indicating whether the grasp was successful.
      • place_success: Boolean indicating whether the placing operation was successful.
      • item_dropped: Boolean indicating whether the item was dropped during the operation.
      • place_bin_full: Boolean indicating whether the placing is full or not.
      • object_not_fit: Boolean indicating whether the object is fit with the compartment or not.
      • rearranged: Boolean indicating whether the object is rearranged or not.
      • retry: The number of retries for the pick operation.
      • object_size: List of three float indicates the grasped object size [length, width, height]. If the bin is empty, this field is not available.

    • task_success: A boolean indicating the overall success of the grasping task.

    • items_picked: The total number of items picked.

    • barcodes: An array containing barcodes associated with the picked items.

Robot - Pack into compartment

This API will call a robot grasp from a bin and place to a bin with compartments. The layout of the compartments and the specific placing compartment must be defined in this call.

Request Payload

{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "robot.grasp",
    "params": {
        "speed": 40,
        "no_items": 2,
        "pick_area": "pick_1",
        "place_area": "place_1",
        "pack_compartment": {
            "layout": "2x4",
            "compartment": "0,0"
        }
    }
}

Parameters

  • method (string): Specifies the action to be performed by the robot. Set to "robot.grasp" for initiating the grasping process.
  • params (object): Contains specific parameters for the grasping action.
    • speed (integer): Speed at which the robot should execute the grasping process.
    • no_items (integer): Number of items the robot should grasp and subsequently place.
    • pick_area (string): Designated area for picking items.
    • place_area (string): Designated area for placing the grasped items.
    • pack_compartment (object): Configuration for the packing compartment.
      • layout (string): Layout of the packing compartment (e.g., "2x4").
      • compartment (string): Specific compartment coordinates (e.g., "0,0").

Example Request

import requests

res = requests.post("http://localhost:5000/api", json={
    "jsonrpc": "2.0",
    "id": 1,
    "method": "robot.grasp",
    "params": {
        "speed": 40,
        "no_items": 2,
        "pick_area": "pick_1",
        "place_area": "place_1",
        "pack_compartment": {
            "layout": "2x4",
            "compartment": "0,0"
        }
    }
})

Expected Result

{
    "jsonrpc": "2.0",
    "id": 1,
    "result": {
        "success": true,
        "payload": {
            "picks": [
                {
                    "id": "ffc69c1b-9d87-4c19-8dac-c09ca857e3fc",
                    "success": true,
                    "bin_empty": false,
                    "grasp_success": true,
                    "place_success":true,
                    "item_dropped": false,
                    "place_bin_full": false,
                    "object_not_fit": false,
                    "retry": 0,
                    "rearranged": false,
                    "object_size": [0.13636983931064606, 0.20544570684432983, 0.030224323272705078]
                },
                {
                    "id": "6caa46c0-dfc4-4eb3-a17f-2db45cebaa40",
                    "success": true,
                    "bin_empty": false,
                    "grasp_success": true,
                    "place_success":true,
                    "item_dropped": false,
                    "place_bin_full": false,
                    "object_not_fit": false,
                    "retry": 0,
                    "rearranged": false,
                    "object_size": [0.13636983931064606, 0.20544570684432983, 0.030224323272705078]
                }
            ],
            "bin_empty": false,
            "task_success": true,
            "items_picked": 2, 
            "barcodes": []
        }
    }
}

The result field in the response contains detailed information about the outcome of the "robot.grasp" operation. Key elements include:

  • success: A boolean indicating whether the API method was called successful.

  • payload: Additional details about the results, including:

    • picks: An array containing information about each item picked. Each entry includes details such as:

      • id: Unique identifier for the picked item.
      • success: Boolean indicating whether the pick and place operation was successful.
      • grasp_success: Boolean indicating whether the grasp was successful.
      • place_success: Boolean indicating whether the placing operation was successful.
      • item_dropped: Boolean indicating whether the item was dropped during the operation.
      • place_bin_full: Boolean indicating whether the placing is full or not.
      • object_not_fit: Boolean indicating whether the object is fit with the compartment or not.
      • rearranged: Boolean indicating whether the object is rearranged or not.
      • retry: The number of retries for the pick operation.
      • object_size: List of three float indicates the grasped object size [length, width, height]. If the bin is empty, this field is not available.

    • task_success: A boolean indicating the overall success of the grasping task.

    • items_picked: The total number of items picked.

    • barcodes: An array containing barcodes associated with the picked items.

  • The API request robot to grasp the specified number of items from the designated pick area and places them in the specified place area, considering the specified packing compartment configuration.

Robot - Check bin or compartment is full

This API call triggers the vision system to detect the fullness of a specified bin or compartment.

Request Payload

{
    "jsonrpc": "2.0",
    "id": 1,    
    "method": "vision.bin_full",
    "params": {
        "area": "place_1",
        "compartment_data": {
            "layout": "2x4",
            "compartment": "0,0"
        }
    }
}

Parameters

  • method (string): Specifies the action to be performed by the vision system. Set to "vision.bin_full" for bin full detection.
  • params (object): Contains specific parameters for the bin full detection.
    • area (string): Designated area for bin full detection (e.g., "place_1").
    • compartment_data (object): Configuration for the compartment to be checked.
      • layout (string): Layout of the compartment (e.g., "2x4").
      • compartment (string): Specific compartment coordinates (e.g., "0,0").

These layouts are example layouts with coordinates. The system will automatically compute the necessary 3D information based on the layout.

Compartment Layout

Example Request

import requests

res = requests.post("http://localhost:5000/api", json={
    "jsonrpc": "2.0",
    "id": 1,        
    "method": "vision.bin_full",
    "params": {
        "area": "place_1",
        "compartment_data": {
            "layout": "2x4",
            "compartment": "0,0"
        }
    }
})

Expected Result

{
    "jsonrpc": "2.0",
    "result": {
        "success": true,
        "payload": false
    }
}

Parameters:

  • success: A boolean indicating whether the API method was called successful.

  • payload: A boolean indicating whether the bin is full or not( true: full, false: not full)

Robot - Check if all objects fit in the place bin

This API call triggers the vision system to determine if all objects fit in the designated place bin.

Request Payload

{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "vision.all_object_fit_place_bin",
    "params": {
        "place_area": "place_1",
        "pick_area": "pick_1",
        "pack_compartment": {
            "layout": "2x4",
            "compartment": "1,3"
        },
        "reduce_bag_size": 0.9
    }
}

Parameters

  • method (string): Specifies the action to be performed by the vision system. Set to "vision.all_object_fit_place_bin" for checking if all objects fit in the place bin.
  • params (object): Contains specific parameters for the operation.
    • place_area (string): Designated area for placing the items (e.g., "place_1").
    • pick_area (string): Designated area for picking the items (e.g., "pick_1").
    • pack_compartment (object): Configuration for the compartment where the items will be packed.
      • layout (string): Layout of the compartment (e.g., "2x4").
      • compartment (string): Specific compartment coordinates (e.g., "1,3").
    • reduce_bag_size (float): Reduction factor for bag size.

Example Request

import requests

res = requests.post("http://localhost:5000/api", json={
    "jsonrpc": "2.0",
    "id": 1,
    "method": "vision.all_object_fit_place_bin",
    "params": {
        "place_area": "place_1",
        "pick_area": "pick_1",
        "pack_compartment": {
            "layout": "2x4",
            "compartment": "1,3"
        },
        "reduce_bag_size": 0.9
    }
})

Expected Result

{
    "jsonrpc": "2.0",
    "result": {
        "success": true,
        "payload": false
    }
}

Parameters:

  • success: A boolean indicating whether the API method was called successful.

  • payload: A boolean indicating whether all the objects in the pick bin is fit with the place bin/compartment or not( true: fit all, false: not fit)

Robot - Check bin moves

This API call triggers the vision system to check the movements associated with a specified bin. CAUTION: This feature is only activated when the bin detection is activated and bin models are properly configured in the config.

Request Payload

{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "vision.bin_moves",
    "params": {
        "area": "pick_2"
    }
}

Parameters

  • method (string): Specifies the action to be performed by the vision system. Set to "vision.bin_moves" for checking bin moves.
  • params (object): Contains specific parameters for the operation.
    • area (string): Designated area for bin moves (e.g., "pick_2").

Example Request

import requests

res = requests.post("http://localhost:5000/api", json={
    "jsonrpc": "2.0",
    "id": 1,
    "method": "vision.bin_moves",
    "params": {
        "area": "pick_2"
    }
})

Expected Result

{
    "jsonrpc": "2.0",
    "result": {
        "success": true,
        "payload": false
    }
}

Parameters:

  • success: A boolean indicating whether the API method was called successfully.
  • payload: A boolean indicating the status of bin moves (true: bin moves aways, false: bin doesn't moves).


## Robot - Count Items in Area

This API call triggers the vision system to count the number of items in a specified area.

### Request Payload
```json
{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "vision.count_items",
    "params": {
        "area": "pick_2"
    }
}

Parameters

  • method (string): Specifies the action to be performed by the vision system. Set to "vision.count_items" for counting items.
  • params (object): Contains specific parameters for the operation.
    • area (string): Designated area for counting items (e.g., "pick_2").

Example Request

import requests

res = requests.post("http://localhost:5000/api", json={
    "jsonrpc": "2.0",
    "id": 1,
    "method": "vision.count_items",
    "params": {
        "area": "pick_2"
    }
})

Expected Result

{
    "jsonrpc": "2.0",
    "result": {
        "success": true,
        "payload": 14
    }
}

Parameters:

  • success: A boolean indicating whether the API method was called successfully.
  • payload: An integer indicating the count of items in the specified area.

Robot - Get Next Object Size in Area

This API call triggers the vision system to retrieve the size of the next object in a specified area.

Request Payload

{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "vision.get_next_object_size",
    "params": {
        "area": "pick_2"
    }
}

Parameters

  • method (string): Specifies the action to be performed by the vision system. Set to "vision.get_next_object_size" for retrieving the size of the next object.
  • params (object): Contains specific parameters for the operation.
    • area (string): Designated area for retrieving object size (e.g., "pick_2").

Example Request

import requests

res = requests.post("http://localhost:5000/api", json={
    "jsonrpc": "2.0",
    "id": 1,
    "method": "vision.get_next_object_size",
    "params": {
        "area": "pick_1"
    }
})

Expected Result

{
    "jsonrpc": "2.0",
    "result": {
        "success": true,
        "payload": {
            "size": [0.04935402795672417, 0.09054764360189438, 0.04741621017456055]
        }
    }
}

Parameters:

  • success: A boolean indicating whether the API method was called successfully.
  • payload: An object containing the size of the next object in the specified area. The size is represented as an array of three dimensions: length, width, and height.

Robot - Get Object Sizes in Area

This API call triggers the vision system to retrieve the sizes of all objects in a specified area.

Request Payload

{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "vision.get_object_sizes",
    "params": {
        "area": "pick_2"
    }
}

Parameters

  • method (string): Specifies the action to be performed by the vision system. Set to "vision.get_object_sizes" for retrieving object sizes.
  • params (object): Contains specific parameters for the operation.
    • area (string): Designated area for retrieving object sizes (e.g., "pick_2").

Example Request

import requests

res = requests.post("http://localhost:5000/api", json={
    "jsonrpc": "2.0",
    "id": 1,
    "method": "vision.get_object_sizes",
    "params": {
        "area": "pick_2"
    }
})

Expected Result

{
    "jsonrpc": "2.0",
    "result": {
        "success": true,
        "payload": [
            {"size": [0.04933764785528183, 0.08983241766691208, 0.04843318462371826]},
            {"size": [0.062454953789711, 0.0923340916633606, 0.03614330291748047]},
        ]
    }
}

Parameters:

  • success: A boolean indicating whether the API method was called successfully.
  • payload: A list of objects containing the sizes of all objects in the specified area. Each object has a "size" key containing an array representing the dimensions of the object (length, width, and height).

Robot - Stop

This API call instructs the robot to stop its current operation or movement.

Request Payload

{
    "jsonrpc": "2.0",
    "id": 1,    
    "method": "robot.stop",
    "params": {}
}

Parameters

  • method (string): Specifies the action to be performed by the robot. Set to "robot.stop" for instructing the robot to stop its operation.
  • params (object): Additional parameters may not be required for this action.

Example Request

import requests

res = requests.post("http://localhost:5000/api", json={
    "jsonrpc": "2.0",
    "id": 1,        
    "method": "robot.stop",
    "params": {}
})

Expected Result

{
    "jsonrpc": "2.0",
    "result": {
        "success": true
}
}
  • The robot processes the request to stop its current operation or movement.

Robot - Hardware Check

This API call initiates a hardware check on the robot, ensuring that all components are functioning correctly. Currently, the hardware check is only the checking of the robot movement and the multi suction gripper functionality.

Request Payload

{
    "method": "robot.hardware_check",
    "params": {}
}

Parameters

  • method (string): Specifies the action to be performed by the robot. Set to "robot.hardware_check" for initiating a hardware check.
  • params (object): Additional parameters may not be required for this action.

Example Request

import requests

res = requests.post("http://localhost:5000/api", json={
    "method": "robot.hardware_check",
    "params": {}
})

Expected Result

{
    "jsonrpc": "2.0",
    "result": {
        "success": true,
        "payload": {
            "success": true,
            "extract_and_landed": {
                "0": {
                    "landed": true,
                    "retract": true
                },
                "1": {
                    "landed": true,
                    "retract": true
                },
                "3": {
                    "landed": true,
                    "retract": true
                }
            },
            "suction_check": {
                "0": true,
                "1": true,
                "3": true
            }
        }
    }
}

  • The robot processes the request to perform a hardware check, verifying the correct functionality of all components. Key elements include:

  • success: A boolean indicating whether the hardware checking operation was successfully called.

  • payload: The detail result of the hardware check process.

    • success: true if all the hardware components are working properly.
    • extract_and_landed: Checking the extracting and landing operation on each suction unit. True indicates the suction unit is working properly and vice versa.
    • suction_check: check if the suction of the suction unit is working or not.

Error handler

Whenever a request is unsuccessful, the Capto API will return an error response with an error type and message. You can use this information to understand better what has gone wrong and how to fix it. Most of the error messages are pretty helpful and actionable. Below is a template for an error response:

{
  "jsonrpc": "2.0",
  "error": {
    "code": <error_code>,
    "message": <error_message>,
    "data": {
      "status": "error",
      "title": <error_type>,
      "description": <error_descritpion>
    }
  }
}

Parameters

  • Code: The code of the error
  • Message: The message from the error
  • data: The data object within the error response provides additional details about the encountered error:
    • Status: error
    • Title: The detailed error type
    • Description: The detailed description of the error.

Example

{
  "jsonrpc": "2.0",
  "error": {
    "code": -32000,
    "message": "Internal Server Error",
    "data": {
      "status": "error",
      "title": "Exception",
      "description": "Robot was e-stopped, please reset!"
    }
  }
}

In this example:

  • Code: -32000
  • Message: Internal Server Error
  • Data Object:
    • Status: error
    • Title: Exception
    • Description: Robot was e-stopped, please reset!

This error response indicates that an internal server error occurred with a specific code of -32000. The data object provides additional details, specifying that the error falls under the "Exception" category and includes a description instructing to reset the robot due to an emergency stop. Analyzing such details is crucial for understanding and addressing issues during API interactions.