ROBOT INTEGRATIONM2 API

VERSION: v1
ENDPOINTS: 04
AUTH: Bearer
FORMAT: JSON

REST · JSON APIBearer token authReal-time robot statusVDA5050 support

M2 Robot Integration API

Connect Polaris3D AMRs to your FMS or MES and query real-time robot status, location and mission history through a simple REST API.

2 Resources · 4 Endpoints

Two read-only resources cover robot monitoring and mission tracking. Every endpoint is an authenticated GET request that responds with JSON.

Missions

Mission Data

Query the mission list and mission details, including state, creator, priority, result code and step-by-step submissions.

GET/api/v1/missions
GET/api/v1/missions/{mission_id}

Mobile Objects

Robot Status

Query the robot list and real-time robot details, including state, coordinates, battery, error codes and hardware module status.

GET/api/v1/amr/objects
GET/api/v1/amr/objects/{object_id}

API Reference

Base URL, authentication and the specification of each endpoint. Click an item to expand its response fields and examples.

Get a tokenCall /api/v1/auth/token with the account issued to you.
Add the token to the headerAuthorization: Bearer <token>
Call the APISend GET requests to the endpoints below.

Base URL	`https://{host}/api/v1` ({host} is the IP address or domain issued to you)
Transport	HTTPS · JSON (UTF-8)
Content-Type	`application/json`

Authentication · Issue Token

Every API call requires a Bearer access token.

POST/api/v1/auth/token

Request Body

Key	Type	Required	Description
client_id	String		Client ID issued to you
client_secret	String		Secret key issued to you

Response Fields4

Key	Type	Description
access_token	String	Access token for API calls
token_type	String	Always `Bearer`
expires_in	Integer	Token lifetime (seconds)
refresh_token	String	Token used to get a new access token after expiry

Request · Response Example

POST /api/v1/auth/token
Content-Type: application/json

{ "client_id": "your_client_id", "client_secret": "your_client_secret" }

--- 200 OK ---
{
  "access_token": "eyJhbGciOi...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "def502..."
}

Getting credentials: A client ID and secret key are issued when you contact us about integration. We will also explain the token expiry and renewal policy at that time.

Common Errors

These apply to every endpoint.

HTTP Status	Description
401 Unauthorized	User is not authenticated
403 Forbidden	Request denied due to insufficient permissions
500 Internal Server Error	Server error
501 Not Implemented	Other errors

Error Response Body2

Key	Type	Description
error_code	Integer	Error identifier
message	String	Description of the error cause

Mission List

Query the mission list page by page.

GET/api/v1/missions

Query Parameters

Parameter	Type	Description
mission_id	String	Filter by mission ID
site_id	String	Filter by site
object_id	String	Filter by object (robot)
map_id	String	Filter by map
mission_state_id	Integer	Filter by mission state
page	Integer	Page number (default 0)

Response Fields · mission15

Key	Type	Description
mission_id	String	Mission ID
mission_state	Object	State: `0` WAITING · `1` CANCELED · `2` PROCESS · `3` COMPLETE · `4` ASSIGNED · `5` ERROR · `6` ASSIGN_FAILED · `7` ASSIGN_PREPARING
mission_creator	Object	Created by: `100` automatic · `101` manual · `102` regenerated · `103` line call
site	Object	Site
map	Object	Map
object	Object	Object (robot)
priority	Object	Priority: `1` high · `2` medium · `3` low
mission_result	Object	Result: `0` START · `1` FINISHED · `2` CANCEL · `3~8` failures · `100~115` server/EV/WebSocket and other errors · `501` FINISHED_EARLY_FOR_NEXT_MISSION
mission_reject_reason	String	Reason the mission was rejected
mission_start_time	String	Start time
mission_end_time	String	End time
mission_time	String	Duration
mission_type	Object	Type: `50` MCS · `100` logistics · `102` return
updated_at	String	Last updated
created_at	String	Created

Response Fields · page (paging)5

Key	Type	Description
content	List	Mission list (empty list if none)
total_page_count	Integer	Total number of pages
now_page_number	Integer	Current page number (starts at 0)
total_element_count	Integer	Total number of elements
now_element_count	Integer	Number of elements on the current page

Response Example (200 OK)

{
  "content": [
    {
      "mission_id": "mi-u2jg-bgae",
      "mission_state": { "id": 1, "label": "Canceled" },
      "mission_creator": { "id": 100, "label": "Automatic" },
      "site": { "id": "s001", "label": "s001" },
      "map": { "id": "m001", "label": "m001" },
      "object": { "id": "o001", "label": "o001" },
      "priority": { "id": 1, "label": "High" },
      "mission_start_time": "2025-08-11 15:43:00.0",
      "mission_end_time": "2025-08-11 15:43:00.0",
      "mission_time": "0m 0s",
      "mission_type": { "id": 100, "label": "Logistics" },
      "created_at": "2025-08-11 14:08:00.0",
      "updated_at": "2025-08-11 15:43:00.0",
      "mission_result": { "id": 2, "label": "Canceled by user" }
    }
  ],
  "total_page_count": 4,
  "now_page_number": 3,
  "total_element_count": 43,
  "now_element_count": 1
}

Mission Detail

Query the details of a single mission and its list of submissions.

GET/api/v1/missions/{mission_id}

Path Variable

Parameter	Type	Description
mission_id	String	ID of the mission to query

Response Fields · Additional2

Includes every mission field from the mission list, plus the fields below.

Key	Type	Required	Description
origin_mission_id	String		Original mission ID
submissions	List		Submission list. Elements: `submission_id`, `submission_type` (`1` move to destination and wait · `2` return to waiting area · `3` return to charging station · `4` pick up · `5` supply), `submission_destination`, `submission_start_time`, `submission_end_time`, `submission_time`, `is_in_progress`, `amr_operation_modes` (List), `error_messages` (List), `created_at`, `updated_at`

Response Example (200 OK)

{
  "mission_id": "m001",
  "mission_state": { "id": 0, "label": "Waiting" },
  "mission_creator": { "id": 100, "label": "Automatic" },
  "site": { "id": "SITE001", "label": "Hotel" },
  "map": { "id": "MAP001", "label": "Hotel 1F" },
  "object": { "id": "AMR001", "label": "Robot 1" },
  "priority": { "id": 1, "label": "High" },
  "mission_result": { "id": 1, "label": "Success" },
  "mission_type": { "id": 100, "label": "Logistics" },
  "origin_mission_id": null,
  "created_at": "2024-12-12 12:32:00.0",
  "updated_at": "2024-12-12 12:32:00.0",
  "submissions": [
    {
      "submission_id": "si001",
      "submission_type": { "id": 4, "label": "Pick up" },
      "submission_destination": "Rack001",
      "submission_time": "2m 0s",
      "is_in_progress": 0,
      "amr_operation_modes": ["Tier 2 supply", "Tier 1 pick up"],
      "error_messages": []
    },
    {
      "submission_id": "si002",
      "submission_type": { "id": 5, "label": "Supply" },
      "submission_destination": "Rack002",
      "is_in_progress": 0,
      "amr_operation_modes": ["Tier 2 supply", "Tier 1 pick up"],
      "error_messages": ["[22] Localization LiDAR fault", "[24] Wheel encoder fault"]
    }
  ]
}

Mobile Object List

Query the list of robots (mobile objects) on a site with their real-time status. No request parameters are needed.

GET/api/v1/amr/objects

Response Fields (array element)10

Key	Type	Description
object_id	String	Object ID
object_type	Object	Type: `1` delivery · `2` serving · `3` logistics · `5` M3
site	Object	Site
object_name	String	Object name
state	Object	State: `-2` offline · `-1` initializing · `0` error · `1` waiting · `2` in progress · `3` stopped · `6` charging · `7` returning to waiting area · `8` returning to charging station · `9` docking · `10` AMR manual control
map	Object	Current location (map)
coordinate	Object	Current coordinates: `coordinate_x`, `coordinate_y`, `direction`
battery	String	Remaining battery
prevent_mission_execution	Integer	Prevent mission execution: `0` OFF (default) · `1` ON
last_communication_time	String	Last communication time

Response Example (200 OK)

[
  {
    "object_id": "amr-ywfx",
    "object_type": { "id": 3, "label": "Logistics robot" },
    "site": { "id": "st-pls3", "label": "Polaris3D" },
    "object_name": "Logistics Robot 1",
    "state": { "id": -1, "label": "Initializing" },
    "last_communication_time": "2025-03-21 13:22:42",
    "map": { "id": "4f_fih", "label": "First Hill 4F" },
    "coordinate": {
      "coordinate_x": "250.7113581270456",
      "coordinate_y": "220.8253131469545",
      "direction": "-140.0"
    },
    "battery": "100",
    "prevent_mission_execution": 1
  }
]

Mobile Object Detail

Query the detailed status of a single robot, including hardware module (fork, gripper, conveyor, lift) status, mission progress and load information.

GET/api/v1/amr/objects/{object_id}

Path Variable

Parameter	Type	Description
object_id	String	ID of the object to query

Response Fields · Additional17

Includes every field from the object list, plus the fields below. Module fields (fork, gripper, conveyor, top_lift, bottom_lift) are included depending on the robot type.

Key	Type	Description
serial_number	String	Serial number
activate_date	String	Activation date
deactivate_date	String	Deactivation date
error_codes	List	Errors currently active (e.g. `{"id":22,"label":"Localization LiDAR fault"}`)
mission_completed	Integer	Number of completed missions
mission_id	String	ID of the mission in progress
current_position	String	Current position (path)
destination	String	Destination (by node_id)
loading	Object	Load information (currently unused, default null)
loadings	List<Object>	Load information. Elements: `stage`, `loading`
fork	Object	Fork: `state`, `error_codes`, `depth`
gripper	Object	Gripper: `state`, `error_codes`, `depth`, `width`, `xoffset`
conveyor	List<Object>	Conveyor. Elements: `stage`, `state`, `error_codes`
top_lift	Object	Top lift: `state`, `error_codes`, `height`
bottom_lift	Object	Bottom lift: `state`, `error_codes`, `height`
pick_drop_direction_ids	List<Integer>	Pick-up/supply directions (with VDA5050): `1` FRONT · `2` REAR · `3` LEFT · `4` RIGHT
docking_direction_ids	List<Integer>	Docking directions (with VDA5050): `1` FRONT · `2` REAR · `3` LEFT · `4` RIGHT

Response Example (200 OK · M3)

{
  "object_id": "amr-5ofn",
  "object_type": { "id": 5, "label": "M3" },
  "site": { "id": "st-pls3", "label": "Polaris3D" },
  "object_name": "M3",
  "state": { "id": 0, "label": "Error" },
  "last_communication_time": "2026-03-05 16:36:39",
  "map": { "id": "4f_fih", "label": "First Hill 4F" },
  "coordinate": { "coordinate_x": "123.45", "coordinate_y": "67.89", "direction": "180.0" },
  "battery": "87",
  "prevent_mission_execution": 0,
  "error_codes": [ { "id": 22, "label": "Localization LiDAR fault" } ],
  "mission_completed": 0,
  "mission_id": "",
  "destination": "",
  "loadings": [
    { "stage": "1", "loading": "Loaded" },
    { "stage": "2", "loading": "Empty" }
  ],
  "fork": { "state": "Error", "error_codes": [ { "id": 501, "label": "Localization unavailable" } ], "depth": "1200" },
  "gripper": { "state": "Waiting", "error_codes": [], "depth": "500", "width": "300", "xoffset": "15" },
  "conveyor": [
    { "stage": "1", "state": "Rotating", "error_codes": [ { "id": 201, "label": "Low battery / discharging error" } ] },
    { "stage": "2", "state": "Forward", "error_codes": [] }
  ],
  "top_lift": { "state": "Rising", "error_codes": [ { "id": 200, "label": "Low battery error" } ], "height": "1500" },
  "bottom_lift": { "state": "Lowering", "error_codes": [], "height": "300" },
  "pick_drop_direction_ids": [1, 2, 3, 4],
  "docking_direction_ids": [1]
}

Looking for Genuine M2 Parts?

Browse genuine M2 replacement parts by category, from drive and electrical to sensors and batteries, and request a quote for the parts you need.

View Spare Parts