Connect a Cloudflare account. Mints the installation and its key.

post/v1/installations

Request

  • The document declares no server URL.
  • Auth: one of:
    • HTTP bearer
    • API key in cookie __Secure-better-auth.session_token

Request body

namestring required

What the founder calls this Cloudflare account. Display only.

Response

The request has succeeded and a new resource has been created as a result.

idstring required
namestring required
proxyBaseUrlstring uri nullable required

Where central posts relayed sends. Absent until the proxy is deployed and the installation settles active.

contractVersionstring required

The transport-contract version this installation's proxy was built against.

The proxy runs in the customer's own account and cannot be updated by us, so central serves every version it has ever issued.

⛔ It is NOT how a dashboard shows which installations are behind, though this said so. Every relay ever shipped answers v1 and a breaking change would mint v2 rather than move anybody, so a screen built on it reports the whole fleet current for ever. That belief is why two production relays ran three-week-old bytes unnoticed while outbound attachments corrupted. relayStatus is the field that answers it.

relayBuildstring nullable required

What this installation's relay ANSWERED when the estate last asked it, or null if it never has.

A hash of the relay's source. Compared against the build central currently ships to decide relayStatus — what the relay says it is, never what we believe we uploaded.

relayStatus'current' | 'behind' | 'unreachable' | 'unknown' required

Whether this relay is running what central ships.

current: it answered with the build we ship. behind: it answered with an older one, and needs a founder to authorise an update — central holds no standing credential for their Cloudflare account. unreachable: it did not answer the last sweep, which is a different problem needing a different fix. unknown: it has never been probed.

⚠️ behind is not cosmetic. A relay can be behind in ways that change what may be sent to it at all — the engine refuses payloads a given build would mishandle — so this is the difference between a founder's attachments working and failing.

relayProbedAtstring date-time nullable required

When the relay last answered, ISO-8601, or null if it never has.

relayAutoUpdateboolean required

Whether this account asked FounderMail to keep its relay updated without a consent hop.

⛔ Never the token itself, only whether one is held. A credential a customer entrusted to us has no business on a read surface every screen calls.

relayAutoUpdateBystring nullable required

Who turned it on, and when. Null when nobody has — the default.

relayAutoUpdateAtstring date-time nullable required
status'connecting' | 'active' | 'failed' required

connecting: the engine tenant is minted, but the proxy's URL has not been reported yet, so relayed sends have nowhere real to go — see reportProxyUrl, the act that settles active. failed: the connect never completed.

cloudflareAccountIdstring nullable required

The Cloudflare account this installation IS, once a founder has authorised one. Null before that, and never changed after: an account holds exactly one relay, and the id is globally unique across every organisation — two orgs connecting the same account would both deploy into it, and the second would overwrite the first's vars and signing key.

cloudflareAccountNamestring nullable required

What Cloudflare calls that account, so the console can show WHICH one was authorised.

createdAtstring date-time required

⛔ The install's progress is NOT here — it is installStatus, and deliberately so.

It was on this model briefly. Two things were wrong with that: every row in a LIST would have to read a Durable Object to fill it in, and the field would otherwise be null in every response that is not about one specific install — a shape that lies by omission. A console polling an install already knows which one it is polling.

keyIdstring required

RFC 7638 thumbprint of the public half — FOUNDERMAIL_KEY_ID, and the keyid this installation's signatures carry. Public and derived, so it is safe to return and useful for matching an installation to the signatures it produces.

Changes

No recorded changes to this operation across all 1 revision of this API.