> ## Documentation Index
> Fetch the complete documentation index at: https://docs.handauncle.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Handa Uncle API

> Overview of the Handa Uncle platform and mobile APIs

<Note>
  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.
</Note>

## Base URLs

| Environment | Base URL                             |
| ----------- | ------------------------------------ |
| Production  | `https://api.handauncle.com`         |
| Staging     | `https://staging-api.handauncle.com` |
| Local dev   | `http://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

```json theme={null}
{
  "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

| Route                 | Limit        | Window     |
| --------------------- | ------------ | ---------- |
| `/api/v1/ai/chat`     | 20 requests  | per minute |
| `/api/v1/*` (default) | 100 requests | per minute |
| OTP send endpoints    | 3 requests   | per 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`](./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