API Modules — Frontpics Image Marketplace

All routes are served under /api/v1. Authentication uses JWT access tokens and role guards. Request validation is primarily handled with shared Zod schemas from packages/shared.

Response Conventions

Most list endpoints return an envelope:

{
  "data": [],
  "meta": { "page": 1, "total": 50, "limit": 20 }
}

Some older endpoints return a plain object or array. Check the controller/service before changing a client call.

Auth — /auth

Method	Path	Auth	Description
POST	/auth/register	Public	Register buyer, photographer, moderator, payroll, or admin as permitted by the current registration flow. Creates wallet and role profile where applicable.
POST	/auth/login	Public	Returns access token and sets refresh cookie.
POST	/auth/refresh	Cookie	Rotates refresh token and returns a new access token.
POST	/auth/logout	JWT/cookie	Invalidates refresh token and clears cookie.
POST	/auth/verify-email	Public	Verifies email with token.
POST	/auth/forgot-password	Public	Sends reset link.
POST	/auth/reset-password	Public	Resets password with token.

JWT validation returns { id, email, role }. Use user.id in services and controllers.

Users — /users

Method	Path	Auth	Description
GET	/users/me	JWT	Current user with role profile.
PATCH	/users/me	JWT	Update account fields.
PATCH	/users/me/password	JWT	Change password.
GET	/users/me/billing	JWT buyer	Buyer billing/profile details used for purchase references.

Use firstName and lastName; the User model has no displayName.

Images — /images

Method	Path	Auth	Description
GET	/images	Public/JWT optional	Browse active images. Supports search, filters, sorting, pagination, purchase flags for authenticated buyers, and location filtering.
GET	/images/:id	Public/JWT optional	Image detail with files, tags, location, photographer, purchase state, and download metadata where allowed.
GET	/images/map-pins	Public/JWT optional	Map pin data for images with coordinates.
GET	/images/mine	Photographer	Photographer's own images.
PATCH	/images/:id	Photographer owner/admin	Edit metadata where allowed.
DELETE	/images/:id	Photographer owner/admin	Soft-delete where allowed.
POST	/images/:id/submit	Photographer owner	Submit draft for review.
GET	/images/:id/download/:orderItemId	Buyer owner/admin/moderator	Return signed download URL and agency brand data.

Important fields:

• Image.basePriceCredits
• Image.imageTags
• Image.status
• ImageFile.cdnUrl
• ImageFile.fileSizeBytes
• Location.latitude / Location.longitude

Upload — /upload

Method	Path	Auth	Description
POST	/upload/presigned	Photographer/admin/moderator	Create presigned upload URLs for files.
POST	/upload/check-duplicates	Photographer/admin/moderator	Check SHA-256 hashes against existing images.
POST	/upload/confirm	Photographer/admin/moderator	Create image records, locations, tags, and queue processing jobs.
GET	/upload/status/:jobId	JWT	Poll processing status.

The web upload UI uses EXIF GPS, reverse geocoding, address autocomplete, and manual coordinate fields. Location metadata is stored on Location and used by search/map.

Orders — /orders

Method	Path	Auth	Description
POST	/orders	Buyer	Purchase one or more images atomically.
GET	/orders	Buyer	Own order history.
GET	/orders/:id	Buyer owner	Order detail and download links.

Create request:

{
  "items": [{ "imageId": "uuid" }],
  "buyerReference": "Listing or invoice reference"
}

Business rules:

• Buyer must have enough credits.
• Duplicate active purchases for the same image are rejected.
• Buyer wallet spend and photographer earnings happen in one transaction.
• Purchased image access is represented by OrderItem.

Wallets — /wallets

Method	Path	Auth	Description
GET	/wallets/me	JWT	Wallet balance and totals.
GET	/wallets/me/transactions	JWT	Paginated transaction history.

Payouts — /payouts

Method	Path	Auth	Description
POST	/payouts/request	Photographer	Request a manual bank-transfer payout.
GET	/payouts	Photographer	Own payout history.

Request body:

{
  "amountCredits": 100,
  "paymentMethod": "bank_transfer",
  "note": "Invoice 123"
}

reference and billingReference are accepted as aliases for note.

Rules:

• Minimum payout is 50 credits.
• Photographer profile must have bankIban and bankAccountHolder.
• Only one pending or processing payout is allowed per photographer.
• Requesting a payout deducts/reserves credits immediately and creates a linked CreditTransaction.
• Admin processing records the final payment reference in Payout.paymentRef.

Shooting Requests — /shooting-requests

Method	Path	Auth	Description
POST	/shooting-requests	Buyer	Create a photoshoot request and reserve the configured fixed cost.
GET	/shooting-requests/open	Photographer/admin	List open jobs for available photoshoots.
GET	/shooting-requests/my-orders	Buyer	Buyer's own requests.
GET	/shooting-requests/my-claims	Photographer	Photographer's claimed jobs.
GET	/shooting-requests/cost	Buyer/admin	Current configured request cost.
GET	/shooting-requests/:id	JWT	Request detail.
POST	/shooting-requests/:id/claim	Photographer	Claim an open request.
POST	/shooting-requests/:id/complete	Claimed photographer	Mark claimed request completed.

Create requests accept address fields plus optional latitude and longitude. If coordinates are missing, the API uses the same Nominatim-style structured lookup as upload. Existing locations with missing coordinates are backfilled when possible.

Completing a shooting request credits the photographer wallet, but does not create a completed Payout by default.

Admin — /admin

All admin routes require Role.admin unless explicitly widened to moderator.

Method	Path	Description
GET	/admin/stats	Dashboard stats including pending payouts and storage totals.
GET	/admin/action-counts	Badge counts: pending images, unread incoming emails, open feedback, pending payouts. Admin and moderator can call it.
GET	/admin/users	User list with filters.
PATCH	/admin/users/:id/suspend	Suspend user.
PATCH	/admin/users/:id/activate	Activate user.
PATCH	/admin/users/:id/role	Change role.
POST	/admin/users/:id/credits	Manual credit adjustment.
PATCH	/admin/users/:id/password	Admin password reset.
DELETE	/admin/users/:id	Soft-delete user.
GET	/admin/images/pending	Moderation queue.
GET	/admin/images	All images with filters.
PATCH	/admin/images/:id/approve	Approve image.
PATCH	/admin/images/:id/reject	Reject image.
DELETE	/admin/images/:id	Delete/soft-delete image and storage objects where allowed.
GET	/admin/payouts	Payout list, optionally filtered by status. Includes bank details and photographer request reference.
PATCH	/admin/payouts/:id/process	Mark payout completed with admin payment reference.
PATCH	/admin/payouts/:id/reject	Reject payout and refund credits.
GET	/admin/audit	Audit log list.
GET	/admin/brands	Agency brand list.
POST/PATCH/DELETE	/admin/brands	Manage centralized agency branding.
GET/PATCH	/admin/settings/*	Storage, image, credit, page, and processing settings.

Incoming Emails, Feedback, and Invoices

Additional modules support admin inboxes, feedback handling, and payroll/invoice reporting. These are implemented as separate Nest modules and web routes. Check the module controller before changing response assumptions.