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 with device keys (created per agent, apk_* prefix) or scoped API keys (apk_sc_* for multi-tenant Pods). Humans authenticate with Firebase Auth ID tokens (Google or Email).

Header	Carries	Used by
x-ujex-key	Project bridge key	MTA, operators, internal services
x-ujex-device-key	Per-agent device key (apk_...)	Agents
x-ujex-delegation	Delegation token	Cross-agent calls
Authorization: Bearer <firebase-id-token>	Human user	Dashboard owner actions

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 Postbox 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