Authentication

The Rover Nexus REST API is authenticated with API keys and served over HTTPS. Every request carries a key as a bearer token; requests without a valid, unexpired, unrevoked key are rejected.

API keys let external tools, scripts, LLM agents, and integrations call the API without a browser sign-in. A key can both read fleet state and act on it (create and control work), bounded by its permissions. A key is scoped to one organization, optionally to a single fleet, and to a set of permissions that decide which endpoints it can call.

Base URL

All endpoints live under the /v1 path of your Rover Nexus API host:

https://<your-nexus-host>/v1

Your API host is provided during onboarding. Everything in this reference is relative to that base.

Endpoint paths

Most endpoints are nested under an organization and a fleet:

/v1/orgs/{org_id}/fleets/{fleet_id}/...

A few resource-management endpoints are top-level and take the fleet as a query or body parameter instead, for example GET /v1/robots?fleet_id=… and PATCH /v1/robots/{robot_id}. Both families authenticate with API keys the same way; each endpoint in this reference shows its full path.

What an API key is

An API key:

belongs to exactly one organization,
is optionally restricted to a single fleet (an org-scoped key can reach any fleet in the org that its permissions allow; a fleet-scoped key can reach only that one fleet),
carries a list of permission strings that gate which endpoints it can call,
is shown once at creation and stored only as a hash, so it can never be retrieved again,
can optionally expire, and can be revoked at any time.

A key authenticates a request only while it is neither revoked nor expired. A revoked or expired key stops working immediately.

Creating a key

Create and manage keys from the Fleet Manager web app:

Sign in and open Account, then Organizations.
Expand the organization you want the key to belong to and open its API Keys panel.
Click Create API Key and fill in:
- Name: a human label, for example CI deploy bot or Planning assistant.
- Permissions: select the permissions the key should carry (see Scopes and permissions). A key with no permissions cannot call any endpoint.
- Expiration (optional): a date after which the key stops working. Leave blank for a key that never expires.
Submit. The raw key is displayed once. Copy it immediately and store it somewhere safe (a secret manager). It will not be shown again.

Managing keys requires an organization owner, organization admin, or a fleet manager within the organization. Keys can also be created through the REST management endpoints documented in Organizations, which the web app calls on your behalf.

Lost a key? There is no way to recover it. Create a new key and revoke the old one.

Key format

A raw key looks like this:

rn_live_<64 hexadecimal characters>

The rn_live_ prefix identifies the value as an API key.

Using a key

Send the key as a bearer token on every request, over HTTPS:

Authorization: Bearer rn_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Example:

curl https://<your-nexus-host>/v1/orgs/<org_id>/fleets/<fleet_id>/robots \
  -H "Authorization: Bearer rn_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Never embed a key in client-side code, a public repository, or a URL. Treat it like a password.

Scopes and permissions

A key may only call endpoints covered by its permissions. Each permission is a simple string; assign only what a key needs.

Permission	Grants
`fleet:read`	Read fleet-level information (alerts, audit log, mission runs, utilization).
`fleet:write`	Acknowledge fleet alerts.
`robots:read`	List and read robots, their position, current mission, and capabilities.
`robots:write`	Edit or transfer a robot, push settings, cancel a mission, and send live commands (go to, stop, resume, set mode, invoke a service).
`features:read`	List and read features (map shapes and routes).
`features:write`	Create, edit, and delete features; reset a feature's decomposer; lock or unlock a feature; configure how a feature is divided.
`operations:read`	Read plans, operation feedback, and operation progress.
`operations:draft`	Create reviewable plans (does not deploy).
`operations:validate`	Validate a plan's deployability.
`operations:deploy`	Deploy a validated plan into a running operation (human approval still required).
`operations:deploy_without_human_approval`	Deploy without the human-approval step. Grant only to trusted automation.
`operations:control`	Stop, resume, delete, or stop-and-reset an operation; abort its missions; reset a step; add or remove robots; assign a spot; set operation priorities; release or force-reset a robot; create and delete scheduled commands.
`missions:read`	Read mission run history, scheduled missions, and mission templates.
`missions:write`	Create, update, and delete mission templates; schedule missions; set a mission run's status.
`history:read`	Read operation and mission history.
`audit:read`	Read the activity log of plan and operation events.
`exports:create` / `exports:read`	Reserved for the data export API (not yet available).

These permission strings are specific to API keys. They are independent of the roles assigned to people in the web app.

Organization-scoped and fleet-scoped keys

An organization-scoped key (no fleet set) can act on any fleet in its organization, as long as its permissions allow the action. Each request still names the fleet, and the server verifies that fleet belongs to the key's organization.
A fleet-scoped key can act only on the single fleet it is bound to. Requests targeting any other fleet are rejected.

In both cases a key can never act outside its own organization.

Discovery

Two endpoints let a key find out what it is and what it can reach, so an integration does not need ids configured out of band. Neither is rate limited.

Inspect the current credential

GET /v1/me

Returns the identity and permissions of the key (or user) making the request. For an API key:

{
  "actorType": "api_key",
  "apiKeyId": "key-uuid",
  "orgId": "org-uuid",
  "fleetId": null,
  "permissions": ["robots:read", "operations:control"]
}

fleetId is null for an organization-scoped key, or the bound fleet for a fleet-scoped key. Use this to confirm why a request might be forbidden without trial and error.

List reachable fleets

GET /v1/orgs/{org_id}/fleets

Returns the fleets the key can reach in the organization, as { "items": [{ "fleetId", "name" }] }. A fleet-scoped key sees only its one fleet. See Fleets.

Idempotency

Endpoints that create or change state require an Idempotency-Key header so a retried request is not applied twice:

Idempotency-Key: <your-unique-string>

Choose a unique value per logical operation (for example a UUID). Retrying a request with the same key and the same body returns the original result instead of acting again, so a network retry never creates a duplicate. Reusing a key with a different body is rejected with 409. The endpoint reference notes where this header is required.

For plan creation, this protection is durable. For the mission, scheduled command, and mission-template create endpoints it is best-effort over a 24-hour window, so do not rely on it beyond a day.

Rate limits

The API is rate limited per organization, and additionally per API key. Default budgets:

Subject	Per minute	Per day
Per organization	600	20,000
Per API key	120	5,000

A request that exceeds any window returns 429 Too Many Requests with a Retry-After header giving the number of seconds until that window resets. Rate limits are applied only after a request authenticates and authorizes, so a rejected request does not consume your budget.

The discovery endpoints (GET /v1/me, GET /v1/orgs/{org_id}/fleets) and the API-key management endpoints are not rate limited.

Errors

Every error response is JSON carrying a human-readable error message and a stable, machine-readable code:

{ "error": "<human-readable message>", "code": "<machine_code>" }

Branch on code rather than on the message text. The code values, with their status:

Status	`code`	Meaning
`400 Bad Request`	`bad_request`	A malformed request: bad identifier, invalid JSON body, or a missing required header.
`401 Unauthorized`	`unauthorized`	Missing, invalid, expired, or revoked key.
`403 Forbidden`	`forbidden`	A valid key without the required permission, or one targeting an organization or fleet it cannot access.
`404 Not Found`	`not_found`	The requested resource does not exist (or is not visible to this key).
`409 Conflict`	`conflict`	An `Idempotency-Key` was reused with a different body, or a plan is in a state that does not allow the requested action.
`429 Too Many Requests`	`rate_limited`	A rate-limit window was exceeded. See Rate limits.
`500 Internal Server Error`	`internal`	An unexpected server error.
`503 Service Unavailable`	`unavailable`	Live operation feedback was temporarily unavailable. Retry shortly.

Endpoints that are not yet implemented (the data export API) instead return 501 with { "status": "not_implemented" } and no code.