Mission

Missions are atomic units of behavior that define a robot's high-level actions. This API enables users to control robot behavior—from simple navigation tasks to complex, conditional workflows.

CreateMission¶

Send a robot on a mission of specified type.

Request¶

robot_id `string` `required`¶

The ID of the robot that will receive this command.

mission `Mission` `required`¶

Universal wrapper for mission types. Only one mission type may be set at a time.

Field (oneof)	Message Type	Description
`base_mission`	`BaseMission`	Base missions are applicable to all robot families.
`servi_mission`	`servi.Mission`	Servi missions are specific to the Servi robot family. Refer to Servi for how to create and send a servi mission.
`carti_mission`	`carti.Mission`	Carti missions are specific to the Carti robot family. Refer to Carti for how to create and send a carti mission.

base_mission `BaseMission`¶

Use field base_mission to send a base mission. Current API version supports 2 types of base missions.

Field (oneof)	Message Type	Description
`navigate_mission`	`NavigateMission`	Create a base mission of type `Navigate`.
`navigate_auto_mission`	`NavigateAutoMission`	Create a base mission of type `NavigateAuto`.

navigate_mission `NavigateMission`¶

A mission consisting of a single, explicitly defined goal.

Field	Message Type	Description
`goal`	`Goal` `required`	The target destination for the mission.

navigate_auto_mission `NavigateAutoMission`¶

A mission that automatically selects the best available goal from the provided list. The system will choose the closest goal while avoiding goals currently occupied by other robots.

Field	Message Type	Description
`goals`	repeated `Goal` `required`	The list of target destinations for the mission.

goal `Goal` `required`¶

Goal represents a target destination for the robot to navigate to.

Field (oneof)	Message Type	Description
destination_id	`string`	Unique identifier for the destination.

JSON Request Example¶

JSON

  {
    "robotId": "robot-001",
    "mission": {
      "baseMission": {
        "navigateMission": {
          "goal": {
            "destinationId": "Main Kitchen"
          }
        }
      }
    }
  }

Response¶

mission_id `string`¶

The ID of the mission created.

JSON Response Example¶

JSON

  {
    "missionId": "mission-xyz-123"
  }

Errors¶

ErrorCode	Description
`FAILED_PRECONDITION`	The robot is already executing another mission. This command is valid if current mission is in terminal state, e.g Cancelled, Succeeded, Failed.
`INVALID_ARGUMENT`	The client supplied a request with invalid format. This covers sending empty requests, invalid goals, goals that do not match mission type, and other format errors. Client should update their usage to have correctly formatted requests with valid goals for the missions as defined in documentation.
`INTERNAL`	The request failed to execute due to internal error in mission system. Client should retry creating the mission.
`DEADLINE_EXCEEDED`	The request was sent internally, but timed out waiting for confirmation response of request being accepted. Client should retry creating the mission.

AppendMission¶

Appends a mission to the end of the mission queue.
Use this when a mission is currently running; otherwise, prefer CreateMission.
Missions are executed in the order they are appended.

JSON Request / Response Example¶

AppendMission request and response message types are the same as CreateMission.
See CreateMission JSON Examples.

Errors¶

ErrorCode	Description
`FAILED_PRECONDITION`	There is no mission in the mission queue. Client should first create the initial mission, and only use Append for queuing additional missions.
`INVALID_ARGUMENT`	The client supplied a request with invalid format. This covers sending empty requests, invalid goals, goals that do not match mission type, and other format errors. Client should update their usage to have correctly formatted requests with valid goals for the missions as defined in documentation.
`INTERNAL`	The request failed to execute due to internal error in mission system. Client should retry appending the mission.
`DEADLINE_EXCEEDED`	The request was sent internally, but timed out waiting for confirmation response of request being accepted. Client should retry appending the mission.

UpdateMission¶

Issues a command to control or update the current mission (e.g., pause, cancel).

Warning

We currently do not support updating missions in mission queue.
Attempting to send UpdateMission command to a queued mission will result in NOT_FOUND error.

Request¶

robot_id `string` `required`¶

The ID of the robot that will receive this command.

mission_command `MissionCommand` `required`¶

Command to update the state of an active mission.
MissionCommand has 2 fields.

Field	Message Type	Description
`mission_id`	`string` `required`	The ID of the mission to control.
`command`	`Command` enum `required`

Command `enum`¶

Name	Number	Description
COMMAND_UNKNOWN	0	Default value. This should never be used explicitly. It means the `command` field is not set
COMMAND_CANCEL	1	Cancel this mission.
COMMAND_PAUSE	2	Pause this mission.
COMMAND_RESUME	3	Resume a paused mission.
COMMAND_FINISH	4	Mark the mission as completed.

JSON Request Example¶

JSON

  {
    "robot_id": "pennybot-abc123",
    "mission_command": {
      "mission_id": "f842c8ac-62de-412e-90fb-bf37022db2f4",
      "command": "COMMAND_PAUSE"
    }
  }

Response¶

(No fields defined)

JSON Response Example¶

JSON

{}

Errors¶

ErrorCode	Description
`FAILED_PRECONDITION`	The robot is either not on a mission, or the command is invalid for the robot's current state. For example, mission in terminal state (Cancelled, Succeeded, Failed) can't be updated.
`INVALID_ARGUMENT`	The client supplied a request with invalid format. This covers sending empty requests, invalid commands, incorrect mission ID, and other format errors. Client should update their usage to have correctly formatted requests with valid commands, and ensure the mission id matches the currently running mission.
`INTERNAL`	The request failed to execute due to internal error in mission system. Client should retry appending the mission.
`DEADLINE_EXCEEDED`	The request was sent internally, but timed out waiting for confirmation response of request being accepted. Client should retry appending the mission.

SubscribeMissionStatus¶

A server side streaming RPC endpoint to get updates on the robot's mission state. Upon subscription, the latest known mission state is sent immediately. Subsequent updates are streamed as the state changes.

Request¶

selector `RobotSelector` `required`¶

RobotSelector is used to select specific robots.
It supports selection by a list of robot IDs OR all robots at a given location.

Field	Message Type	Description
`robot_ids`	`RobotIDs`	Selects robots by their specific IDs. Example: `["pennybot-123abc", "pennybot-abc123"]`
`location_id`	`string`	Selects all robots at the specified location.

JSON Request Example¶

JSON

  {
    "selector": {
      "robot_ids": {
        "ids": ["pennybot-abc123", "pennybot-123abc"]
      }
    }
  }

Response¶

This endpoint returns a stream of messages in response.
Each message includes:

metadata `EventMetadata`¶

Field	Message Type	Description
`timestamp`	Timestamp	The time when the event was recorded.
`sequence_number`	int64	An incremental sequence number generated by the robot. The sequence number should never be negative and can be reset to 0. i.e. sequence is valid if it is larger than the previous number or 0.

robot_id `string`¶

The robotID the message is associated with.

mission_state `MissionState`¶

Field	Message Type	Description
`mission_id`	string	Unique identifier for the mission.
`state`	State enum
`goals`	Goal	All goals associated with the mission, in the order the request was given.
`current_goal_index`	int32	Index of the currently active goal in the goals list.
`mission_feedback`	MissionFeedback	Latest feedback for the mission.

State `enum`¶

Name	Number	Description
STATE_UNKNOWN	0	Default value. It means the `state` field is not returned.
STATE_DEFAULT	1	Initial state when no mission has been run (e.g., feedback is empty).
STATE_RUNNING	2	The mission is actively running.
STATE_PAUSED	3	The mission is paused.
STATE_CANCELED	4	The mission was canceled before completion.
STATE_SUCCEEDED	5	The mission completed successfully.
STATE_FAILED	6	The mission encountered an error or failure.

MissionFeedback¶

BaseFeedback will be returned when sending one of the BaseMission missions.

BaseFeedback `enum`¶

Name	Number	Description
STATUS_UNKNOWN	0	Default value. It means `status` field is not returned.
STATUS_NAVIGATING	1	The robot is currently navigating to its target.

JSON Response Example¶

JSON

{
  "metadata": {
    "timestamp": "2025-04-01T15:30:00Z",
    "sequenceNumber": 128
  },
  "robot_id": "pennybot-abc123",
  "mission_state": {
    "mission_id": "d6637a14-5f6b-43f6-bd86-cc1871a8322e",
    "state": "STATE_RUNNING",
    "goals": [
      {
        "destinationId": "pickup_zone"
      },
      {
        "pose": {
          "xMeters": 4.2,
          "yMeters": 7.8,
          "headingRadians": 1.57
        }
      }
    ],
    "current_goal_index": 1,
    "mission_feedback": {
      "baseFeedback": {
        "status": "STATUS_NAVIGATING"
      }
    }
  }
}

Errors¶

ErrorCode	Description
`PERMISSION_DENIED`	Attempting to request status for a `robot_id` or `location_id` you don't own. Tip: check the spelling of all `robot_id` or `location_id` values.
`INVALID_ARGUMENT`	One or more request parameters are malformed or logically incorrect. Example: Using an invalid robot ID format.

ChargeRobot¶

ChargeRobot is a special type of mission. Use this command to instruct the robot to begin charging, regardless of its current battery level.

This command is only supported on robots equipped with a contact-based charging dock. Robots without a compatible dock will return an INVALID_ARGUMENT error.

You can use SubscribeBatteryStatus to monitor the charging process.

Request¶

robot_id `string` `required`¶

The ID of the robot that will receive this command.

JSON Reqeuest Example¶

JSON

{
  "robot_id": "pennybot-abc123"
}

Response¶

mission_id `string`¶

The ID of the mission created. Since this command is a special type of mission, its execution state is also avaiable in response messages from SubscribeMissionStatus.

JSON Response Example¶

JSON

{
  "mission_id": "mission-xyz-001"
}

Errors¶

ErrorCode	Description
`FAILED_PRECONDITION`	The robot is already executing a mission. The current mission must be canceled before issuing this command.
`INTERNAL`	The request failed to execute due to internal error in mission system. Client should retry creating the mission.
`DEADLINE_EXCEEDED`	The request was sent internally, but timed out waiting for confirmation response of request being accepted. Client should retry creating the mission.

Mission

CreateMission¶

Request¶

robot_id string required¶

mission Mission required¶

base_mission BaseMission¶

navigate_mission NavigateMission¶

navigate_auto_mission NavigateAutoMission¶

goal Goal required¶

JSON Request Example¶

Response¶

mission_id string¶

JSON Response Example¶

Errors¶

AppendMission¶

JSON Request / Response Example¶

Errors¶

UpdateMission¶

Request¶

robot_id string required¶

mission_command MissionCommand required¶

Command enum¶

JSON Request Example¶

Response¶

JSON Response Example¶

Errors¶

SubscribeMissionStatus¶

Request¶

selector RobotSelector required¶

JSON Request Example¶

Response¶

metadata EventMetadata¶

robot_id string¶

mission_state MissionState¶

State enum¶

MissionFeedback¶

BaseFeedback enum¶

JSON Response Example¶

Errors¶

ChargeRobot¶

Request¶

robot_id string required¶

JSON Reqeuest Example¶

Response¶

mission_id string¶

JSON Response Example¶

Errors¶

robot_id `string` `required`¶

mission `Mission` `required`¶

base_mission `BaseMission`¶

navigate_mission `NavigateMission`¶

navigate_auto_mission `NavigateAutoMission`¶

goal `Goal` `required`¶

mission_id `string`¶

robot_id `string` `required`¶

mission_command `MissionCommand` `required`¶

Command `enum`¶

selector `RobotSelector` `required`¶

metadata `EventMetadata`¶

robot_id `string`¶

mission_state `MissionState`¶

State `enum`¶

BaseFeedback `enum`¶

robot_id `string` `required`¶

mission_id `string`¶