Skip to main content

API overview

Use an official SDK where possible. It handles the Firebase callable envelope, session exchange, token refresh, and normalized errors.

Base region:

https://us-central1-axy-ujex.cloudfunctions.net/<functionName>

Caller types​

CallerCredentialTypical surfaces
Human owner/team memberFirebase Auth ID tokenAgent creation, mandates, approvals, exports, settings.
AgentDevice/scoped key exchanged by session, then Firebase ID tokenPostbox, memory, tools, secrets, budgets, scheduler, artifacts.
Admin operatorVerified, allowlisted Firebase account on the admin originCross-tenant diagnostics, policies, KMS/mail health, admin audit.
Mail/internal serviceEndpoint-specific HMAC or configured secretMail ingest/bounce and operational webhooks.
Anonymous verifierNo credential, read-only HTTPPublic keys, anchor feed, local pack verification assets.

Human and agent tokens are not interchangeable. A callable may require a specific owner/team permission even after human authentication, or a named agent scope and active mandate after agent authentication. Each subsystem page states its caller.

Callable protocol​

Firebase callable functions use a POST JSON envelope and return {data: ...}. Direct callers must follow the Firebase callable protocol; do not treat a callable URL as an ordinary REST endpoint.

Errors and recovery​

Callable failures use Firebase HttpsError codes. Client SDKs expose codes such as functions/permission-denied; raw callable responses use Google RPC status names. See Error codes.

Recovery rule:

  • Fix input/auth for invalid-argument, unauthenticated, and permission-denied.
  • Reload current state for aborted version conflicts.
  • Retry unavailable and resource-exhausted with bounded jitter and the same idempotency key.
  • Treat a missing/failed authorization or risk decision as deny. Never continue optimistically.

Idempotency​

Idempotency is operation-specific. Agent creation, Pod create/invite, and selected write/dispatch paths accept or derive stable idempotency keys. Transactions protect decisions and chain appends, but that does not make every callable safe to repeat. Check the endpoint documentation before retrying a mutation.

Versioning and source of truth​

The deployed function inventory and repository exports are authoritative. The public openapi.json covers the documented HTTP/session subset; it is not a promise that all Firebase callables are conventional REST operations.

See also​