---
title: "Send a set of relative waypoints to the robot"
method: POST
path: "/v1/vehicles/{vehicleId}/relative-waypoints"
tags: ["Vehicle Autonomy"]
---

# Send a set of relative waypoints to the robot

`POST /v1/vehicles/{vehicleId}/relative-waypoints`

## Request

- Base URL: `https://api.polymathrobotics.dev`
- URL: `https://api.polymathrobotics.dev/v1/vehicles/{vehicleId}/relative-waypoints`
- Auth: HTTP bearer

Sends relative waypoints and navigation options to the robot.

## Path parameters

- `vehicleId` string, required

## Request body

- RelativeWaypoints: Base for request bodies: unknown fields are rejected instead of silently dropped.
  - `relative_to` union: The target that waypoints are specified relative to. Accepts either a name as string or a fully specified ReferenceTarget. The name can be 'current_position', a previously set ReferenceTarget, or the name of a frame in the transform tree, such as 'base_link'. Unknown strings are passed through verbatim and will fail downstream if the reference does not exist. Defaults to 'current_position' so waypoints are interpreted relative to the robot's current pose.
    - string
    - ReferenceTarget: Base for request bodies: unknown fields are rejected instead of silently dropped.
      - `target_id` string: Unique name or ID of the reference target
      - `timestamp_utc` string: Timestamp in UTC ISO format. Should be provided in ISO 8601 format: 'YYYY-MM-DDTHH:MM:SSZ'. If not provided, it will default to the current UTC time.
      - `pose` GeoPoint, required: Base for request bodies: unknown fields are rejected instead of silently dropped.
        - `lat` number, required: Latitude
        - `lon` number, required: Longitude
        - `altitude` number: Altitude (meters)
        - `yaw` number: Yaw (radians). Robot body frame: x forward, y left, z up; positive yaw is counter-clockwise.
      - `time_validity` number: Time validity in seconds. -1 means forever.
      - `recorded_speed_m_s` number: Recorded speed of the object in m/s. `None` indicates no measurement available.
  - `timestamp_utc` string: Timestamp in UTC ISO format. Should be provided in ISO 8601 format: 'YYYY-MM-DDTHH:MM:SSZ'. If not provided, it will default to the current UTC time.
  - `move_to` RelativeCommand[], required: Ordered list of relative waypoints. When multiple waypoints are provided, the robot navigates through them continuously as a single path rather than stopping discretely at each one. Robot body frame: x forward, y left, z up; positive yaw is counter-clockwise.
    - `timestamp_utc` string: Timestamp in UTC ISO format. Should be provided in ISO 8601 format: 'YYYY-MM-DDTHH:MM:SSZ'. If not provided, it will default to the current UTC time.
    - `x` number: Offset distance in meters along the X axis.
    - `y` number: Offset distance in meters along the Y axis.
    - `z` number: Offset distance in meters along the Z axis.
    - `yaw` number: Yaw (radians) angular offset indicating the direction the robot should face relative to the target.
  - `navigation_options` CortexNavigationOptions: Base for request bodies: unknown fields are rejected instead of silently dropped.
    - `path_option` CortexOption: Base for request bodies: unknown fields are rejected instead of silently dropped.
      - `name` string, required
      - `params` KeyValuePair[], required
        - `key` string, required
        - `value` string, required
    - `mode` unknown

## Response `200`

Sent relative waypoints and upstream service response.

- RelativeWaypointTransmissionResponse
  - `status` string, required
  - `message` string, required
  - `data` RelativeWaypointTransmissionData, required
    - `sent` RelativeWaypoints, required: Base for request bodies: unknown fields are rejected instead of silently dropped.
      - `relative_to` union: The target that waypoints are specified relative to. Accepts either a name as string or a fully specified ReferenceTarget. The name can be 'current_position', a previously set ReferenceTarget, or the name of a frame in the transform tree, such as 'base_link'. Unknown strings are passed through verbatim and will fail downstream if the reference does not exist. Defaults to 'current_position' so waypoints are interpreted relative to the robot's current pose.
        - string
        - ReferenceTarget: Base for request bodies: unknown fields are rejected instead of silently dropped.
          - `target_id` string: Unique name or ID of the reference target
          - `timestamp_utc` string: Timestamp in UTC ISO format. Should be provided in ISO 8601 format: 'YYYY-MM-DDTHH:MM:SSZ'. If not provided, it will default to the current UTC time.
          - `pose` GeoPoint, required: Base for request bodies: unknown fields are rejected instead of silently dropped.
            - `lat` number, required: Latitude
            - `lon` number, required: Longitude
            - `altitude` number: Altitude (meters)
            - `yaw` number: Yaw (radians). Robot body frame: x forward, y left, z up; positive yaw is counter-clockwise.
          - `time_validity` number: Time validity in seconds. -1 means forever.
          - `recorded_speed_m_s` number: Recorded speed of the object in m/s. `None` indicates no measurement available.
      - `timestamp_utc` string: Timestamp in UTC ISO format. Should be provided in ISO 8601 format: 'YYYY-MM-DDTHH:MM:SSZ'. If not provided, it will default to the current UTC time.
      - `move_to` RelativeCommand[], required: Ordered list of relative waypoints. When multiple waypoints are provided, the robot navigates through them continuously as a single path rather than stopping discretely at each one. Robot body frame: x forward, y left, z up; positive yaw is counter-clockwise.
        - `timestamp_utc` string: Timestamp in UTC ISO format. Should be provided in ISO 8601 format: 'YYYY-MM-DDTHH:MM:SSZ'. If not provided, it will default to the current UTC time.
        - `x` number: Offset distance in meters along the X axis.
        - `y` number: Offset distance in meters along the Y axis.
        - `z` number: Offset distance in meters along the Z axis.
        - `yaw` number: Yaw (radians) angular offset indicating the direction the robot should face relative to the target.
      - `navigation_options` CortexNavigationOptions: Base for request bodies: unknown fields are rejected instead of silently dropped.
        - `path_option` CortexOption: Base for request bodies: unknown fields are rejected instead of silently dropped.
          - `name` string, required
          - `params` KeyValuePair[], required
            - `key` string, required
            - `value` string, required
        - `mode` unknown
    - `received` unknown
    - `command_ids` string[]: Cortex-assigned ids for the accepted commands, aligned 1:1 with the commands sent and in the same order. Each is the goal id for its command; pass one to GET /command-history as command_id to look that command up once it finishes. Empty when cortex handled the request without queueing commands, as a RESUME motion command does.

## Other responses

- `422`: Validation Error
- `500`: Internal server error

## Changes

- **2026-09-09** `7bb062ddb622`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/polymathrobotics/apis/polymath-api/changes/v1/vehicles/:vehicleId/relative-waypoints/post.md)

---

[API](https://skmtc.dev/polymathrobotics/apis/polymath-api.md) - [All operations](https://skmtc.dev/polymathrobotics/apis/polymath-api/llms.txt) - [OpenAPI document](https://skmtc.dev/polymathrobotics/apis/polymath-api/revisions/3b5ff2f21338?raw)