API overview

:::warning Reference in transition The per-page API reference in this folder (agent-identity, agent-postbox, agent-memory, etc.) was written for a pre-SDK REST model that no longer matches the current codebase. The authoritative surface is:

• OpenAPI 3.1 spec at https://ujex.dev/openapi.json — machine-readable, autogenerated from the deployed Cloud Functions.
• SDK reference on the SDK quickstart page — Python, Go, TypeScript, CLI, and MCP server. Each wraps the HTTP layer; don't call functions directly unless you need to.
• Deployed function list — gcloud functions list --project=axy-ujex for the live inventory.

The per-subsystem pages in this folder will be regenerated from OpenAPI in a subsequent pass. :::

Endpoint shape (current)

Every Cloud Function is exposed at:

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

For us-central1 (regions can vary if you self-host). Cloud Functions Gen 2 so each endpoint is backed by a Cloud Run service.

Authentication

Agents authenticate by exchanging a device key (ap_live_*) or scoped API key (apk_sc_*) through the session callable. That returns a Firebase custom token; the SDK exchanges it for a Firebase ID token and sends Authorization: Bearer <firebase-id-token> to agent callables. Humans also use Firebase Auth ID tokens (Google or Email).

Header	Carries	Used by
x-ujex-key	Project bridge key	MTA, operators, internal services
Authorization: Bearer <firebase-id-token>	Agent or human Firebase ID token	Agent and dashboard callables
x-ujex-delegation	Delegation token	Cross-agent calls

Error format

RFC 7807 problem+json on all failures:

{
  "type": "https://ujex.dev/errors/scope_mismatch",
  "title": "scope mismatch",
  "status": 403,
  "detail": "device key bound to 'agent-hello' cannot act for 'agent-triage'"
}

See reference/error-codes for the full error catalog.

Idempotency

Writes use Firestore transactions with existence checks, so retrying a 5xx is safe. The Inbox send / draft operations accept an optional idempotency_key in the body and dedupe server-side via a 24h TTL store — useful for exactly-once outbound from crash-prone workers.

Versioning

Ujex is pre-1.0. Breaking changes can land with 30 days notice via the changelog and the in-product banner.

See also

• Quickstart — 5-minute walkthrough with the CLI
• SDKs — installation + language-specific recipes
• OpenAPI 3.1 spec — authoritative machine-readable reference