robodatech.Roboda Cloud API
Telemetry ingest and live AGV dashboard documentation
Use Roboda Cloud to accept authenticated robot telemetry, validate subscription access, update device online state, and plot AGVs on the dashboard and maps.
https://ingest.robodatech.com/v1/state
https://api.robodatech.com/v1/state
Both endpoints route to the same strict Roboda Cloud ingest handler.
What the API does
The State API stores the latest JSON state for one registered robot device, updates the last-seen time, marks the device online, and feeds the subscribed user dashboard.
- Accepts telemetry only from a valid device API key or token.
- Checks that the owner has an active Roboda Cloud subscription or trial.
- Checks token expiry and plan device limit before saving telemetry.
- Supports indoor x/y AGV plotting and outdoor latitude/longitude maps.
Device model
Each registered AGV or robot should have its own device token. A plan with a 25 device limit should use up to 25 registered devices, each sending telemetry with its own token.
Request flow
Security
Authentication headers
Send one valid Roboda device token in a request header. Keep tokens out of browser code, public repositories, screenshots, and query strings.
| Header | Example | Use |
|---|---|---|
x-api-key | YOUR_DEVICE_TOKEN | Recommended for telemetry clients. |
x-roboda-api-key | YOUR_DEVICE_TOKEN | Roboda-specific API key header. |
x-roboda-token | YOUR_DEVICE_TOKEN | Compatible with the original State API. |
Authorization | Bearer YOUR_DEVICE_TOKEN | Standard bearer-token style. |
Quick start
Send a first telemetry packet
Replace the token with a real device token from the Roboda Cloud dashboard. This example sends indoor position, battery, speed, current, temperature, and heading.
Source code and build tools are available in the protected platform workspace.
Successful response
Source code and build tools are available in the protected platform workspace.
Dashboard result
- Device status changes to online.
- Battery gauge and numeric chart update.
- Indoor map moves the AGV to x/y position.
- Latest JSON viewer stores the payload for inspection.
Reference
Endpoint reference
Use ingest.roboda.tech for robot telemetry. api.roboda.tech is an equivalent alias for integrations.
| Method | URL | Purpose | Auth |
|---|---|---|---|
GET | https://ingest.robodatech.com/health | Public service health check. | No |
POST | https://ingest.robodatech.com/v1/state | Store latest robot state and update online status. | Yes |
POST | https://ingest.robodatech.com/v1/ingest | Alias for strict telemetry ingest. | Yes |
POST | https://ingest.robodatech.com/v1/devices/state | Alias for device state ingest. | Yes |
POST | https://robodatech.com/wp-json/roboda-cloud/v1/state | Legacy-compatible REST endpoint for state ingest. | Yes |
Payload
Recommended telemetry fields
The API stores JSON flexibly, but the dashboard reads common field names for charts, dials, and maps. Put robot readings inside state where possible.
Identity
device, device_id, timestamp, state.mode, state.signal
Indoor map
state.x, state.y, state.indoor_x, state.indoor_y. Use a 0-100 coordinate scale for the floor map.
Outdoor map
state.lat, state.lng, state.latitude, state.longitude for OpenStreetMap/Leaflet position plotting.
Power
state.battery_v, state.battery_percent, state.current_a, state.voltage.
Motion
state.speed_mps, state.speed, state.motor_pwm, state.heading_deg, state.rpm.
Sensors
state.distance_cm, state.temperature_c, state.obstacle, state.line_left, state.line_right.
Source code and build tools are available in the protected platform workspace.
Live maps
Plot AGVs on indoor and outdoor maps
The Roboda dashboard merges multiple devices into one fleet view and lets the user focus a selected device. Send x/y for indoor maps or lat/lng for outdoor GPS maps.
Coordinate rules
x: 0is the left edge,x: 100is the right edge.y: 0is the top edge,y: 100is the bottom edge.- AGVs without x/y still appear in the staging lane until live position arrives.
- Outdoor map requires real latitude and longitude values.
Code examples
Client examples
Use these as templates. Keep production tokens in environment variables or server-side configuration.
Source code and build tools are available in the protected platform workspace.
Source code and build tools are available in the protected platform workspace.
Source code and build tools are available in the protected platform workspace.
Source code and build tools are available in the protected platform workspace.
Errors
Common API responses
Handle these responses in the sender software so robots can retry safely or ask the user to refresh subscription/device settings.
| Status | Code | Meaning | Action |
|---|---|---|---|
401 | roboda_missing_token | No token was sent. | Add one accepted auth header. |
403 | roboda_invalid_token | Token does not match a registered device. | Regenerate or copy the correct device token. |
402 | roboda_subscription_required | Owner has no active trial/subscription. | Renew or activate Roboda Cloud. |
402 | roboda_subscription_expired | Access expiry has passed. | Renew subscription or license. |
403 | roboda_device_limit_exceeded | Device is outside the active plan limit. | Disable extra devices or upgrade plan. |
413 | roboda_payload_too_large | JSON payload is too large for the plan. | Send compact telemetry or reduce frequency/fields. |
Testing
AGV telemetry simulator
For lab testing, Roboda has a local simulator that can send random telemetry for up to 25 AGVs. It keeps real device tokens server-side and sends battery, location, speed, current, temperature, heading, and distance values.
Use it for
- Testing dashboard charts before hardware is ready.
- Checking plan device-limit behavior.
- Populating indoor maps with multiple AGVs.
- Verifying token expiry and invalid-token rejection.
Production rule
Only subscribed/trial users with valid device tokens can ingest telemetry. Invalid API keys, expired tokens, and devices beyond plan limit are discarded.
Use https://ingest.robodatech.com/v1/state for the simulator endpoint.
Operational guidance
Best practices
Do
- Use one token per robot device.
- Send compact JSON every 1-5 seconds for live maps.
- Include timestamp, battery, position, and signal/mode.
- Regenerate a token if it is exposed.
Do not
- Do not hard-code real tokens in public web pages.
- Do not share one token across many AGVs.
- Do not send huge camera images through the state endpoint.
- Do not rely on Arduino Nano alone for HTTPS; use a gateway.