Skip to main content
The Handa Uncle backend powers both the /api/v1/* web APIs (secured with Auth0 JWTs) and the /app/* mobile bootstrap flow. This reference keeps both surfaces in sync with the live codebase.

​
Base URLs

All web APIs are versioned and live under /api/v1. The dedicated mobile app router is mounted at /app.

​
Authentication & headers

  • Web APIs (/api/v1/*) — require Authorization: Bearer <JWT> where the token is issued by Auth0. Standard scopes such as admin:rag gate privileged endpoints.
  • Mobile App Launch (/app/launch) — uses signed device headers instead of JWTs:
    • x-device-id (required): stable device or installation identifier
    • x-platform (required): android, ios, or web
    • x-user-id, x-user-email, x-user-phone (optional hints)
  • Every successful response includes an X-Request-ID header; log it when filing support tickets.

​
Standard response envelope

Errors use the same envelope with an error object instead of data.

​
Rate limits

Anonymous traffic is throttled via a composite identifier (IP + route + hashed fingerprint) so multiple guests on the same network are treated fairly.

​
Tooling

  • Live OpenAPI file: /docs/api-reference/openapi.json
  • Example endpoints: see the App Launch and health checks in the sidebar
  • For a deeper architectural view, start with README.md in the repo root