Fleet API and operations

Authentication and reads

APIs use the existing authenticated Struct browser session. Members may read; only organization owners/admins may mutate or disclose provisioning material. No unauthenticated fleet enrollment endpoint is introduced. Responses use private, no-store caching.

GET /api/fleet?orgId=UUID&page=0&filter=JSON returns at most 50 devices plus group/tag counts and the 20 most recent jobs. Supported filter keys: search, status, group, labels, sort, schemaDevice, schemaSlot, createdAfter, createdBefore, seenAfter and seenBefore (ISO timestamps). GET /api/fleet/job?orgId=UUID&id=JOB_UUID&page=0 returns 100 items plus aggregate result counts.

Preview and confirm

POST /api/fleet/preview accepts same-site JSON, orgId, requestId (UUID), operation and options. For create, supply quantity/prefix/start/digits, rows, or csv/mapping; use duplicates reject/skip/metadata. For existing-device actions, supply rows [{id,version}] or a server-side filter.

POST /api/fleet/action accepts orgId, jobId and action confirm/cancel. retry_preview also requires a new requestId and returns a new preview jobId. Review it before confirmation. POST /api/fleet/groups accepts orgId, name, optional id/version and delete:true for confirmed deletion.

POST /api/fleet/export accepts orgId and jobId, ids or filter, returning metadata CSV. POST /api/fleet/manifest accepts orgId, jobId, deviceIds (1–100) and confirm:true, returning a private credential JSON download. Do not call it as a routine inventory export.

// Same-origin authenticated browser request; no API secrets in URL.
const preview = await fetch("/api/fleet/preview", {
  method: "POST", headers: {"Content-Type":"application/json"},
  body: JSON.stringify({orgId, requestId: crypto.randomUUID(),
    operation:"create", prefix:"sensor-", quantity:10,
    options:{labels:["testing"]}, duplicates:"skip"})
}).then(r => r.json());
// Review GET /api/fleet/job before explicitly confirming preview.jobId.

Limits and errors

Safety limits: 10,000 items/job, two pending/running jobs/workspace, four active previews/jobs, 20 previews/hour, five metadata exports/minute/workspace, 200 groups, 20 group assignments per request, 20 tags/device, 8 MiB JSON request. Existing subscription allowances still apply. Export is bounded to 10,000 rows; narrow filters for larger fleets.

401 requires login; 403 indicates tenant/role denial; 402 indicates capacity/billing prerequisites; 409 indicates an administrative version conflict. Job items expose safe error codes, never database statements or credentials. No request ID should be reused for a different intended operation.

Workers run outside the browser. Administrators must install migration 037 after 035/036, explicitly activate fleet_settings, set server/public feature flags and start tcp-server/fleet-worker.js with the existing private credential key. See repository docs/phase-6/DEPLOYMENT.md; no deployment happens automatically.