StyleMint API

Email-based passwordless login. Link expires in 15 minutes. Deep-link to your mobile app.

curl -X POST http://localhost:5000/v1/auth/magic-link/send \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"email":"user@example.com","redirectUrl":"stylemint://auth/callback"}'

WebAuthn / FIDO2 passkeys. Platform biometrics (Face ID, fingerprint).

# Begin registration challenge
curl -X POST http://localhost:5000/v1/auth/passkey/register/begin \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{"deviceName":"iPhone 15 Pro"}'

Social login with Google, Apple, and Facebook. One call to exchange the provider token for a StyleMint JWT.

curl -X POST http://localhost:5000/v1/auth/oauth/token \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"provider":"Google","idToken":"...","authorizationCode":"..."}'

All list endpoints use cursor-based pagination. No offset. No page numbers. Deterministic and scalable.

# First page (no cursor)
GET /v1/discovery/feed?limit=25

# Next page (use nextCursor from previous response)
GET /v1/discovery/feed?limit=25&after=eyJzY29yZSI6MTIzNC41Nn0=

# Response:
{ "items": [...], "nextCursor": "opaque||null" }
# null nextCursor = end of collection

RFC 7807 Problem Details. Clients should key on errorCode, not HTTP status codes.

// 404 — Entity not found
{
  "type":"https://stylemint.dev/errors/entity.not_found",
  "title":"Entity not found.",
  "status":404,
  "errorCode":"entity.not_found",
  "field":null,
  "correlationId":"550e8400-..."
}

// 422 — Validation failure
{
  "errorCode":"validation.required_field",
  "field":"phoneNumber",
  "errors":[{"field":"phoneNumber","message":"Required."}]
}

Four payment methods. All card data is tokenized — raw PAN never touches our servers.

curl -X POST http://localhost:5000/v1/payments/intent \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "orderId":"...",
    "amount":{"amount":2599.00,"currency":"NPR"},
    "method":"Esewa",
    "returnUrl":"stylemint://payment/complete"
  }'

# Supported: Visa/Mastercard (3DS), PayPal v2, eSewa Epay v2, Cash on Delivery

Three SignalR hubs for real-time experiences. Authenticate with your JWT.

ws://localhost:5000/hubs/notifications     # In-app push
ws://localhost:5000/hubs/companion         # Minty AI chat
ws://localhost:5000/hubs/live/{sessionId}  # Live commerce

// JavaScript client:
const conn = new signalR.HubConnectionBuilder()
  .withUrl("/hubs/companion", { accessTokenFactory: () => token })
  .build();
await conn.start();

// 1. Phone OTP — primary auth (most users)
POST /v1/auth/otp/send      {"phoneNumber":"+977-9800000000"}
POST /v1/auth/otp/verify     {"phoneNumber":"+977-9800000000","code":"12345"}
→ { accessToken, refreshToken, account, roles, activeRole }

// 2. Magic Link — passwordless email
POST /v1/auth/magic-link/send  {"email":"user@example.com","redirectUrl":"stylemint://auth/callback"}
→ deep link: stylemint://auth/magic?token=...&tokenId=...

// 3. Passkey — WebAuthn / platform biometrics
POST /v1/auth/passkey/register/begin   {"deviceName":"iPhone 15 Pro"}
POST /v1/auth/passkey/register/finish  // complete WebAuthn ceremony

// 4. OAuth — social login
POST /v1/auth/oauth/token  {"provider":"Google","idToken":"...","authorizationCode":"..."}

// Token refresh — Dio interceptor handles automatically
POST /v1/auth/refresh  Authorization: Bearer {refreshToken}
→ { accessToken, expiresAtUtc }

// Role switching — no re-login needed
POST /v1/accounts/{id}/roles/{role}/activate  → new access token with updated active_role claim

// lib/auth/auth_state.dart — Riverpod auth state
@freezed
class AuthState with _$AuthState {
  const factory AuthState({
    String? accessToken,
    String? refreshToken,
    AccountInfo? account,
    @Default([]) List roles,
    Role? activeRole,  // Customer | Creator | Vendor
  }) = _AuthState;
}
enum Role { customer, creator, vendor }

// lib/auth/secure_storage.dart — hardware-backed token storage
import 'package:flutter_secure_storage/flutter_secure_storage.dart';

class SecureStore {
  static const _refreshKey = 'refreshToken';
  static const _storage = FlutterSecureStorage(
    aOptions: AndroidOptions(encryptedSharedPreferences: true),
    iOptions: IOSOptions(accessibility: KeychainAccessibility.first_unlock),
  );

  static Future   setRefresh(String t) => _storage.write(key: _refreshKey, value: t);
  static Future getRefresh()         => _storage.read(key: _refreshKey);
  static Future   clearRefresh()        => _storage.delete(key: _refreshKey);
}

Customer role — browse, search, buy, post in feed, recommend products, join groups. Most endpoints require Bearer auth.

// ── Onboarding: Pick 3+ interest categories from 65 available
GET   /v1/onboarding/interests           → [CategoryDto]
PUT   /v1/onboarding/interests           { categoryIds: [...] }

// ── Discovery: Personalized feed, search, trending
GET   /v1/discovery/feed?limit=25&after={cursor} → PagedResult
GET   /v1/discovery/search?q=laptop&limit=25     → PagedResult
GET   /v1/discovery/trending?window=24h&limit=20 → PagedResult
GET   /v1/discovery/search/visual                  // Image similarity search
GET   /v1/discovery/search/vibe?mood=minimalist     // Mood-based discovery

// ── Catalog: Browse products, view details, read reviews
GET   /v1/catalog/products?category=electronics&limit=25 → PagedResult
GET   /v1/catalog/products/{id}                          → ProductDto (full PDP)
GET   /v1/catalog/reviews?productId={id}                 → PagedResult

// ── Reels: Watch shoppable reels, tap product tags to add-to-cart
GET   /v1/reels/feed?limit=20                 → reel feed
GET   /v1/reels/{id}                          → reel + tagged product cards
POST  /v1/reels/{id}/comments  { body: "..." } → add comment

// ── Cart & Checkout (Redis-backed cart)
GET   /v1/cart                                → CartDto (with line items + creator attribution)
POST  /v1/cart/items  { productVariantId, quantity } → add to cart
POST  /v1/cart/checkout                        → begin checkout session
POST  /v1/cart/checkout/{id}/shipping  { addressId } → set shipping
POST  /v1/cart/checkout/{id}/confirm            → finalize, reserve inventory

// ── Orders: Tracking, cancel, returns
GET   /v1/orders                            → ListOrdersResponseDto
GET   /v1/orders/{id}                       → OrderDetailDto (with sub-orders per vendor)
GET   /v1/orders/{id}/tracking              → TransitTimelineDto
POST  /v1/orders/{id}/cancel  { reasonCode } → cancel (6 reason codes)
POST  /v1/orders/{id}/return  { photos, reason } → return within 7 days

// ── Payments: 4 methods only — Visa/MC, PayPal, eSewa, Cash on Delivery
POST  /v1/payments/intent  { orderId, amount: {amount,currency}, method: "Esewa", returnUrl }
POST  /v1/payments/intent/{id}/confirm  → authorize payment
POST  /v1/payments/webhooks/esewa       → eSewa verification (auto-called by PSP)

Creator role — apply, connect social accounts, import reels, manage partnerships, earn commission.

// ── Onboarding: Submit creator application (1-3 biz-day SLA)
POST  /v1/onboarding/creator/apply  { contentCategories: [...], description, socialLinks }
GET   /v1/onboarding/creator/status → application status

// ── Social: Connect IG/TT/YT/FB via OAuth
POST  /v1/social/connect/instagram    → OAuth redirect flow
POST  /v1/social/connect/tiktok       → OAuth redirect flow
GET   /v1/social/accounts             → list connected accounts
DELETE /v1/social/accounts/{id}       → disconnect

// ── Reel Import: Import a reel (pointer record only — no video hosted)
POST  /v1/reels/import  { sourceUrl, sourcePlatform, durationSeconds, caption }
POST  /v1/reels/{id}/tag  { productVariantId, commissionRate }  → tag product on reel

// ── Partnerships: Manage brand relationships + commission
GET   /v1/partnerships                → list my partnerships
POST  /v1/partnerships                → invite brand (creator-initiated)
POST  /v1/partnerships/{id}/accept    → accept brand invite
GET   /v1/partnerships/{id}/terms     → active terms & commission range
GET   /v1/partnerships/{id}/earnings  → commission projection (@50 sales)

// ── Creator Studio (Pillar D): Pre-publish coaching
POST  /v1/creator-studio/reels/{id}/analyze  → pre-publish analysis (hook score, audio recs, caption variants)
GET   /v1/creator-studio/reels/{id}/report   → Post-Publish Coach (24h structured report)
POST  /v1/creator-studio/story-arcs          → create Story Arc (series → +10% commission boost)
GET   /v1/creator-studio/performance         → creator analytics dashboard

// ── Reach (Pillar E): Cross-platform publishing + AI boost
POST  /v1/reach/publish  { reelId, platforms:["instagram","tiktok"], scheduleUtc }
POST  /v1/reach/boost    { reelId, budget: {amount,currency}, platforms, maxCpc }
GET   /v1/reach/analytics → unified cross-platform analytics

// ── Payouts: Withdraw earnings
GET   /v1/payouts/earnings              → append-only ledger
GET   /v1/payouts/earnings/summary      → available / pending breakdown
POST  /v1/payouts/withdraw  { amount, destinationId }  → on-demand (2% fee)
POST  /v1/payouts/methods   { type:"NIMB", accountNumber, accountName }  → add destination

Vendor role — apply, list products, run partnership campaigns, fulfill orders, withdraw earnings.

// ── Onboarding: Submit vendor/brand application
POST  /v1/onboarding/vendor/apply  { businessName, kycDocuments, brandCategory }
GET   /v1/onboarding/vendor/status → application status

// ── Catalog: 5-step Add Product wizard
POST  /v1/catalog/products                  → Step 1: Basic (name, description, category)
PUT   /v1/catalog/products/{id}             → Steps 2-5: images, pricing, shipping, review
POST  /v1/catalog/products/{id}/variants    → create variants (size/color/etc)
POST  /v1/catalog/products/{id}/images      → upload product images
GET   /v1/catalog/products/mine?limit=25    → my products
GET   /v1/catalog/products/{id}/analytics   → product performance (views, sales, commission)

// ── Partnerships: Invite creators, manage campaigns
POST  /v1/partnerships           { creatorProfileId, commissionMinPercent, commissionMaxPercent, termsVersionId }
GET   /v1/partnerships           → both incoming + outgoing
POST  /v1/partnerships/{id}/end  { reason }  → end partnership

// ── Brand Studio (Pillar D): Campaign authoring + intelligence
POST  /v1/brand-studio/briefs     → create AI-assisted campaign brief
GET   /v1/brand-studio/briefs     → list my briefs
GET   /v1/brand-studio/dashboard  → brand intelligence: top creators, attributed sales, ROI

// ── Matchmaking (Pillar E): Find creators who fit your brand
GET   /v1/matchmaking/creators?category=electronics     → ranked creator matches
GET   /v1/matchmaking/featured                           → weekly curated matches
POST  /v1/matchmaking/{id}/connect                       → send match connection

// ── Orders: Fulfillment
GET   /v1/orders/vendor?limit=25    → sub-orders assigned to me
PUT   /v1/orders/{id}/fulfill       → mark sub-order as fulfilled

// ── Payouts: Auto-weekly (Friday, free) + On-demand (2% fee, 10k-70k NPR)
GET   /v1/payouts/earnings          → all settled + pending rows
POST  /v1/payouts/withdraw          → request payout
POST  /v1/payouts/methods           → add bank/PayPal/eSewa destination

Social commerce layer (Pillars C + F) — friend feeds, stories, recommendation threads, groups, co-watch, tips.

// ── Social Feed (Pillar F): Posts, stories, reactions
GET   /v1/social/feed?limit=25                         → personalized feed
POST  /v1/social/feed/posts  { body, visibility, attachments }
POST  /v1/social/feed/stories  { imageUrl }             → 24h story
POST  /v1/social/feed/posts/{id}/reactions  { type }   → like/love/wow etc
POST  /v1/social/feed/posts/{id}/comments  { body }    → comment on post
GET   /v1/social/feed/hashtags/trending                 → trending tags

// ── Networking (Pillar F): Mutual friendships
POST  /v1/networking/requests  { receiverAccountId, message }
GET   /v1/networking/friends    → my friend list
POST  /v1/networking/requests/{id}/accept
GET   /v1/networking/suggestions → people you may know

// ── Recommendations (Pillar F): Ask friends what to buy
POST  /v1/recommendations/requests  { title, body, categoryId }
GET   /v1/recommendations/requests?limit=25   → browse threads
POST  /v1/recommendations/requests/{id}/replies  { productId, comment }
POST  /v1/recommendations/replies/{id}/vote  { vote: "up" }
POST  /v1/recommendations/replies/{id}/accept → accept answer (2% affiliate for recommender)

// ── Community (Pillar F): Interest groups + professional circles
POST  /v1/community/groups  { name, category, isPrivate }
GET   /v1/community/groups?category=tech  → browse groups
POST  /v1/community/groups/{id}/join  { message }
POST  /v1/community/groups/{id}/posts  { body, attachments }

// ── Gen Z mechanics (Pillar C): Group carts, Style Circles, Co-Watch, Drop Parties, Tips
POST  /v1/social/graph/group-carts  { productIds, members }
POST  /v1/social/graph/circles  { name, memberAccountIds }    → Style Circle (max 20)
POST  /v1/social/graph/co-watch/{reelId}/start                → co-watch session
POST  /v1/social/graph/drop-parties  { reelId, startsUtc, products }
POST  /v1/social/graph/tips  { reelId, creatorAccountId, amount: {amount,currency} }  → 3% fee
POST  /v1/social/graph/stitches  { parentReelId, childReelUrl, platform }  → stitched reply reel

// ── Realtime: SignalR hubs
WS    /hubs/notifications            → in-app realtime push
WS    /hubs/companion               → Minty AI companion chat
WS    /hubs/live/{sessionId}        → live commerce reactions + purchases

Each Figma screen maps to 1-2 API calls. The backend is pre-denormalized — response DTOs are shaped exactly as the screen renders. If you need 3 GETs for one screen, flag the backend for a denormalized view.