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

EnvironmentBase URL
Productionhttps://api.handauncle.com
Staginghttps://staging-api.handauncle.com
Local devhttp://localhost:8080
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

{
  "success": true,
  "data": { "...": "domain object" },
  "meta": {
    "timestamp": "2025-12-01T07:10:08.337Z",
    "request_id": "6f3dfc92-0a16-41ed-a360-3c78a9272f0f"
  }
}
Errors use the same envelope with an error object instead of data.

​
Rate limits

RouteLimitWindow
/api/v1/ai/chat20 requestsper minute
/api/v1/* (default)100 requestsper minute
OTP send endpoints3 requestsper hour
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