---

title: XRPC HTTP Surface updated: 2026-06-03 #

XRPC is the public HTTP RPC layer used by AT Protocol clients and services. Tempest exposes XRPC methods under /xrpc/<method-nsid>.

Concepts #

A Lexicon method has an NSID such as com.atproto.repo.createRecord. Methods are queries, procedures, or subscriptions:

• queries usually use GET and URL query parameters
• procedures use POST and a JSON or byte body
• subscriptions upgrade to a streaming protocol such as WebSocket

Errors are protocol-shaped JSON with an error string and optional message.

Implementation #

TempestWeb.Router sends protocol methods through the XRPC pipeline. Tempest.Xrpc.Registry is the method table. _health is public, and _admin/status is protected by admin-token auth outside normal account bearer credentials. Each registry entry declares:

• NSID
• kind (query, procedure, subscription)
• auth requirement
• input/output content type
• handler module/function
• known errors

TempestWeb.XrpcController performs registry lookup, method checks, content handling, auth assignment, and error rendering before calling the handler.

Handlers live under Tempest.Xrpc.* and should remain thin. Long-running or stateful work belongs in contexts such as Tempest.Accounts, Tempest.Records, Tempest.Sync, or Tempest.Blobs.

Error behavior #

Unknown methods return JSON, not Phoenix HTML errors. Verb mismatches and content mismatches fail before handler execution.

Common status mappings:

• 400: invalid params/body
• 401: missing or invalid auth
• 403: authenticated but forbidden
• 404: unknown method or missing resource
• 409: compare-and-swap conflict
• 500: unexpected internal error
• 502: upstream failure

Verification #

hurl --test --variable base_url=http://localhost:4000 test/smoke/xrpc.hurl

The smoke test covers health, method dispatch, unknown methods, and verb/error shape behavior.