Skip to main content
The Fleet access policy governs these endpoints on tuturuuu.com. Responses use Cache-Control: private, no-store. Use getFleetAccess, getFleetDigest, publishFleetDigest, listFleetIntents, submitFleetIntent, createFleetLinkCode and confirmFleetLink from @tuturuuu/internal-api/fleet for TypeScript callers. The package also exports the response schemas; validate responses before use.

Read access

GET /api/v1/fleet/access accepts a signed-in Tuturuuu session or an app access session with the platform or mastermind audience and internal-app:session scope. The server uses the verified user ID and looks up the grant and stop state on every request. An unsigned request receives 401. A signed-in account without live access receives:
A live grant returns enabled: true, its tier, project keys and capabilities. While Fleet is stopped, the endpoint returns stopped: true and disables access for every tier.

Read the digest

GET /api/v1/fleet/digest uses the same sessions and requires live status.read access. The response contains sections and totals. Each section is the latest visible snapshot for a project in the grant. It carries the publisher timestamp generatedAt, the server timestamp receivedAt, and stale, which becomes true one hour after receipt. Totals count visible sections as projects, and their lanes overall and by state. An authorized reader with no visible snapshots receives empty sections and zero totals. A disabled or stopped reader, or a grant without status.read, receives 403.

Publish a project snapshot

PUT /api/v1/fleet/digest accepts one project snapshot and returns 204. The digest publisher uses a dedicated Authorization: Bearer <token> credential over HTTPS. Provision the token as the prefix ttr_fleet_digest_ followed by 32 cryptographically random bytes encoded as unpadded base64url. Store the full token in the publisher’s secret store. Set FLEET_DIGEST_PUBLISHER_TOKEN_SHA256 on Web to the lowercase hex SHA-256 of the full token. Remove the configured hash to disable publishing or replace it with a new hash to rotate the credential. A missing or invalid publisher credential is denied. A Fleet stop also denies publishing. The route rejects unknown fields at every level and caps the body at 128 KiB. Only the database owner can provision approved display values in private.fleet_digest_display_values. Approvals are specific to a project and field. Approve only text safe for the project’s Fleet readers. A removed approval hides any affected snapshot while one of its display values lacks approval. Retrying the same snapshot preserves its original receipt time. A snapshot older than the stored snapshot, or different content at the same timestamp, receives 409. Invalid documents, unapproved labels, and unknown projects receive 400. Excess body bytes receive 413. Unavailable storage or invalid publisher configuration returns 503.

Submit and read intents

POST /api/v1/fleet/intents accepts a signed-in Tuturuuu web session cookie, a Supabase session bearer, a Mastermind access session with internal-app:session, or a desk request with signed event evidence. The mobile app sends its Supabase access token as Authorization: Bearer. That token is not an app-coordination token. The platform audience stays read-only, including a signed CLI session. Send Content-Type: application/json with { kind, payload, quote? }. Bodies are limited to 4 KiB. Each payload includes a projectKey. Targeted requests also include a catalog targetKey, with the same syntax as a project key. Catalog operators store target aliases under the corresponding group in private.fleet_projects.target_mapping, mapping each alias to a lowercase UUID. Each alias must uniquely identify one target within its group across the entire catalog. The server binds the resolved ID, parameters, kind and owning project version to the action hash. A project mismatch, missing target or ambiguous alias is denied. The release intent kinds file requests for approval. Desk requests never approve themselves. A desk-filed low- or medium-risk request waits for approval even when the requester holds approve.low. Desk-filed comment and status_question intents need no approval and still execute. Desk operations resolve a live grant row, so the Owner needs a non-Owner grant to use them. The optional quote is capped at 1,000 characters and required for comments. The server scrubs recognizable sensitive values and stores the result separately as display text. Keep credentials and private data out of submitted quotes. A successful response is 201 {"id":"<intent UUID>"}. Refused desk evidence returns 401. Denied requests return 403, event replays and stale mappings return 409, and exhausted quotas return 429. Invalid JSON or unknown fields return 400. GET /api/v1/fleet/intents accepts the same human sessions as the access endpoint. It returns the caller’s own receipts for currently authorized projects, newest first, with id, kind, state and createdAt. The intents array contains up to 50 entries. Pass nextBefore as ?before=<intent UUID> for the next page when present. Disabled or stopped access returns 403. POST /api/v1/fleet/identity/link-codes and POST /api/v1/fleet/identity/confirm accept the same signed-in sessions as POST /api/v1/fleet/intents: a web session cookie, a Supabase session bearer, or a Mastermind access session with internal-app:session. They refuse the platform audience. Desk event evidence is not a session on these two routes.
  1. A signed-in user with live Fleet access sends {} to POST /api/v1/fleet/identity/link-codes. The 201 response contains code and expiresIn: 600. Issuing a new code invalidates the account’s current code or pending link.
  2. The user sends the code in an approved one-to-one conversation. The desk sends { code } to POST /api/v1/fleet/identity/verify with signed event evidence. It shows the returned linkId and confirmationCode to the sender in the same conversation.
  3. The same signed-in user sends { linkId, confirmationCode, preview: true } to POST /api/v1/fleet/identity/confirm within the original ten-minute window to read the pending channel and the desk owner’s accountLabel with linked: false. Sending { linkId, confirmationCode } to the same route confirms the link and returns the channel and label with linked: true. Neither response exposes provider sender or conversation identifiers. A sender can link to one user per provider account. Desk events resolve to that user only in the linked conversation and while their grant is live.

Desk and ingress credentials

Set FLEET_DESKS on Web to a JSON object keyed by desk ID. Each entry contains tokenSha256 (lowercase hex SHA-256 of the full bearer), ingressPublicKey (an Ed25519 public key in PEM format), and credentialVersion (a positive 32-bit integer). Desk IDs contain 1–40 lowercase letters, digits or hyphens. The bearer format is ttr_fleet_desk_<desk-id>.<32 random bytes in unpadded base64url>. Store the private signing key only at ingress and the bearer only with its desk. FLEET_DESKS holds key material only and admits nothing by itself. A configuration that still names a channel, account or accountLabel fails validation, and every desk request then returns 401. Trusted ingress validates the provider event, its original freshness, account, sender and approved private conversation before constructing the request body. It repeats the freshness check on provider redelivery and declines to sign expired events. Send the UTF-8 JSON claims as unpadded base64url in X-Fleet-Event. Sign the ASCII string fleet-event-v2.<encoded claims> with Ed25519 and send the unpadded base64url signature in X-Fleet-Event-Signature. The v1 claims and signature domain are retired. The v2 claims are:
  • version of 2, channel (whatsapp, zalo, or discord), account, sender, conversation, and conversationType of private_1_to_1.
  • deskId, credentialVersion, and ownerGeneration. Use the decimal string returned by the Owner operation for ownerGeneration.
  • The provider’s eventId, the allowed operation (identity.verify, intent.submit, or digest.read), and inputSha256 (lowercase hex SHA-256 of the exact HTTP JSON body bytes).
  • issuedAt, Unix time in milliseconds. Evidence permits up to 30 seconds of future clock skew and expires after five minutes.
Admission requires an active, unquiesced database row for the channel and provider account. Inside the action transaction, the API matches the bearer desk ID, the verifying key’s desk ID and credential version, and the signed desk ID, credential version and generation to that row. A missing or mismatched row, quiesced owner or retired proof returns 401, leaves the event unconsumed and appends an audit event without an actor. The API consumes the event ID once per channel and provider account across all three operations and across desk rotations and cutovers. Replay fingerprints are retained for 90 days from consumption. Preserve FLEET_IDENTITY_HMAC_KEY across cutovers. It is 32 random bytes in lowercase hex stored only on Web. Changing it requires retirement and re-linking of existing sender and conversation identities.

Register, rotate and cut over a desk

Change the desk owner only from a trusted database-owner session carrying the configured Owner’s verified request identity and live explicit root manage_mastermind permission. No API role can execute these functions or read the owner tables. Each function takes the channel and provider account first, returns the account, desk ID, credential version, owner generation (a decimal string) and quiesce state, and appends an audit event. A stale expected generation fails with 55000, and an invalid transition with 22023. Each generation advances by exactly one, and the database rejects direct writes that skip, repeat or rename an owner row. Owner rows and the credential history cannot be deleted. A desk ID and credential version pair is admitted at most once across all accounts, so a retired credential never becomes valid again, even when its desk later serves another account. Each credential version maps to one FLEET_DESKS entry. A rollback assigns a new version. It may reuse the previous desk’s key only while that key is still held and unexpired; otherwise provision a fresh bearer and key. Quiesce before rotating when Web replicas receive verifier configuration at different times. After the verifier configuration and the database readback agree, resume and issue proofs with the returned generation. For a runtime cutover, quiesce both admission and the provider send fence, reconcile in-flight sends and verify the desk and send owners before resuming. Use the same sequence for rollback. If a cutover is aborted, resume the quiesced current owner at a fresh generation. See the Mira cutover procedure.

Cut over from v1 evidence

  1. Apply the desk-owner migrations. Every desk request returns 401 until the remaining steps finish.
  2. Register the owner row, which starts quiesced.
  3. Install the matching v2 FLEET_DESKS entry for that desk ID and credential version on every Web replica.
  4. Resume the owner after the configuration and the database readback agree.
  5. Sign only v2 proofs carrying the generation that resume returned.
Keep FLEET_IDENTITY_HMAC_KEY unchanged so linked identities still resolve. Retire the v1 signers once v2 proofs are admitted. Known gap: FLEET_DESKS holds one key per desk ID, so Web cannot verify an old and a new credential side by side during rotation. Quiesce before rotating when replicas receive configuration at different times. A rollback always mints a higher credential version.

Read a digest from a desk

Send POST /api/v1/fleet/desk/digest with Content-Type: application/json, body {} and v2 proof for digest.read. A successful response has the same sections and totals as the session digest. The transaction consumes the event, resolves the actor from the linked private conversation, and requires a live status.read grant. It returns only projects in that grant. An unlinked conversation, inactive grant, missing capability or Fleet stop returns 403. A replay returns 409. Every successful read uses one slot from the actor’s rolling questions_per_hour quota, shared with status-question intents. Quota exhaustion returns 429. The endpoint returns digest data only. Generated answers additionally require ask and a model budget reservation. Desk credentials confer no approval authority.

Dry-run consumer

Cron Control calls these routes with its dedicated Authorization: Bearer <token> over HTTPS. The token is ttr_fleet_consumer_ followed by 32 random bytes encoded as unpadded base64url. Keep the token in the Worker secret FLEET_CONSUMER_TOKEN. Configure its lowercase hex SHA-256 on Web as FLEET_CONSUMER_TOKEN_SHA256. This principal has no submit, approval, grant, or dispatch authority. Send JSON bodies with Content-Type: application/json. Bodies are capped at 4 KiB and unknown fields are rejected. slot is the UTC start of the current 15-minute window in ISO 8601 format with milliseconds. generation is the decimal string returned by status. Use the same generation for the whole run. A stop or generation change returns {state:"stopped"}; an out-of-window request returns {state:"slot_closed"}. A missing or mismatched current lease returns {state:"lease_conflict"}. These protocol states use HTTP 200. Invalid credentials return 401, invalid input returns 400, oversized bodies return 413, and unavailable storage or verifier configuration returns 503. A repeated claim in the same slot returns only the batch’s remaining live leases. A new slot reconciles existing leases before admitting fresh work. A repeated successful receipt or purge in the same slot yields the recorded result. Claims contain opaque IDs only. A dry-run receipt closes the intent with state done and the database records dry_run.