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.