API Reference

The bearer token is a Supabase access token. Send it in the Authorization header. Tokens expire — refresh them through the Rush app or let rush http handle it for you.

# Authorization header (required for authenticated routes)
Authorization: Bearer <supabase-access-token>

# Same call via rush http (token auto-injected from ~/.rush/user.yaml)
rush http GET /api/v1/auth/me

On the server, the token is validated in getAuthenticatedUser():

// prix/api/src/auth.ts:80
if (authHeader?.startsWith("Bearer ")) {
  token = authHeader.slice(7);
}
// ...
if (!token) {
  throw new AppError("AUTH_FAILED", "Missing authorization - use Authorization header");
}

OAuth-proxy endpoints accept a per-provider header alongside the bearer. The header carries the access token the API uses to call Google, Twitter, etc.

# Gmail call via rush http (injects both headers)
rush http GET /api/v1/gmail/messages --oauth google

# Tweet via rush http
rush http POST /api/v1/twitter/tweets --oauth twitter -d '{"text":"Hello"}'

Returns a JSON object with a single url field — a short-lived presigned URL for catalog.json on R2. Fetch that URL with plain curl (no auth) to get the full catalog body.

# Step 1: get the presigned URL
rush http GET /api/v1/catalog
# => { "url": "https://halo-registry...r2.cloudflarestorage.com/catalog.json?X-Amz-..." }

# Step 2: fetch the actual catalog
curl -s "<presigned-url-from-step-1>"

Route definition: prix/api/src/index.ts:1105 — if (path === "/api/v1/catalog" && req.method === "GET"). Concrete shape of the response body lives in prix/api/docs/fetching-the-catalog.md.

The CLI uses these directly during rush install. They're also part of the public registry surface.

Defined in prix/api/src/index.ts:1132–1186 (manifest, latest, keys, version, download, publish).

Returns the list of LLM models the proxy will accept. No auth — the list is public so agent developers can pick models without signing in.

curl -s https://api.prix.dev/api/v1/models

Defined in prix/api/src/index.ts:1090.

Returns the user behind the bearer token. Useful for rush whoami-style probes and for validating that a session is still live.

rush http GET /api/v1/auth/me
# 200
# {
#   "userId": "...",
#   "email": "[email protected]",
#   "valid": true
# }
# 401
# { "valid": false, "error": "Invalid or expired token" }

Defined in prix/api/src/index.ts:2070.

/health is the cheap liveness probe — returns the string ok. /api/v1/status probes DB, R2, and the LLM provider in parallel and returns a structured component map.

# Liveness — used by load balancers
curl -s https://api.prix.dev/health
# ok

# Component status — used by uptime monitors
curl -s https://api.prix.dev/api/v1/status
# {
#   "ok": true,
#   "components": { "db": "up", "r2": "up", "llm": "up" },
#   "groups":     { "api": "up", "catalog": "up", "proxy": "up", "auth": "up", "store": "up", "sharing": "up" },
#   "latency_ms": { ... },
#   "ts": "..."
# }

Defined in prix/api/src/index.ts:686 and prix/api/src/index.ts:697.

Used by the Rush app to start, complete, refresh, and revoke provider connections. Most users never call these directly — they run when you click “Connect Google” in the app.

Defined in prix/api/src/index.ts:2089–2171. Notion, Slack, and Pinterest follow the same shape — see lines 2139–2228.

All Gmail routes require the bearer plus X-Google-Access-Token. Each handler reads the provider token directly — see prix/api/src/gmail/index.ts:505 (const googleToken = req.headers.get("X-Google-Access-Token")).

Defined in prix/api/src/index.ts:2988–3058.

rush http GET /api/v1/gmail/messages --oauth google
rush http POST /api/v1/gmail/send --oauth google -d '@./body.json'

Defined in prix/api/src/index.ts:3129–3186.

All Twitter routes require the bearer plus X-Twitter-Access-Token (see prix/api/src/twitter/index.ts:171).

Defined in prix/api/src/index.ts:3451–3519.

rush http POST /api/v1/twitter/tweets --oauth twitter \
  -d '{"text":"Hello from Rush"}'

Mail, calendar, contacts, and OneDrive via Microsoft Graph. Bearer plus a Microsoft access token (see prix/api/src/index.ts:3066–3111).

Adds an email to the waitlist. No bearer required.

curl -s -X POST https://api.prix.dev/api/v1/waitlist \
  -H "Content-Type: application/json" \
  -d '{"email":"[email protected]","source":"getrush.ai"}'
# { "ok": true }

Defined in prix/api/src/index.ts:762–786.

:id must match the pattern developer/slug (alphanumeric + hyphens/underscores, single slash). Body: prompt required, session_id optional. Response is an SSE stream of execution events.

rush http POST /api/v1/agents/prix/rabbit-hole/execute \
  -d '{"prompt":"Research quantum computing","session_id":"session_abc"}'

Defined in prix/api/src/routes/agent-execute.ts:7 (Hono route) and prix/api/src/routes/execute.ts:22 (handler). Path pattern /^\/api\/v1\/agents\/[^/]+\/execute$/ is also matched in prix/api/src/index.ts:729 for the Hono dispatch.

The LLM proxy. Agents call this to invoke a model — the request shape mirrors the upstream provider, the proxy authenticates the Rush user, enforces quotas, and forwards the call.

# Bearer required. Body passes through to the upstream provider.
rush http POST /api/v1/proxy -d '@./model-request.json'

Defined in prix/api/src/index.ts:727 (dispatch) and prix/api/src/routes/proxy.ts:9 (Hono handler chained through requireAuthWithOrg + requireLimits).

Public endpoints are IP-rate-limited via checkRateLimit(clientId, bucket). The waitlist route at prix/api/src/index.ts:766 uses the "waitlist" bucket. Authenticated routes go through requireLimits("llm") middleware (see prix/api/src/routes/proxy.ts:8) — exhausted quotas return 429 (rate) or 402 (subscription).