Send missions to real drones, follow them live and get every photo, video and analysis back into your own system. This guide explains every endpoint, field and error so your team can integrate without having to ask us.
Call GET /me with the key. If it answers 200, your account, permissions and clients are ready.
GET /api/v1/me
Get started
Overview
The Ubermach API lets an external system — your field-service software, ERP or your own app — send work to drones and get the results back. You never talk to the drone directly: you create a mission, a person approves it, the pilot confirms the take-off on the remote controller, and Ubermach returns every photo, video, telemetry point and AI analysis, with webhooks at each step.
How the pieces fit
Concept
What it is
Organization
Your company. Owns the API keys, the webhook and the bill. A partner organization can also have clients (child organizations) and act on their behalf.
Client
One of your customers, identified by your own id (external_ref). Drones, zones and missions belong to a client.
Drone
A registered aircraft (dev_…) with a capability profile. It connects through the phone connector with its own device key.
Zone
A geofence drawn in Ubermach Flights. Missions can only fly inside an operation zone and never inside an exclusion zone.
Mission
A route for one drone, built from a template or your own waypoints, optionally with automatic AI on every photo.
Session
One flight as recorded by the phone: telemetry, events, photos and videos, with a summary when it closes.
Media
A photo or video (med_…) with its position, hash and AI analyses.
Safety rules the API always enforces
Every route is checked against the client's zones and the 120 m ceiling before a mission is saved, again when it is approved and again when it is dispatched.
No API key can approve a mission or create a zone: those actions need a person signed in to the panel. Direct commands to a drone are off by default and only work if your administrator enables them in the developer portal (Direct control).
No take-off happens without the pilot's confirmation on the remote controller.
Get started
Access and pricing
The API (API keys, webhooks and the embeddable viewer) is a paid service, separate from Ubermach Flights. Your organization needs the API plan with an active subscription. None of the Flights plans include it.
Sign up at /developers/alta. The account is created with the API plan; access opens when the card subscription is authorized.
Monthly fee plus one charge per drone connected in the month. A drone counts once per month when it talks to Ubermach at least once (telemetry, connector or session), counted by distinct serial number. Deleting and re-creating a drone does not count it twice; deleting it before month end does not remove it from the bill.
If you connect your own clients' drones, all of them are billed to your organization, even with a single key.
API keys are free: create as many as you need, one per system or environment.
Prices, the 3-month pilot at half the platform fee and examples: ubermach.com/pricing. Payment is a monthly card subscription.
Without an active API plan every call made with an API key answers 402, viewer tokens stop working and webhooks are not sent:
402 Payment Required
{ "error": "La API de Ubermach es un servicio pago para integradores…", "code": "plan_limit", "limit": "api" }
Your subscription, keys, connected drones of the month and invoices are all in the developer portal.
Get started
Authentication
Every request carries your API key in the Authorization header. Keys start with ubk_ and belong to your organization, not to a person. Create, see and revoke them in the developer portal → Keys; the full key is shown only once.
Header
Authorization: Bearer ubk_…
The scheme is case-insensitive (Bearer or bearer), followed by one or more spaces and the key.
Client-restricted keys. When you create a key in the portal you can limit it to one client: it only sees and operates that client, and cannot change organization-wide settings (403 client_restricted_key). Use one per client if your system serves many customers, so a bug that mixes customers cannot cross data between them.
A revoked or unknown key answers 401. A valid key without the API plan answers 402. A key without the needed permission answers 403.
Use the API only from your server. The API sends no CORS headers, so browsers on other sites cannot call it, and a key inside a mobile app or a web page can be extracted. To show live video in your app, use the embeddable viewer.
Other credentials
Prefix
Who uses it
For
ubk_
Your server
Everything in this guide under Resources.
ubd_
The phone or connector next to the drone
Sending telemetry, photos and videos, and receiving missions. One per drone. See Phone connector.
vt_
The embeddable viewer in your app
Watching one drone live for a limited time. Your server requests it. See Embeddable viewer.
whsec_
Your webhook receiver
Verifying that a webhook comes from Ubermach. See Webhooks.
Get started
Permissions
Each key has a list of permissions chosen when you create it. Give each system only what it needs: a reporting tool only needs read permissions.
Permission
Allows
—
GET /me and GET /templates: any valid key.
read:devices
List drones and their live state, command history, viewer layouts.
read:telemetry
Telemetry by time range, the live channel, viewer tokens, session tracks and full session telemetry.
read:flights
Flights, sessions and session events.
read:missions
Missions, zones and the approval queue.
read:media
Photos, videos, their files and AI analyses, the AI summary.
control:missions
Create, dispatch and cancel missions.
control:drone
Send direct commands to a drone, only if direct control is enabled in the developer portal. See Direct control.
propose:zones
Propose new zones (they stay pending until a person approves them in Ubermach Flights). See Propose a zone.
Never possible with an API key, whatever its permissions: approving missions, creating or approving zones, managing API keys, direct control settings and billing. These answer 403 and are done by a person in the panel or the developer portal.
Get started
Requests and responses
Item
Rule
Base URL
https://ubermach.com/api/v1
Alias
/api/v1/x3a/… answers the same for the resource routes. Existing integrations use it; new ones should use /api/v1/…. URLs returned by the API (files, tracks, live) still use the alias: follow them as they come.
Format
JSON in and out, UTF-8. File downloads, GeoJSON, NDJSON and CSV are the exceptions.
Body size
JSON bodies up to 512 KiB (413 above). An empty body, or an empty array [], counts as {}; any other body that is not a JSON object answers 400.
Server time
Every response carries X-Server-Time (ms). Compare it with your clock to detect drift: telemetry with a timestamp more than 5 minutes ahead is rejected.
Ids
Strings with a prefix: dev_, msn_, med_, ses_, org_… Treat them as opaque.
Your ids
external_ref, external_id, external_form, external_field: up to 120 characters in every resource. Longer values answer 400 field_too_long; they are never cut.
Times
Milliseconds since the Unix epoch (UTC), as integers.
Coordinates
WGS84 decimal degrees. Points are { "lat", "lng" }; polygons are lists of [lng, lat], like GeoJSON.
Clients
Wherever a route accepts client, you can send the Ubermach id or your own external_ref.
Lists
Newest first. limit sets the page size (each route says its default and maximum; a value that is not a positive integer answers 400). When there are more results the response has next: send it as after to get the next page. since (ms) returns only items from that time on, for incremental syncs. Paged: clients, drones, missions, photos and videos, sessions.
Other organizations
A resource that belongs to an organization you cannot see answers 404, never 403, so ids cannot be probed.
Using your own ids
Send your own identifiers and Ubermach keeps them and returns them in every response and webhook: external_ref for a client, external_id for the task that originated a mission, a session or a file. external_id is for correlation and can repeat (the same task can be flown again). If your system replaces a provisional id with the final one, move everything with re-link an external id.
Safe retries: Idempotency-Key
Send an Idempotency-Key header (up to 120 letters, numbers, ., _, - or :) on POST /missions, unique per operation, for example task-48213:attempt-2. Repeating the request with the same key within 24 hours returns the same response, with Idempotent-Replayed: true, without creating anything new. Creating clients and registering drones are idempotent by themselves (external_ref and serial number).
Errors return an HTTP status and a JSON body. error is a message in Spanish, ready to show to a person. Every error has a stable code: branch on the code, never on the text, which can change. When there is no more specific code, it comes from the status (invalid_request, unauthorized, forbidden, not_found, conflict, unprocessable, rate_limited, internal_error…).
JSON
{
"error": "La ruta no cumple las zonas o la altitud.",
"code": "zone_violation",
"problems": [
{ "index": 3, "problem": "altitud 140 m supera el máximo 120 m" },
{ "segment": 4, "problem": "el tramo entre waypoints cruza una zona no permitida" }
]
}
Status
Meaning
400
Invalid data. The message names the field.
401
Missing, unknown or revoked key (or an expired viewer token: code: "token_expired").
402
A plan limit: code: "plan_limit" with limit = api, devices, flights, storage, ai or live.
403
The key lacks the permission, or the action needs a person in the panel.
404
It does not exist, or it belongs to an organization you cannot see.
405
Wrong method for that route.
409
The resource is not in a state that allows the action (for example, dispatching a mission that is not approved). The message says why.
413 · 415
Body too large, or a content type that is not accepted.
422
A valid request the zones or the drone cannot accept: problems (zones and altitude) or code: "capability_missing".
429
Too many requests on a rate-limited route. Wait the seconds in Retry-After.
5xx
A problem on our side or in a service we depend on (AI, detection). Retry later with backoff.
Stable error codes
Code
Status
Extra fields and what to do
plan_limit
402
limit. Renew or upgrade the plan; retrying will not help.
capability_missing
422
required and what the drone does have (device_control or device_commands). The drone cannot do it: change the mission or the drone. Do not retry.
token_expired
401
Viewer token expired: request a new one from your server.
zone_violation
422
problems lists each waypoint or leg outside the zones or above the allowed altitude.
mission_pending_approval · mission_not_approved
409
The mission is waiting for a person, or is not in a state that can be dispatched. Wait for mission.approved.
device_offline · battery_low · device_busy
409
The drone has not talked to Ubermach in 30 s, its battery is below 30 %, or it already has an active mission.
field_too_long
400
field and max tell which value is too long. Shorten it; it is never cut.
invalid_country · invalid_time_zone
400
Country must be an exact ISO 3166 two-letter code; time zone an IANA name.
What your platform needs to have in place before going live. Each point avoids a failure we have seen in field integrations.
Keys and data isolation
Keep ubk_ and whsec_ in your secret store or environment, never in a database table or in code.
If you serve many customers, consider one client-restricted key per customer. Always send client explicitly.
Never pass Ubermach ids (media, sessions, missions) from a browser to your server without checking that the signed-in user belongs to that client_ref.
Ids and retries
Use your final task id as external_id. If you only have a provisional one (an offline task), send it and re-link it as soon as you have the final id.
Send Idempotency-Key on every mission creation, and make your jobs safe to run twice: a scheduled job that runs on two servers must not create two missions.
Branch on code, never on the error text.
Your webhook receiver
Public https with no redirects: a trailing slash, a language prefix or http→https redirect makes every delivery fail.
Verify the signature over the raw body, store the event, answer 2xx in under a second and process it afterwards.
Ignore repeated X-X3A-Delivery ids and do not rely on arrival order.
After an outage, catch up with the event log instead of waiting for retries.
Time and text
Times are milliseconds UTC. Convert with integer division (intdiv($ms, 1000) in PHP) before storing in a seconds column, and show them in the client's time zone (time_zone of the client).
Text is full UTF-8: AI descriptions can contain any character. If your database cannot store 4-byte characters, turn on ascii_only in the webhook and use utf8mb4 for new tables.
On the phone, compare your clock with X-Server-Time and check rejected in each telemetry answer before deleting points locally.
Drones, zones and approvals
Register each drone by serial number (repeating it is safe) and give each phone its own device key. Do not rotate the original key on every error: it disconnects the other phones.
Manual flights (the pilot flying with the controller) need no mission, zone or approval: open a session and upload what the drone captures.
Autonomous missions need an operation zone for the client and a person who approves. During onboarding, propose the zones and decide who approves; send them the approval_url you get when a mission is created.
Check usage and limits before a field visit so a plan limit does not stop a flight on site.
Resources
Account
Two routes any valid key can call. Use /me as a health check of your credentials when your system starts.
Resources · Account
Who am I
GET/api/v1/me
Returns the organization that owns the key, how many clients it has, the mission templates and the webhook events you can subscribe to.
If your organization is a partner, each of your customers is a client: a child organization with its own drones, zones, missions and files. You identify each one with your own id (external_ref, for example your account number). Organizations that are not partners work with their own drones and skip this section.
Resources · Clients
Create or update a client
POST/api/v1/clientsadmin:clients
Idempotent by external_ref: the first call creates the client (201); later calls with the same external_ref update its name and country (200). Call it every time a customer is created or renamed in your system.
Body
Field
Type
Description
external_ref
string · required
Your id for this customer. Up to 80 characters.
name
string · required
Name shown in Ubermach. Up to 120 characters.
country
string
Exact two-letter ISO 3166 code (US, MX, ES…). Send it always; anything else answers 400 invalid_country.
time_zone
string
Optional IANA time zone (America/Mexico_City), to show local times. Kept if you omit it later.
A drone is registered once, with its serial number. Registration returns its device key (ubd_…), which goes into the phone or connector that flies it. From then on, the drone reports its position and battery and appears online while it has talked to Ubermach in the last 30 seconds.
Resources · Drones
Register a drone
POST/api/v1/devicesadmin:clients
Creates the drone and returns its original device key only once. Idempotent by serial number: registering the same serial again for the same client answers 200 with the existing drone, existing: true and no key, so retrying after a timeout is safe. To give a key to another phone, create a device key.
Body
Field
Type
Description
serial
string · required
Serial number: 4 to 40 letters, numbers or dashes (stored in capitals).
client
string
Client id or external_ref. Without it, the drone is yours.
model
string
Aircraft model, up to 60 characters.
controller
string
Remote controller, up to 60 characters.
nickname
string
Friendly name, up to 60 characters.
adapter
string
How it connects: mavlink, dji_v5, dji_v4, dji_cloud, tello, toy_wifi or import. Loads a default capability profile.
capabilities
object
Full capability profile, if you want to declare it yourself. See Capabilities.
Invalid serial, unknown adapter or an invalid capability profile.
Fix the body; the message names the field.
402 plan_limit
The client's plan does not allow more drones (limit: "devices").
Upgrade the plan or remove a drone.
Resources · Drones
Device keys, one per phone
POST/api/v1/devices/{id}/keysadmin:clients
A drone flown from several phones (or a phone replaced) should not share one key. Create one key per phone or connector: each is shown once, works exactly like the original key, and can be revoked alone without disconnecting the others. Up to 50 active keys per drone. The original key keeps working.
GET /devices/{id}/keys lists them (prefix, label, dates). DELETE /devices/{id}/keys/{keyId} revokes one.
Body
Field
Type
Description
label
string
Optional, up to 120 characters: for example the phone id in your system.
Drones newest first, up to 500 per page (limit, after, since), each with its last telemetry point and its active mission. GET /devices/{id} returns one drone with the same shape.
Query
Field
Type
Description
client
string
Only the drones of this client (id or external_ref).
Points in a time range, newest first. Each point has normalized fields (lat, lng, alt_m, speed_ms, heading_deg, battery_pct, satellites, mode, link_quality) and data, the full object the drone sent (attitude, gimbal, signal, detailed battery, home point…). For a whole flight, the session routes are easier.
Query
Field
Type
Description
from
integer
Start, in ms. Default: one hour before to.
to
integer
End, in ms. Default: now.
limit
integer
1 to 5000. Default 1000.
include_details
1
Also return the connector's per-message records (in data.bridge.record). They do not add points to the track.
The last 100 commands sent to the drone (mission starts, pauses, returns home…) and what happened to each: pending → sent → done or rejected, or expired if the drone did not pick it up in 5 minutes (returns home and landings never expire).
Lets your platform act on a drone in flight: bring it home, land it, pause or resume its mission, take a photo, record or tilt the camera. It is off by default. It only works when all of these hold:
An administrator of your organization turned on direct control in the developer portal → Control.
The key has the control:drone permission.
That command is among the allowed ones, and the drone belongs to an allowed client (or all clients are allowed).
The drone's capability profile supports it.
Your platform decides which of its users see these controls. The pilot stays on site with the remote controller and can take over at any time. Every command is recorded in the audit log with the key that sent it.
Body
Field
Type
Description
type
string · required
return_home, land, pause, resume, take_photo, start_recording, stop_recording or set_gimbal.
Direct control is off (api_control_disabled), the command is not allowed (api_control_command) or the client is not allowed (api_control_client). Also without control:drone.
Ask your administrator to change it in the portal → Control.
409
pause or resume without an active mission, or resume before it started.
Read the drone's active_mission first.
422 capability_missing
The drone cannot do what is asked (no mission control, no camera…).
Do not retry. Change the mission or the drone.
The command waits in a queue (202) until the phone next to the drone picks it up. Follow it with GET /devices/{id}/commands or the command.acked webhook. Commands not picked up in 5 minutes expire, except return_home and land, which never expire and are resent until the drone answers.
Resources · Drones
Rotate a device key
POST/api/v1/devices/{id}/rotate-keyadmin:clients
Generates a new ubd_ key. The old one stops working at once and the drone's live connection is closed, so the phone must be updated with the new key. Use it when a key is lost or a phone is replaced.
Response · 200
JSON
{ "id": "dev_4k2p", "ingest_key": "ubd_…" }
Resources
Capabilities
Each drone has a capability profile: how it can be controlled, which commands it accepts, its camera and its sensors. The API rejects up front what the drone cannot do (422 capability_missing) instead of queuing it. A drone without a profile is not checked.
Field
Values
control
missions (flies missions), manual (direct commands only) or none (import only). Missions need missions.
{ photo, video, live, gimbal }, booleans. Photo actions need photo; video actions need video. A gimbal angle on a drone without gimbal is only a warning.
Where the profile comes from (capabilities_source): declarado (you or the adapter default), bridge (what the connector detected on the real drone, which replaces what was declared) or sesion.
Resources · Capabilities
Declare or fix a profile
PUT/api/v1/devices/{id}/capabilitiesadmin:clients
Send capabilities, or just an adapter to load its default profile. It is only written (and audited) if something changed. If the connector later reports what it detects, that wins.
Unknown adapter, invalid profile, or neither capabilities nor an adapter with a default profile.
Fix the body.
Resources
Missions
A mission is what you ask the drone to do. You create it from a template or with your own waypoints; Ubermach validates it against the client's zones; an administrator approves it in Ubermach Flights (it can be the same person who created it); you dispatch it; the pilot confirms the take-off on the remote controller; and webhooks tell you when it starts and finishes, with every photo.
draft
→
approved
→
dispatched
→
running
→
done · aborted
Status
Meaning
Webhook
draft
Created and validated, waiting for an administrator's approval.
mission.created
approved
Approved in the panel. You can dispatch it.
mission.approved
dispatched
Sent to the drone. Waiting for the pilot to start it. If the drone rejects it, it goes back to approved.
mission.dispatched
running
The drone is flying it.
mission.started
done
Finished. The webhook carries every file.
mission.completed
aborted
Cancelled by you, or the drone landed before finishing.
mission.cancelled · mission.completed
Resources · Missions
Create a mission
POST/api/v1/missionscontrol:missions
Creates a mission for one drone, from a template or from your own waypoints. The route is checked against the client's operation zones, exclusion zones and the 120 m ceiling before it is saved, and the drone's capabilities are checked too. A new mission is always draft: an administrator approves it in Ubermach Flights, then you dispatch it. Take-off always needs the pilot's confirmation on the remote controller.
Body
Field
Type
Description
device_id
string · required
The drone that will fly. Must belong to you or one of your clients.
template
string
fotos_lugar, punto_fijo, relevamiento_area, fachada or video_recorrido, with its params.
Instead of a template: 1 to 200 points { lat, lng, alt_m, heading_deg?, gimbal_pitch?, action? }. heading_deg 0–360, gimbal_pitch −90 to 30, action = photo, start_recording or stop_recording.
name
string
Up to 120 characters. Default: the template name.
external_id
string
Your task id (up to 120). Without Idempotency-Key, sending it again while that mission is still open returns it (200, existing: true); after it finished or was aborted, a new mission is created, so the task can be flown again. With Idempotency-Key, the key decides.
ai
object
Analyze every photo automatically: { "mode": "detect" | "describe" | "ask", "prompt" }. prompt (up to 500) is required with ask.
Invalid template parameters or waypoints, or an invalid ai block.
Fix the body; the message names the problem.
404
The drone does not exist or is not yours.
Check the id and the organization of the key.
422 problems
The route leaves the operation zones, enters an exclusion zone, crosses one between waypoints, or goes above the allowed altitude. Also when the client has no operation zone.
Fix the route with the list in problems, or ask the client to draw a zone in Flights.
422 capability_missing
The drone cannot do what is asked (no mission control, no camera…).
Do not retry. Change the mission or the drone.
Send Idempotency-Key to make retries safe (see Requests). approval_url opens the approval queue in Ubermach Flights: send it to whoever approves (an administrator of your organization or of the client). warnings lists non-blocking notices (for example, a gimbal angle on a drone without gimbal). The old dispatch: true option no longer dispatches: the response explains it in dispatch_error.
Resources · Missions
List missions
GET/api/v1/missionsread:missions
Newest first, paged with after and next; since for incremental syncs. Filter to find the missions of one of your tasks with external_id.
A person with the administrator role approves the mission in Ubermach Flights → Approvals; it can be the same person who created it. The route is validated against the zones again. No API key can approve: it answers 403. Listen for the mission.approved webhook, or read the approval queue.
Sends an approved mission to the drone (no body). Checks, in this order, that the mission is approved, that the drone can fly missions, that it is online (it talked to Ubermach in the last 30 seconds), that its last reported battery is at least 30 %, that it has no other active mission, and that the route still complies with the zones. The pilot then confirms the take-off on the remote controller.
The drone has not talked to Ubermach in the last 30 seconds.
Ask the pilot to power it and connect the app; retry.
409 battery_low · device_busy
Battery below 30 %, or the drone already has an active mission.
Change battery or wait for the other mission.
422 capability_missing
The drone cannot do what is asked (no mission control, no camera…).
Do not retry. Change the mission or the drone.
422 problems
The route leaves the operation zones, enters an exclusion zone, crosses one between waypoints, or goes above the allowed altitude. Also when the client has no operation zone.
Fix the route with the list in problems, or ask the client to draw a zone in Flights.
Idempotent: dispatching a mission that is already dispatched or running answers 200 with already: true.
Resources · Missions
Re-link an external id
POST/api/v1/external-ids/remapcontrol:missions
When your system replaces a provisional id with the final one (for example a task created offline on the phone), move every mission, session and file from from to to in one operation. Only within what the key can see; use client to limit it to one client.
Moves the mission to aborted from any open status. If it was dispatched, its pending commands expire. If the drone is already flying it, a return-home command is queued automatically and its id comes back in the response.
A template builds the waypoints for you from a few parameters. Values outside the range answer 400; missing optional values take the default. Altitudes are in meters above the take-off point, and the zones always have the last word.
center required · alt_m 5–120 (40) · gimbal_pitch −90–0 (−45)
relevamiento_area
Grid survey over a polygon, with overlap, for maps and models.
area 3–500 points [lng, lat] · alt_m 20–120 (60) · front_overlap 0.5–0.9 (0.75) · side_overlap 0.4–0.9 (0.65) · camera_hfov_deg 40–120 (82) · gimbal_pitch −90–0 (−90). At most 200 photos.
fachada
Columns of photos facing a façade between two points A → B.
area [A, B] at least 2 m apart · side left | right (left) · standoff_m 5–60 (15) · alt_min_m 2–120 (5) · alt_max_m 2–120 (30) · vertical_step_m 2–30 (5) · horizontal_step_m 2–50 (8). At most 200 photos.
video_recorrido
A path with continuous video from the first to the last point.
Zones are geofences drawn by the client's administrators in Ubermach Flights → Zones. There are three kinds: operacion (missions may only fly inside one), restringida (with its own maximum altitude) and exclusion (no flying). Without at least one operation zone, no mission can be created for that client. Your key can read zones but never create, change or approve them.
Resources · Zones
List zones
GET/api/v1/zonesread:missions
Current zones (active) and proposals waiting for approval (pending). A pending proposal does not count yet when routes are validated. Use client to choose the client.
Proposes a new zone for a client. It is born pending and does not count for missions until a person with the administrator role approves it in Ubermach Flights → Approvals. No API key can approve, change or remove zones. Useful during onboarding: propose the operation zone of each site from the coordinates you already have.
Body
Field
Type
Description
client_id
string
Client id or external_ref.
name
string · required
Up to 80 characters.
kind
string · required
operacion · restringida · exclusion
ring
array
3 to 500 vertices [lng, lat].
center · radius_m
object · number
Instead of ring: a center { lat, lng } and a radius of 10 to 5000 m.
What is waiting for a person: draft missions of the last 30 days and zone changes, plus what was decided in the last 24 hours. Missions you created appear as requested by “Integración (API)”.
Every file the drone captures arrives with its position, time, SHA-256 hash and, if requested, its AI analyses. Files are linked to their mission, session and to your external_id, so you can attach them to your task.
Returns the binary file. The organization that owns the photo receives the original. Any other organization that can see it (for example, a partner looking at a client's photo) receives a watermarked copy: “UBERMACH” tiled, plus a strip with the id, UTC time, position and the start of the original's SHA-256. Videos are always delivered as originals.
preview (small JPEG), original (owner only) or watermarked (anyone, also the owner, to share it).
What can go wrong
Status
When
What to do
403
variant=original from an organization that does not own the photo.
Use the watermarked copy.
404
No preview for that file, or the file is not available.
Ask for the original.
Resources
AI analysis
Ubermach can analyze photos (not videos) in three modes. Ask for it on demand, or automatically for every photo of a mission (ai when creating it). Results are stored with the photo and arrive by the analysis.completed webhook.
Mode
Result
detect
Objects with label, score (≥ 0.5) and box, up to 50, plus counts of people and vehicles. A general model, not specialized in aerial imagery.
describe
{ "text" }: a description of the scene in Spanish.
ask
{ "question", "answer" }: the answer to your question about the photo.
Resources · AI
Analyze a photo
POST/api/v1/media/{id}/analyzeai:analyze
Each call creates a new analysis and counts towards the client's AI photos of the month.
Body
Field
Type
Description
mode
string · required
detect, describe, ask
prompt
string
Your question, required with ask. Up to 500 characters.
Request
cURL
API=https://ubermach.com/api/v1
KEY="Authorization: Bearer ubk_…"
curl -X POST $API/media/med_7hq/analyze -H "$KEY" \
-H "Content-Type: application/json" \
-d '{"mode":"ask","prompt":"¿Hay daños visibles en el techo?"}'
A video, an unknown mode, or ask without a prompt.
Fix the request.
402 plan_limit
The client reached its AI photos for the month (limit: "ai").
Upgrade the plan or wait for next month.
409
A photo over 5 MB without a preview.
The phone must upload its preview first.
502 · 503
The AI did not answer, or it is not enabled.
Retry later.
Resources · AI
Analyses and monthly summary
GET/api/v1/ai/analysesread:media
The latest analyses with their photo, drone and mission. Filter with client, mode (detect, describe, ask or skipped for photos not analyzed because of the plan) and limit (up to 200, default 50).
GET /api/v1/ai/summary returns the current month: analyses by mode, detections by class and skipped photos. PUT /api/v1/ai/settings with { "ai_auto": "detect" | "describe" | null } (permission ai:analyze) turns automatic AI on or off for every uploaded photo.
Resources
Flight sessions
The phone opens a session for every flight and closes it when it lands. Everything captured — telemetry, events, photos, videos — is linked to it, and on close Ubermach computes a summary and sends session.closed. Sessions carry your external_id, so you can find the flights of one task.
The session, its flight (points, distance, maximum altitude) and its files (up to 500). GET /sessions/{id}/events returns its events (log, alert, mode, command, link), limit up to 2000, default 500.
The flight path as a GeoJSON FeatureCollection with one LineString, at most one point per second; properties.coord_times has the time of each coordinate. Ready for any map library.
GET /sessions/{id}/telemetry streams every point of the session: format=ndjson (default, one JSON per line) or format=csv (columns ts, lat, lng, alt_m, speed_ms, heading_deg, battery_pct, satellites, mode, link_quality, data). Add include_details=1 for the connector's detailed records.
A flight is the track Ubermach builds from telemetry, with or without a session. Without a session, a gap of more than 2 minutes closes the flight and opens a new one.
Resources · Flights
Flights of your organization
GET/api/v1/flightsread:flights
Your organization's flights, newest first. Filter with device_id; limit up to 200, default 50. GET /api/v1/flights/{id} returns one.
This route only sees the key's own organization. To see a client's flights, use GET /devices/{id}/flights or the sessions. It has no /x3a alias.
Resources
Live channel
A WebSocket that pushes what the drone is doing as it happens. Open it from your server with your key; to show live video to your users without exposing your key, use the embeddable viewer.
On connect you receive a snapshot with the last point and whether the drone is online; then telemetry (at most 5 per second), event and presence. You may send {"type":"ping"} (answered with pong); anything else you send is ignored.
Request
Node.js
import WebSocket from "ws";
const ws = new WebSocket("wss://ubermach.com/api/v1/devices/dev_4k2p/live", {
headers: { Authorization: `Bearer ${process.env.UBM_KEY}` },
});
ws.on("message", (raw, isBinary) => {
if (isBinary) return; // video frames, only with ?video=1
const msg = JSON.parse(raw);
if (msg.type === "telemetry") console.log(msg.point.lat, msg.point.lng, msg.point.battery_pct);
});
The client's plan does not include live view (limit: "live").
Upgrade the client's plan.
426
The request was not a WebSocket upgrade.
Use a WebSocket client.
429
50 viewers (or 10 with video) already connected.
Share one connection in your server.
Video
With ?video=1 you also receive the drone's video as binary messages: byte 0 is the type (1 H.264 key frame in Annex B with SPS/PPS, 2 H.264 delta, 3 JPEG), bytes 1–8 are the capture time in ms (float64, big-endian), and the rest is the frame. You get the last key frame right after connecting. In a browser it decodes with WebCodecs (VideoDecoder).
Resources
Embeddable viewer
To show a drone's live video inside your own app or website, without decoding anything and without exposing your key: your server asks for a short-lived token, and your page shows an iframe with the embed_url it returns. The viewer brings the HUD (altitude, speed, battery, map…), the watermark and the reconnection logic.
Resources · Viewer
Get a viewer token
POST/api/v1/devices/{id}/live-tokenread:telemetry
Only with an API key, from your server. The token is only valid for this drone. Ask for a new one each time a user opens the view.
Body (optional)
Field
Type
Description
ttl_s
integer
Lifetime in seconds, 60 to 3600. Default 600.
layout
string
HUD layout name (lowercase letters, numbers and dashes, up to 40).
role
string
viewer (default) or designer, which can also edit and save layouts and needs admin:clients.
Request
HTML
<!-- your server inserts embed_url -->
<iframe src="https://ubermach.com/embed/live/dev_4k2p#token=vt_…"
width="960" height="540" allow="fullscreen"></iframe>
The viewer emits token_expired: ask your server for a new token and reload the iframe.
403
Requested with a panel session instead of a key, or designer without admin:clients.
Request it from your server with the right key.
Resources · Viewer
HUD layouts
PUT/api/v1/viewer/layouts/{name}admin:clients
Create or replace a HUD layout, for all your clients or for one (?client=). GET /viewer/layouts (read:devices) lists yours and the presets completo, minimo, busqueda and solo-video; DELETE /viewer/layouts/{name} removes one.
Up to 24 elements. type: estado, bateria, alertas, altura, velocidad, gimbal, horizonte, mapa, rumbo, mision, hora, coordenadas. anchor: top-left, top, top-right, left, center, right, bottom-left, bottom, bottom-right. x/y offsets up to ±1080, size S, M or L, visible.
Ubermach calls your server when something happens, so you do not have to poll. One webhook per organization (your clients' events go to yours). Configure it with PUT /webhook; the response brings the signing secret only once.
Resources · Webhooks
Configure the webhook
PUT/api/v1/webhookadmin:webhooks
Body
Field
Type
Description
url
string · required
Public https address. Local and private addresses are rejected.
events
array
Events to receive. Empty or missing: all of them.
rotate_secret
boolean
Generate a new secret (the old one stops signing).
ascii_only
boolean
Send non-ASCII characters escaped as \uXXXX. Same JSON for any parser; for receivers whose database cannot store 4-byte characters.
Not https, a private address, or an unknown event.
Fix the body.
403
The key belongs to a client organization: webhooks are configured on the partner.
Use the partner's key.
GET /webhook shows the configuration (without the secret), DELETE /webhook turns it off, POST /webhook/test sends a ping, and GET /webhook/deliveries lists the last 50 deliveries with their status, attempts and last error.
What arrives
Each delivery is a POST with a JSON body { event, created_at, org_id, data }. org_id is the organization where it happened (one of your clients, or you).
The above + ended_at, summary, track_url, media[] (up to 200; media_truncated if more)
session.updated
Late telemetry arrived for a closed session.
Same as session.closed
ping
You called POST /webhook/test. Always sent, whatever your event filter.
message
Verify the signature
v1 is the hex HMAC-SHA256 of t + "." + raw body, keyed with your whsec_ secret. Compute it over the raw body, before parsing the JSON, compare in constant time, and reject timestamps older than 5 minutes.
Answer with any 2xx within 8 seconds. Redirects are not followed and count as a failure.
Up to 7 attempts over about 21 hours: right away, then about 1 minute, 5 minutes, 30 minutes, 2 hours, 6 hours and 12 hours after each failure (retries run every 5 minutes, so short waits round up). After the seventh failure the delivery is marked failed; you can redeliver it.
Delivery is at least once: the same event can arrive twice. Use X-X3A-Delivery (stable across retries) to ignore duplicates. Order is not guaranteed: rely on created_at and on the resource status.
Process slow work after answering: save the event, answer 200, then handle it.
Resources · Webhooks
Event log and redelivery
GET/api/v1/webhook/events?after=admin:webhooks
Every event addressed to your webhook in the last 30 days, oldest first, with the same body you receive. After an outage, read from the last delivery_id you processed (after) until next_after is null, instead of waiting for retries. limit up to 500, default 100.
POST /webhook/deliveries/{id}/redeliver sends one delivery again, with the sameX-X3A-Delivery, so your receiver recognizes it if it had already processed it.
Each client may have its own Flights plan with limits on drones, flights, storage, AI photos and live view. When a limit is reached the API answers 402 plan_limit, even in the middle of a field visit. Check before the visit.
Resources · Usage
Usage and limits of a client
GET/api/v1/usage?client=read:devices
The current month for one client (or for your organization without client). plan: null and limits: null mean no Flights limits apply. One client per call.
This part is for whoever builds the app or connector that runs next to the drone (an Android app with the DJI SDK, a MAVLink connector…). If you only integrate from your server, you can skip it: Ubermach's own app already does all of this.
Each drone has its original ubd_ key, returned once when it is registered. Give each phone or connector its own extra key with device keys, so you can revoke one without disconnecting the others. A key can only act on its own drone.
Send it as Authorization: Bearer ubd_…. An unknown or revoked key answers 401 invalid_device_key.
Use the X-Server-Time header of any answer to correct the phone clock: telemetry more than 5 minutes ahead of the server is rejected.
Every call marks the drone as connected this month (that is what is billed per drone) and as online for 30 seconds.
The phone usually talks to the drone over one network and to the internet over another. Calls to Ubermach must go out over a network with internet (normally mobile data); with Wi-Fi drones, bind only the drone's sockets to its Wi-Fi network.
These routes live under /api/v1/x3a/… (also /api/v1/…), except telemetry ingestion and commands, which only exist as /api/v1/ingest/telemetry and /api/v1/bridge/commands.
Phone connector
Sessions and telemetry
Phone connector · Sessions
Open a session
POST/api/v1/x3a/bridge/sessionsubd_
Open one session per flight, before take-off. Idempotent by client_session_id: a retry returns the same session with 200 instead of 201.
Body
Field
Type
Description
client_session_id
string · required
Your id for this flight: 8 to 64 letters, numbers, _ or -.
external_id · external_form · pilot_ref
string
Task, form and pilot in your system (up to 80 each).
The client reached its flights for the month (limit: "flights").
Tell the pilot; the plan must be upgraded.
Close it after landing with POST /bridge/sessions/{id}/close (ended_at, battery_end_pct, note). Closing twice returns the same summary; only the first close sends session.closed. Send flight events in batches of up to 200 with POST /bridge/sessions/{id}/events (ts, type = log · alert · mode · command · link, data up to 2 KB, optional uid to deduplicate).
Phone connector · Telemetry
Send telemetry
POST/api/v1/ingest/telemetryubd_
Batches of 1 to 400 points (200 recommended). Send session_id so the points go to that flight. Points are idempotent by time: resending a batch after a timeout does not duplicate anything. Points older than 30 days or more than 5 minutes in the future are dropped; out-of-range values are stored as null. The whole point is kept in data (up to 4 KB).
Check rejected before deleting points locally. Points with an invalid time, older than 30 days or more than 5 minutes in the future are not stored; rejected says how many, why and their time range. If every point of the batch was rejected, the answer is 400 no_valid_points with the same detail. With a session, points in the future also leave an alert event with code: "clock_skew".
Use the live_url of the session. Send {"type":"telemetry","point":{…}}, {"type":"event","event":{…}}, {"type":"ping"} and video frames as binary messages (same format as the live channel, up to 40 frames per second and 1 MB per frame). Nothing sent here is stored: keep sending telemetry to ingest/telemetry. One publisher per drone: a new connection replaces the previous one (close code 4000); a closed session or rotated key closes it with 4001.
Phone connector
Missions and commands
Phone connector · Commands
Fetch commands
GET/api/v1/bridge/commandsubd_
Poll every few seconds while the app is connected. Returns up to 20 pending commands (a dispatched mission arrives as mission_start with its waypoints) and marks them sent. Returns home and landings without an answer are sent again after 10 seconds. Answer each one with an ack. Before starting a mission, the app must ask the pilot to confirm the take-off on the remote controller.
POST /api/v1/bridge/commands/{id}/ack with { "status": "done" | "rejected", "detail" }. A done on mission_start moves the mission to running; a rejected sends it back to approved. When the flight ends, call POST /bridge/missions/{id}/complete with status = done or aborted (landed before finishing).
Phone connector · Capabilities
Report capabilities
PUT/api/v1/x3a/bridge/capabilitiesubd_
Send { adapter, capabilities } with what the app detects on the real drone. It replaces what was declared and is only written if it changed.
The body is the file itself (JPEG, PNG, DNG or a short MP4, up to 50 MB) with its Content-Type; the metadata goes in the query. Idempotent by content: uploading the same file again returns 200 with duplicate: true. Sends media.created and runs the automatic AI if the photo is up to 5 MB. For larger photos, upload a JPEG preview with PUT /bridge/media/{id}/preview.
Query
Field
Type
Description
session_id · mission_id
string
Link the file to the flight and the mission.
external_id · external_form · external_field
string
Where it belongs in your system (up to 80 each).
external_filename
string
Original file name: letters, numbers, ., _, -, up to 120.
For MP4 videos up to 4 GiB, resumable. 1. Start with { content_type: "video/mp4", bytes, sha256, session_id, external_*, taken_at, duration_s }: you get upload_id, media_id, part_size (10 MiB) and total_parts. If an upload of the same sha256 is open, it is returned with parts_done so you can resume; if it is complete, you get complete: true. 2. Send each part with PUT /bridge/uploads/{id}/parts/{n} (from 1, exact Content-Length; repeating a part replaces it). 3. Finish with POST /bridge/uploads/{id}/complete, which creates the file and sends media.created.
If complete answers 409 with missing, upload those parts and call it again. GET /bridge/uploads/{id} shows the progress; DELETE aborts it. The hash is the one the phone declared, so videos come with sha256_verified: false.
Real-time detection for the pilot's screen. multipart/form-data with imagen (JPEG up to 2 MB), optional session_id, grupos (comma-separated: personas, livianos, pesados, dos_ruedas) and conf (0.1 to 0.9). Returns the objects with a tracking id and a box normalized 0–1. At most 3 frames per second per drone (429 with Retry-After).
