FrootAI.dev AgentSpace
On this page 7
Reference Worker + D1

HTTP API & platform contracts

Complete authenticated Worker endpoints, concurrency headers, normalized entity synchronization, execution Flight Recorder routes, and error envelopes.

Status: Available Architecture: Core System Read: 8 min Verified: 2026-11-16

Authentication and required headers

All /api/v1/* routes require an authenticated principal. In production (ENVIRONMENT=production), the Worker enforces AUTH_MODE=oidc and verifies JWT signatures against configured OIDC_ISSUER, OIDC_AUDIENCE, and JWKS keys. Local header authentication is rejected outside ENVIRONMENT=local.

Header Required on Contract behavior
Authorization: Bearer <jwt> All /api/v1/* requests Resolves immutable OIDC subject and enforces tenant RBAC (owner, admin, member, auditor).
Idempotency-Key All mutating requests (POST, PUT, DELETE) Stores canonical response keyed by tenant, route, key, and SHA-256 payload hash. Reusing a key with a different payload returns 409.
If-Match Versioned workspace updates Requires the last observed integer version. Stale versions fail with 409 version_conflict without writing audit entries.
x-request-id Returned on every response Correlates HTTP responses, structured Worker logs, audit records, and Flight Recorder spans.

Idempotency and optimistic concurrency

  • Every mutating call reserves an idempotency slot before mutating D1 state and replays the exact stored status and canonical JSON on safe retries.
  • JSON request payloads above 1.5 MB are rejected before parsing; outbound connector responses are capped at 256 KB.
  • Non-members probing a foreign :tenantId receive 404 not_found rather than 403 so tenant identifiers cannot be enumerated.
  • Audit records and execution lifecycle events are strictly append-only and cryptographically hash-chained.

Health, tenant, and workspace endpoints

Method Path Role Summary
GET /api/health/live Public Confirms Worker process liveness.
GET /api/health/ready Public Verifies D1 schema readiness, OIDC config, HTTPS origin allowlist, and Queue bindings.
GET /api/v1/tenants Authenticated Lists tenants where the caller holds an active membership.
POST /api/v1/tenants Authenticated Creates a tenant, owner membership, initial workspace snapshot, and genesis audit event.
GET /api/v1/tenants/:tenantId/workspace auditor+ Returns current workspace snapshot, version, and ETag.
PUT /api/v1/tenants/:tenantId/workspace member+ Updates workspace state when If-Match matches current version.
GET /api/v1/tenants/:tenantId/audit auditor+ Lists ordered, hash-chained tenant audit events.

Normalized entities and cursor delta feed

GET /api/v1/tenants/tnt_northstar/changes?after=42&limit=250 HTTP/1.1
Host: frootai.io
Authorization: Bearer <oidc-jwt>

Clients persist nextCursor locally and advance monotonically until hasMore is false. Current browser clients poll once per second while active.

Work executions, Flight Recorder, and replay

POST /api/v1/tenants/:tenantId/work/:workId/executions
GET  /api/v1/tenants/:tenantId/work/:workId/executions
GET  /api/v1/tenants/:tenantId/jobs/:jobId
GET  /api/v1/tenants/:tenantId/jobs/:jobId/events
POST /api/v1/tenants/:tenantId/jobs/:jobId/cancel
POST /api/v1/tenants/:tenantId/jobs/:jobId/replay

Admission commits the job and transactional outbox row in D1 before publishing to Cloudflare Queues, enforcing at most one active attempt per work item and tenant concurrency caps. See Execution Flight Recorder & replay for event phases and cancellation guarantees.

Extension and secret-reference transitions

GET  /api/v1/tenants/:tenantId/connectors
POST /api/v1/tenants/:tenantId/connectors
GET  /api/v1/tenants/:tenantId/extensions
POST /api/v1/tenants/:tenantId/extensions
POST /api/v1/tenants/:tenantId/extensions/:extensionId/transition
GET  /api/v1/tenants/:tenantId/secret-references
POST /api/v1/tenants/:tenantId/secret-references
POST /api/v1/tenants/:tenantId/secret-references/:secretReferenceId/transition

Secret-reference routes accept only binding aliases, provider types, and non-secret metadata. Any payload containing raw secret keys or token strings is rejected at schema validation.

Canonical error envelope and status codes

{
  "error": {
    "code": "version_conflict",
    "message": "Workspace version does not match If-Match header.",
    "traceId": "req_01jcv92k8m"
  }
}
Status Error code When returned & client action
400 validation_error / missing_idempotency_key Malformed schema or missing required headers. Fix request contract before retrying.
401 unauthenticated Missing, expired, or invalid OIDC bearer token. Refresh authentication.
403 insufficient_role Caller is a tenant member without required role (for example, auditor attempting a write).
404 not_found Resource does not exist or caller is outside the tenant boundary.
409 version_conflict / idempotency_conflict / work_execution_active Reload latest state or use a fresh idempotency key for a distinct mutation.
429 tenant_execution_capacity_exceeded Tenant has reached its concurrent active execution limit (default 4). Wait for active runs to finish.
Verified against repository suites
tests/backend/api.test.tstests/backend/repository.test.tstests/backend/platform.test.tstests/backend/jobs.test.ts
Markdown specification

HTTP API & platform contracts