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:
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.
Link a private desk conversation
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.
- A signed-in user with live Fleet access sends
{}toPOST /api/v1/fleet/identity/link-codes. The201response containscodeandexpiresIn: 600. Issuing a new code invalidates the account’s current code or pending link. - The user sends the code in an approved one-to-one conversation. The desk
sends
{ code }toPOST /api/v1/fleet/identity/verifywith signed event evidence. It shows the returnedlinkIdandconfirmationCodeto the sender in the same conversation. - The same signed-in user sends
{ linkId, confirmationCode, preview: true }toPOST /api/v1/fleet/identity/confirmwithin the original ten-minute window to read the pendingchanneland the desk owner’saccountLabelwithlinked: false. Sending{ linkId, confirmationCode }to the same route confirms the link and returns the channel and label withlinked: 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
SetFLEET_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:
versionof2,channel(whatsapp,zalo, ordiscord),account,sender,conversation, andconversationTypeofprivate_1_to_1.deskId,credentialVersion, andownerGeneration. Use the decimal string returned by the Owner operation forownerGeneration.- The provider’s
eventId, the allowedoperation(identity.verify,intent.submit, ordigest.read), andinputSha256(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.
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 rootmanage_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
- Apply the desk-owner migrations. Every desk request returns
401until the remaining steps finish. - Register the owner row, which starts quiesced.
- Install the matching v2
FLEET_DESKSentry for that desk ID and credential version on every Web replica. - Resume the owner after the configuration and the database readback agree.
- Sign only v2 proofs carrying the generation that resume returned.
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
SendPOST /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 dedicatedAuthorization: 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.