Skip to main content

API

The Suite exposes route handlers under app/api/. They serve the interface and the vehicles, and are not a public product API.

The reference is generated, and it is live​

lib/swagger.ts builds an OpenAPI 3.0.3 document from the JSDoc annotations on the route handlers themselves. Two endpoints serve it:

  • GET /api/openapi — the document
  • GET /api-docs — a browsable reference

The reference is generated from route annotations, which must be maintained alongside implementation changes. Generation does not prove that annotations cover every route or describe every behavior correctly.

The HTTP route index is generated from all explicit handler exports, including routes without annotations. It distinguishes method inventory from schema coverage. The generator recognizes both @swagger and @openapi annotations.

Authentication​

SchemeUsed by
cookieAuththe browser, an HTTP-only encrypted sab_session cookie issued after the Suite OIDC login
machineAutha vehicle's onboard computer, with the identity it received when it enrolled
bearerAuthGCS clients such as Harlock and Arcadia, using a Suite OIDC access token on routes that accept it

Authorization is always enforced on the server. Some responses are redacted by role before they leave the Node service rather than hidden in the interface.

Signed storage grants and licence activation tokens are additional, separate credential types. GET/PUT /api/storage?token=… accept a short-lived grant bound to the bucket, path, and read/write operation; they do not accept an arbitrary file path as authorization. Never log or publish these grant URLs. Licence check/deactivate uses the device protocol described in Authentication and licensing.

Browser data/ server actions are not a public REST contract. They can have different allowed audiences from similarly named legacy HTTP routes: for example Client document upload uses the authorized server-action flow, while /api/documents/create is privileged. Implementations must enforce visibility and ownership in either path.

Families​

auth, account, users, customers and customer clients, contacts, drones, documents, flight-logs, drone-control, storage, settings, software, and gcs — licences, visible drones and gateway tokens, flight-log uploads, vehicle enrolment, network-control proofs, and update assets.

GCS clients discover permitted vehicles through GET /api/gcs/drones and request vehicle-scoped gateway credentials through GET /api/gcs/drones/{droneId}/gateway-token. These endpoints use OIDC bearer authentication and server-side visibility checks. They are distinct from the browser's cookie-authenticated drone routes and from the activation-token protocol used by licence checks; see Authentication and licensing.

Remote ground stations​

GET /api/gcs/drones/remote is the bearer-authenticated discovery endpoint for Harlock desktop's remote Connections tab. It returns the account's remoteControl flag and eligible drones with id, name, serialNumber, droneType, online, and onlineSince. online: null means presence could not be checked; it is distinct from a confirmed offline result. Vehicle type, company visibility, remote access, and gateway configuration determine the list.

An Administrator changes the account flag through same-origin cookie-authenticated POST /api/users/remote-control, with { "accountId": "…", "enabled": true } or false. The change is audited. Any role can receive the grant; it does not change that role or expand the fleet the account can see. Only gateway credentials issued to a ground-station application can add mavlink:write; the Suite browser never receives that permission. The existing role-based command:write permission for web flight actions is separate. See Allow or revoke remote control.

GET /api/gcs/network-control reports allowed and role for Harlock's Internet link panel. POST to the same route takes { "serial": "…" } and issues a short-lived signed proof plus expiresAt, only for an Administrator or Operator who can see that vehicle. This proof authorizes the Jetson's LTE-off operation; it is separate from the account's remote-control grant and from the Suite's per-drone remote-access switch. Harlock must obtain it while the Suite is reachable. A Client's remote-control grant does not confer permission to turn LTE off.

Configuration and supporting endpoints​

OperationCaller and behaviorFurther documentation
POST /api/users/temporary-passwordAdministrator cookie, same-origin JSON { "accountId": "…" }; returns the single-display temporary password and expiryUsers and access
POST /api/customers/clients/temporary-passwordAdministrator or Operator cookie, same-origin JSON { "customer_id": "…", "account_id": "…" }; only a Client associated with that customer can be resetClient password recovery
POST /api/users/remote-controlAdministrator cookie; audited per-account grant or revocationRemote ground stations
GET /api/gcs/drones/remote, GET/POST /api/gcs/network-controlGCS bearer; remote discovery and the separate network-control proofRemote ground stations
GET/POST /api/drones/{id}/jetson-enrolmentPrivileged user; GET reads state, POST prepares a single-use enrolment permit after provisioning the remote linkSetup and remote-link contract
GET/PATCH /api/drones/{id}/simPrivileged user; PATCH updates only allowed SIM fields; GET reports has_sim_password, never the stored passwordSIM configuration
GET/PUT /api/drones/{id}/ssh-accessAdministrator; reports or changes SSH publication; PUT uses { "enabled": true } or false and enforces Access/remote-access prerequisitesRemote SSH
GET/POST /api/drones/{id}/ssh-host-keysPrivileged registry access; public keys only; replacement requires the predecessor and a reasonHost-key registry
GET …/ssh-host-keys/known_hosts, GET …/verify?fingerprint=…, POST …/{keyId}/revokePrivileged registry access; read trust material, inspect a fingerprint, or withdraw a keyHost-key registry
/api/drones/{id}/playback/… and /hls/{cameraId}/…Authenticated, vehicle-scoped WHEP/HLS proxy; use resolved playback endpoints rather than constructing a gateway URLVideo
GET /api/healthPublic runtime health probe; not a vehicle, storage, or sign-in acceptance testDeployment
/api/oidc/*Provider protocol endpoints; authorize, token, UserInfo, keys, logout, native logout events, and restricted password replacement have different rulesOIDC provider

Browser mutations generally require same-origin requests and the expected content type. A cookie alone is not permission to change any drone. Feature-disabled responses, remote-access refusal, missing configuration, and a gateway outage are distinct; see Environment variables and The remote link.

Flight-log uploads​

The multipart flow under /api/gcs/flight-logs/uploads accepts enrolled-machine requests and the user/GCS authentication supported by the handlers. A machine's drone association comes from its enrolled identity, not an arbitrary payload id. Uploads cover ArduPilot DataFlash logs and Harlock session journals.

  1. POST /api/gcs/flight-logs/uploads with JSON kind, fileName, sizeBytes, and a 64-character hexadecimal sha256. User callers also supply droneId; an enrolled machine's drone comes from its verified identity. Optional time, duration, pilot, location, notes, and summary fields accompany the declaration.
  2. Read the returned id, status, duplicate, partBytes, partCount, and receivedParts. Parts are numbered from 1. The current part size is 8 MiB and maximum file size is 2 GiB; use the returned part sizing, including the shorter final part.
  3. PUT /api/gcs/flight-logs/uploads/{id}/parts/{part} with the exact raw part bytes and matching content length. Skip parts the server already received when resuming the same file.
  4. POST /api/gcs/flight-logs/uploads/{id}/complete. Treat it as delivered only after available; preserve the source until delivery is confirmed.

The ardupilot kind accepts .bin and .tlog; harlock_session accepts .jsonl. The same file identity for the same drone is deduplicated across callers. A repeated start for an already available file returns duplicate: true. Clients cannot upload flight logs. Browser uploads also require the Suite origin; machine and GCS callers use their respective signed or bearer authentication.

Missing parts, a wrong part size, expired/revoked identity, and a final size or digest mismatch must be handled as errors. Do not discard the onboard copy on a successful part response alone. The handler's JSON errors include an error code and message; keep credentials out of diagnostics.

Finalization reads the assembled object back from storage and checks both its size and its SHA-256 before marking it available; the declared digest alone is never trusted. A file whose stored content does not match answers 409 with digest_mismatch: the stored object is deleted, the log is left in error with both digests, and the next start for the same file begins the upload again. The check streams the object, so memory stays bounded; it adds one read of the file from storage to complete, which grows with the file (2 GiB at most). Jetson spool persistence and recovery are tracked in issue #75.