API Reference

This page maps the routes: method, path, who may call it. API Routes, API Schemas and openapi.json are generated from the contracts and carry every field. Here is what they cannot say.

Two APIs, one command surface

• REST (api.fleetless.dev) — polling, history, action and service calls, publishes, snapshots, URDF and assets, and users.
• Realtime (WebSocket, same host, /realtime) — subscriptions on datapoints, action state and bridge_state, plus full command parity: everything REST can do works over the same connection.

Every subscriber of a datapoint gets its configured send rate, not one stream each.

Errors

Every rejection carries a stable error code. Validation failures name the field and the rule.

Plan errors

A plan limit or a feature the plan does not have is refused with its own code, and the details say what lifts it. See Plans and Limits.

Billing errors

The /api/billing routes are owner-only: a developer gets 403 tier_required. Billing refusals name the field and the rule, as validation errors do.

A refused or unanswered payment changes nothing. See Paying.

The validation_error rules a billing route can name:

The target_state_conflict rules name what the org’s billing state refuses: plan already_billed (the checkout for a plan the org already pays for), billing no_account, past_due and no_valid_mandate (a change that needs a payment method on file), billing vat_id_invalid (a charge, or paying a renewal on hold, while VIES does not confirm the VAT ID), billing charge_in_progress (an earlier change is still being settled with Mollie; try again later), and invoice not_open (paying an invoice that is already paid or cancelled).

POST /api/billing/mollie/webhook is Mollie’s callback and not for developers: it takes the payment id from Mollie and fetches the payment itself.

Asset errors

One file has its own limit, apart from the storage.

/api/admin/* is the operator’s surface. Public hosts answer 404 for every path under it, and it is not described here.

Job errors

Job.error.code on a failed, unknown, lost or cancelled job — the codes below, open-ended like every other error code, but worth naming once rather than left to grep:

A restart on either side is not a loss. The bridge keeps which goal belongs to which job in FLEETLESS_STATE_DIR and names the jobs it recognises when it reconnects; one it does not know ends lost, job_unknown_to_bridge, under the rule above. A cloud restart leaves every Fleetless job that was in flight unknown (bridge_disconnected) until its robot’s bridge reconnects and answers — GET /api/org/jobs?state=unknown lists them meanwhile.

busy and parameter_invalid are refusals of the invoke/call itself, not a job outcome — see the SDK reference. The refusals of a cancel, cancel_rejected among them, are under Cancelling a job.

Job origin and external goals

job.origin says who started a job: fleetless for everything minted by an invoke, external for a goal the bridge found active on a published action without having sent it — anyone else’s goal on the robot’s ROS graph. An external job has the same shape, the same states and the same live stream as any other, but no parameters, no starter, and it lives only in memory: never written to job history, never counted towards quotas.

A busy refusal’s details.running names the job that holds the slug, state and origin included, so a caller can tell “wait for it” from “someone else is using this slug”. Cancelling an external job works exactly like cancelling any other — by its id, or by slug for whatever is running — and is audited goal by goal, with the action server’s answer; see Cancelling a job. Cancelling an unknown job the bridge does not know cancels every external goal still active on its action instead, since one of them may be that very job — never another Fleetless job.

Only an explicit cancel does that: when a republish changes or removes an action, the cancel the cloud sends for the job it resets stops that Fleetless job alone and never an external goal — from bridge 6.1.0.

A slug held by a job — running, unknown or external — stays held while the robot is offline: a start there is refused busy, naming that job, before robot_offline is even considered.

Health

Developer auth

There is no password and no POST /api/auth/login. A developer signs in at the auth portal below, of which the console is an OAuth client, by an emailed code or a passkey. In closed beta, sign-up answers 403 signup_closed.

These answer a <form> post with a page and a JSON post with JSON. A console sign-in is never a password: single sign-on is per-app.

App-user auth (the client auth API)

Fleetless renders no page for an app user — your app owns every screen, and these routes are what it calls. CORS is answered for the app’s allowed_origins on every status, refusals included, so a 400 or 429 arrives readable rather than as an opaque error. The model is in Manage Users and Roles, the working code in the app starter.

The enumeration discipline is the design’s, not a preference. register, resend-verification, password/reset and login/code answer 202 whether or not the address exists, and login and login/code/verify answer one invalid_credentials / invalid_code for a wrong password or code, a blocked account and an unverified one alike. Past rate_limited and validation_error, which every route here carries, the refusals are about the app and never a person: 403 registration_closed, 403 domain_not_allowed, 404 not_found, 409 quota_exceeded, and 409 target_state_conflict for an app with no default role.

An app with no verify_url is not refused: the mail links the hosted confirmation page. password/* and login answer 403 method_not_allowed while the app’s sign_in_methods has passwords off, login/code and login/code/verify while it has the email code off.

Every step that can mint a session answers a sign-in result: tokens, or a challenge first. login, login/code/verify, verify-email, password/reset/confirm and invitations/accept all answer either the session tokens ({ access_token, refresh_token, expires_in }) or { status: 'two_factor_required' | 'two_factor_setup_required', challenge }. Only the challenge carries status, so that is how to tell the two apart.

A user with a confirmed authenticator, or whose app requires one, never gets a session without it. oidc/exchange is the one exception: the provider already owns that sign-in, so it always answers tokens. A challenge is spent at two-factor/verify (or, for the setup case, two-factor/setup then two-factor/setup/confirm), both answering the session.

Org

next_cursor === null is the only end-of-data signal on /api/org/jobs; an over-large limit is refused, not capped, and the window parameters have no defaults. None of these has a client-facing twin: a run row names the actor who invoked it.

/api/org/usage answers one row per metric, per day, and per app where the metric has an app dimension.

app_id: null means the org itself, and what that implies depends on the metric. On the two with an app dimension it is console traffic, not billable; on the other three every row carries it and every one is. Both byte metrics are each day’s peak, not a daily total.

The team (Fleetless users)

Two identity spaces, and nothing joins them: Fleetless users are the org’s team and hold console access, app users belong to one app. A Fleetless user’s address is globally unique across the platform, so an invitation to a claimed one is refused email_taken.

Re-issuing mints a fresh link onto the same row, so the old one stops resolving at once. Limited to once a minute per invitation, refused with 429 and details.retry_after_ms.

Apps

DELETE .../server-keys/:keyId removes the row, not just the secret. rotate invalidates the old secret and keeps the key; DELETE is for a key that should stop existing, and it closes any /realtime socket on it.

Deleting an app cascades its users, roles, server keys, invitations, OIDC provider configuration and mail templates, recorded once as app.deleted carrying an appDeletionSummary — the same shape deletion-preview answers, computed by the same function, so the confirmation and the eventual receipt agree by construction. Its robots are untouched: they belong to the organisation, not the app. No force parameter, unlike the robot pair this route is modelled on — a robot’s open live session is a hazard worth naming explicitly, and an app has no equivalent state to force past, so the preview is the guard instead.

An app identifier may not be mcp, oauth, welcome, healthz, realtime or bridge — each is a fixed segment of the MCP host.

An app’s users

status accepts only active and blocked on the patch. pending_verification is entered once, by self-registration, and left once, by spending the mailed token; setting it back would void a verified address.

A re-issued invitation answers a new id: the row is replaced, so the previous id is a dead handle.

An app’s auth configuration

How people get into one app: the policy, the origins, the app-hosted URLs, the providers.

Five slice writes, one document. Each PUT is .strict(): every field of its own slice arrives or the write is refused, so a client built against an older shape cannot silently clear a setting it does not know about. The merge is server-side, against the stored row, never the caller’s copy — five screens carving up one all-required request is how a field nobody’s screen shows becomes a field somebody’s save clears.

oidc_callback_url, hosted_logo_url, hosted_pages and updated_at are the server’s on every slice and refused in the body. The logo is the one exception to “one document”: it travels as its own raw-body write, not a JSON field, because it is binary.

allowed_origins is both the CORS allow-list and the redirect-URI check, and its entries are bare origins: scheme, host, port, nothing longer. An entry carrying a path compares unequal forever, so it is refused on the write.

None of the four link URLs is refused for being unset any more. invite_url, verify_url, reset_url and mcp_login_url each carry their placeholder exactly once when you do set them — {token} for the first three, {interaction} for the last — and nothing checks that a set URL resolves. Leave one unset and hosted_pages names the Fleetless page that takes its place; see Create an App.

Robots

exposes on GET /api/robots and /api/robots/:id/exposures disagree on purpose, and both are correct. exposes is five counts from the latest published configuration, never the draft. /exposures lists every grantable slug and prepends the built-ins — bridge_state and robot_details — a set that can grow, so the difference is not a number to hard-code.

Configuration (draft/publish)

A configuration is written as text. PUT .../config/draft takes { "source": "<the fleetless.yaml>" } and nothing else, so the server is the one account of what it says. Reads give you the parsed doc and source, the author’s text, never null. Saving asks only whether that text is YAML; publish asks whether it is a fleetless.yaml.

On a draft, doc can be null: the text does not parse to a configuration, which is not the same as nothing being configured. The last published version is untouched and the robot is still running it, so a view built out of doc must tell the two apart. Such a draft is never clean — its issues carry draft_not_a_document.

POST .../config/rename-slug is one atomic transaction across the draft entry, the app-role grants, the alert and chart-display rows, and the recorded history. The published config is immutable, so requires_publish: true is not a suggestion: until the publish lands the bridge still reports the old slug, and those samples are never moved.

Alerts

The org route takes ?state=firing, required and the only value it accepts.

Alerts are defined in the configuration document, not through this API — an alert is a key under the datapoint it watches, so there is no create, patch or delete route. See alerts.

These routes return runtime state: ok or firing, since when, and the value at the last transition. Across a publish an unchanged condition keeps its state, a changed one resets to ok, a deleted key takes its state with it.

Commands (jobs, publishers)

See When the link drops for the semantics behind cancel, timeouts and failsafes.

Cancelling a job

POST .../jobs/:slug/cancel takes { "job_id": "…" } to cancel that job alone, or no body to cancel whatever runs on the slug. The cloud answers once the robot’s action server has answered the cancel request — ROS 2’s CancelGoal, one return code per goal the cancel reached:

An accepted cancel is not an ended goal. Whether the goal ends, and how, is what the action reports afterwards: the job’s cancelled (or any other end) arrives as its next update, over subscribe or GET .../jobs/:slug.

A named job_id of an unknown job the bridge does not hold cancels every external goal active on the action, each listed in the answer, and never one of Fleetless’s own jobs. The realtime cancel answers the same way in its command_result (ok: false, code, details.goals), and so does the MCP tool job_cancel.

A republish that changes or removes the action cancels its job on its own (cancelled, config_changed). That cancel stops only the Fleetless job it names, never an external goal, even when the job is unknown — from bridge 6.1.0; bridge 6.0.0 still treats it like a cancel of an unknown job.

Every cancel that reached the robot is audited per goal: one job.cancelled event for each goal in the bridge’s answer, carrying robot_id, the slug as target, job_id, goal_id, origin and the server’s return_code — for every return code, a refused cancel included — with the caller as actor. A job the answer does not list, because none came in time or the robot went offline, still gets its event, without a return_code. A refusal before anything was sent (not_found, not_cancellable, robot_offline up front) and a slug cancel that found nothing running write no event.

GET .../jobs/history is the per-robot half of /api/org/jobs and shares its paging rules; an app user’s role must carry action_history or the read answers 403 capability_required.

An app user sees only runs their role grants, and that filter runs after the page is read — so a narrow role gets a page of two where it asked for fifty, with a good cursor behind it.

Cameras

See Cameras for snapshot versus live semantics.

Assets (URDF, meshes)

See URDF & meshes for the authorization model.

The robots share the organisation’s asset storage, the robots times the plan’s allowance per robot, and a single file can be at most one gigabyte, the URDF included: a larger one answers 413 file_too_large with max_bytes and size_bytes. A file that would not fit the storage answers 409 plan_limit with the plan-limit details plus store_bytes (the storage), used_bytes and size_bytes, and the sync moves on to the next one; the URDF itself is never refused for the storage, and never counted against used_bytes. Reconcile after every sync frees whatever the new URDF stopped referencing, and DELETE .../assets clears the store outright, unless a sync is running, which is 409 busy.

A sync ends succeeded only if the cloud’s own store holds something. stored and announced say how many of the announced files — the URDF and every mesh its description references — actually arrived; stored is null until the robot reports the sync done. A robot that reports a clean finish over a store that holds none of them ends failed, with an upload_failed entry naming each missing file.

The two /api/asset-links routes take no bearer: the token is the authorization, minted for an agent whose MCP session token REST refuses. A link is a bearer capability for its lifetime.

OAuth 2.1 / MCP

OAuth for apps is gone. Apps use the JSON client auth API above. What still speaks OAuth is two MCP authorization servers, one central and one per app, plus the console’s own sign-in documented at the top of this page.

The central MCP server: Fleetless users

One server for the org’s team, at POST /mcp. Every Fleetless user has access; there is no override.

Dynamic client registration is supported, public clients only. The well-known id fleetless-central-mcp is the fallback for a tool without it, and the one client with no consent step; central consent is per connection and nothing is stored.

Hand out https://mcp.fleetless.dev — pathless; that vhost rewrites POST / and the root discovery documents onto their suffixed forms. But https://api.fleetless.dev/mcp stays the canonical resource identifier every audience is minted from.

An app’s MCP server: that app’s users

One server per app, switched on by mcp_enabled, with the login delegated to the app.

The app decides the interaction through the client auth API above, with the app user’s own access token, and it lives ten minutes. An unauthenticated caller cannot tell “this app exists but MCP is off” from “no such app”: both answer one 404.

Gating is checked at login and again on every single request, against the rows as they are now rather than a value cached off the token: mcp_enabled, the user’s status, the standing consent behind the client. Withdrawing that consent answers that client 401 at its next call.

Hosted pages for app users

Plain server-rendered forms on the auth portal, under /app/<identifier>/…; the page an unset invite_url, verify_url, reset_url or mcp_login_url falls back to (see Create an App). Every one calls the same /api/client/* route a page of your own would — there is no second policy.

Every GET here renders a page and spends nothing; the token or code is spent only by the form POST the page submits, so a mail scanner or link preview opening the GET leaves it untouched. A spent, expired or exhausted one answers 410 token_spent, with the page saying what to do next.

The two tool catalogs

Every session is offered the same tools, and a caller’s role decides what a call answers rather than which tools appear: fourteen robot tools on both endpoints, sixty-three console_* tools at the central one only. Each tool dispatches onto the REST route the MCP page names beside it — the same function, so validation, refusals and audit are identical, never a second implementation. MCP lists the fourteen robot tools with their inputs, and the console families with their counts.

Realtime and bridge transports