docs/API.md

# API Documentation

Base path: `/api/v1`

## Auth

- `POST /auth/login`
  - Admin username/password login.
  - Returns `access_token`, `refresh_token`, and expiry metadata.
- `POST /auth/refresh`
  - Exchanges a refresh token for a fresh token pair.
- `GET /auth/me`
  - Returns the authenticated user profile.

## Users

- `GET /users/me/profile`
- `GET /users/me/credits`
- `PATCH /users/me/settings`
- `GET /users/me/history`
- `GET /users/{user_id}` (admin only)

## Images

- `POST /images/upload`
  - Accepts `multipart/form-data` with a photo file.
  - Validates file type, size, and integrity.
- `GET /images/me`

## Jobs

- `POST /jobs/`
  - Creates and dispatches a queued job.
  - Supports:
    - `text_to_image`
    - `anime_style`
    - `ghibli_style`
    - `cartoon_style`
    - `realistic_enhancement`
    - `face_enhancement`
    - `background_removal`
    - `background_replacement`
    - `object_removal`
    - `object_replacement`
    - `ai_repaint`
    - `inpainting`
    - `outpainting`
    - `upscale`
    - `colorization`
    - `old_photo_restoration`
- `GET /jobs/me`
- `GET /jobs/{job_id}`
- `POST /jobs/{job_id}/cancel`

## Models

- `GET /models/`
  - Lists configured model descriptors and capabilities.

## Admin

- `GET /admin/stats`
- `GET /admin/users`
- `GET /admin/jobs`
- `POST /admin/credits/grant`
- `POST /admin/broadcasts`

## Payments

- `POST /payments/checkout`
  - Creates a provider-specific checkout session or deep link.
- `GET /payments/me/transactions`

## Auth Model

- Bearer JWT for API routes.
- HTTP-only JWT cookie for the server-rendered admin dashboard.
- Role enforcement on admin endpoints using the `roles` claim and Mongo user record validation.

## Error Behavior

- `400`: invalid prompt, blocked prompt, invalid file.
- `401`: missing or invalid token.
- `402`: insufficient credits.
- `403`: role violation.
- `404`: missing resource.
- `429`: rate limit or daily quota exceeded.
- `500`: worker or infrastructure error.