# API (`/api/v1`)

JSON API for future mobile apps and integrations. Throttled at 60 requests/minute. Endpoints ship with their phase:

| Endpoint | Phase |
|---|---|
| `GET /products` ✅, `GET /products/{slug}` ✅ | 2 |
| `GET /orders` ✅ (token) | 3 |
| `GET /quiz/{slug}` ✅, `POST /quiz/{slug}/submit` ✅, `GET /rewards` ✅, `POST /rewards/{id}/redeem` ✅, `GET /referrals` ✅, `GET /me` ✅ | 3 |
| `POST /cart`, `POST /checkout` | later (checkout runs on the web; payments need Paystack's hosted page) |
| `POST /ai/try-on` ✅, `GET /ai/try-ons` ✅, `GET /ai/try-ons/{id}` ✅ (token) | 4 |
| `GET /ugc` ✅, `GET /challenges` ✅, `POST /ugc` ✅ (token), `GET /ugc/mine` ✅ (token) | 5 |
| `GET /creator/dashboard` ✅ (token) | 6 |

No administrative endpoints are exposed over the API.

### Authentication

```
POST /api/v1/auth/token   { "email": "…", "password": "…", "device_name": "iPhone" }  → 201 { "token": "1|…", "token_type": "Bearer" }
DELETE /api/v1/auth/token (Authorization: Bearer …)
```
Token issuing is throttled (5/min). Suspended accounts can't get tokens. All customer endpoints are scoped to the token's user.

### `GET /api/v1/products`

Query: `q`, `colour` (slug), `category`, `collection`, `sort` (`featured|newest|price_asc|price_desc|popular|best_selling`), `in_stock` (bool). Paginated (24). Each product lists its variants with `price.kobo`, `price.formatted`, `compare_at` and `in_stock`.

### AI try-on (token)

```
POST /api/v1/ai/try-on   multipart: photo, variant_ids[]=12, consent=1   → 202 { data: [ { id, status, colour, images… } ] }
GET  /api/v1/ai/try-ons            your last 50 previews
GET  /api/v1/ai/try-ons/{id}       poll one (status: queued | processing | succeeded | failed)
GET  /api/v1/ai/try-ons/{id}/after image (JPEG), owner's token only; `before` while the original still exists
```
Same consent, daily limits, budget cap and auto-deletion as the website (see AI.md). `422 { message }` when a limit applies.

### Wall & challenges

```
GET  /api/v1/ugc?colour=pink&challenge=pink-for-a-week   approved posts only, featured first (paginated, 24)
GET  /api/v1/challenges                                   published challenges with state (upcoming | live | judging | complete)
POST /api/v1/ugc   (token) multipart: after, before?, variant_id?, caption?, social_handle?, challenge? (slug), consent=1 → 201 { data: { id, status: "pending" } }
GET  /api/v1/ugc/mine (token)                             your posts with status and rejection reason
```
Posts are moderated before they appear; storage paths are never returned. Posting is throttled (10/min) on top of the per-customer pending/daily limits.

### Creator dashboard (token)

```
GET /api/v1/creator/dashboard → { data: { code, status, commission_rate, customer_discount, rank_this_month,
                                          last_30_days: { clicks, orders, revenue, conversion, earned, pending, payable, paid },
                                          all_time: {…}, payable, links: [ { label, url, destination, clicks } ] } }
```
`403` if the token's account isn't a creator. Money is in kobo.

