{
  "title": "Style Mint API",
  "version": "v1",
  "baseUrl": "/v1",
  "description": "StyleMint is a general-purpose social commerce platform \u2014 a three-sided mobile-first reel-commerce marketplace on modular monolith architecture.",
  "authentication": {
    "type": "JWT Bearer",
    "header": "Authorization: Bearer {token}",
    "tokenUrl": "/v1/auth/signup (phone OTP) or /v1/auth/login",
    "refreshTokenUrl": "/v1/auth/refresh"
  },
  "modules": [
    {
      "name": "identity",
      "prefix": "/v1/auth",
      "endpoints": 28,
      "description": "Accounts, auth (OTP/magic-link/passkey/OAuth), KYC, sessions, payment instruments, professions, preferences, privacy, GDPR, consent, tax info, blocks"
    },
    {
      "name": "onboarding",
      "prefix": "/v1/onboarding",
      "endpoints": 12,
      "description": "Customer interests, Creator application (15 content categories), Vendor/brand setup"
    },
    {
      "name": "catalog",
      "prefix": "/v1/catalog",
      "endpoints": 35,
      "description": "Products, brands, categories (65 top-level), reviews, Add Product 5-step wizard, flash sales, dynamic pricing"
    },
    {
      "name": "reels",
      "prefix": "/v1/reels",
      "endpoints": 22,
      "description": "Imported reel aggregates (pointer records only), tagged product cards, comments, engagement snapshots"
    },
    {
      "name": "discovery",
      "prefix": "/v1/discovery",
      "endpoints": 18,
      "description": "Search, trending, personalized feed, AI-powered visual/vibe/audio search"
    },
    {
      "name": "social",
      "prefix": "/v1/social",
      "endpoints": 12,
      "description": "Creator social account connections (IG/TT/YT/FB OAuth), reel import"
    },
    {
      "name": "partnerships",
      "prefix": "/v1/partnerships",
      "endpoints": 30,
      "description": "Creator-vendor partnerships, commission rates, terms, milestones, campaigns, squads, retainers"
    },
    {
      "name": "cart-checkout",
      "prefix": "/v1/cart",
      "endpoints": 16,
      "description": "Redis/Postgres cart, checkout saga, inventory holds, shipping addresses"
    },
    {
      "name": "orders",
      "prefix": "/v1/orders",
      "endpoints": 24,
      "description": "Orders/sub-orders, fulfillment, returns, cancel flow, predictive reorder"
    },
    {
      "name": "payments",
      "prefix": "/v1/payments",
      "endpoints": 14,
      "description": "Visa/MC, PayPal, eSewa, Cash on Delivery \u2014 full lifecycle"
    },
    {
      "name": "payouts",
      "prefix": "/v1/payouts",
      "endpoints": 16,
      "description": "Creator/vendor earnings ledger, auto-weekly \u002B on-demand payouts, 4 destinations"
    },
    {
      "name": "messaging",
      "prefix": "/v1/notifications",
      "endpoints": 8,
      "description": "Push (FCM/APNs), email (SES), in-app (SignalR), quiet hours, localized templates"
    },
    {
      "name": "support",
      "prefix": "/v1/support",
      "endpoints": 14,
      "description": "Tickets (#ST{6 digits}), Help Center, notification preferences, 5 languages"
    },
    {
      "name": "admin",
      "prefix": "/v1/admin",
      "endpoints": 40,
      "description": "KYC review, moderation, refunds, disputes, feature flags, platform config, audit log"
    },
    {
      "name": "intelligence",
      "prefix": "/v1/intelligence",
      "endpoints": 20,
      "description": "AI infrastructure: LLM/embeddings/vision (Anthropic\u002BOpenAI failover), pgvector store, scorers, signals, A/B tests"
    },
    {
      "name": "delivery",
      "prefix": "/v1/delivery",
      "endpoints": 18,
      "description": "P2P delivery: packages, hops, tracking (SM-D-{8 digits}), chain-of-custody, story mode"
    },
    {
      "name": "delivery-routing",
      "prefix": "/v1/delivery/routing",
      "endpoints": 10,
      "description": "Three-tier courier routing (Pro/Traveler/Neighbor), Dutch auctions, multi-hop composition"
    },
    {
      "name": "delivery-couriers",
      "prefix": "/v1/delivery/couriers",
      "endpoints": 14,
      "description": "Courier profiles, KYC, tiers, device keys, reliability scores, travel plans"
    },
    {
      "name": "social-graph",
      "prefix": "/v1/social/graph",
      "endpoints": 20,
      "description": "Group carts, Style Circles (max 20), Co-Watch, Drop Parties, Tips, Stitched Reels"
    },
    {
      "name": "reputation",
      "prefix": "/v1/reputation",
      "endpoints": 12,
      "description": "Multi-facet reputation (5 facets), badges, proof-of-buy verification"
    },
    {
      "name": "creator-studio",
      "prefix": "/v1/creator-studio",
      "endpoints": 16,
      "description": "Reel Studio pre-publish analysis, Story Arcs (\u002B10% commission boost), Post-Publish Coach"
    },
    {
      "name": "brand-studio",
      "prefix": "/v1/brand-studio",
      "endpoints": 14,
      "description": "Brand Brief Builder, intelligence dashboard, campaign authoring"
    },
    {
      "name": "audio",
      "prefix": "/v1/audio",
      "endpoints": 10,
      "description": "Audio reference catalog (no hosting), reel audio recommendations"
    },
    {
      "name": "reel-recipes",
      "prefix": "/v1/recipes",
      "endpoints": 12,
      "description": "Pre-production reel recipes: songs, shot lists, captions, per-platform instructions"
    },
    {
      "name": "reach",
      "prefix": "/v1/reach",
      "endpoints": 16,
      "description": "Cross-platform publish, AI boost engine, unified analytics dashboard"
    },
    {
      "name": "matchmaking",
      "prefix": "/v1/matchmaking",
      "endpoints": 14,
      "description": "Brand-creator AI matchmaking, 3 surfaces, proactive nudges, quarterly fairness audits"
    },
    {
      "name": "social-feed",
      "prefix": "/v1/social/feed",
      "endpoints": 22,
      "description": "Posts, stories (24h), comments, reactions, hashtags, mentions, attachments"
    },
    {
      "name": "recommendations",
      "prefix": "/v1/recommendations",
      "endpoints": 18,
      "description": "Ask friends what to buy, replies, votes, accepted answers, expertise, 2% affiliate share"
    },
    {
      "name": "networking",
      "prefix": "/v1/networking",
      "endpoints": 16,
      "description": "Mutual friend connections, requests, categories, privacy, contacts import (hash-only)"
    },
    {
      "name": "community",
      "prefix": "/v1/community",
      "endpoints": 20,
      "description": "Interest groups, professional circles (KYC-required), group posts, events, moderation"
    },
    {
      "name": "companion",
      "prefix": "/v1/companion",
      "endpoints": 8,
      "description": "Minty AI Shopping Best Friend, conversational commerce, SignalR chat, proactive nudges"
    }
  ],
  "commonHeaders": [
    {
      "name": "Idempotency-Key",
      "type": "string (UUID)",
      "required": "Mutating requests",
      "description": "Prevents duplicate operations. Supply a unique UUID per request intent."
    },
    {
      "name": "X-Correlation-Id",
      "type": "string (UUID)",
      "required": "Optional",
      "description": "Trace ID for request correlation. Auto-assigned if not provided."
    },
    {
      "name": "Accept-Language",
      "type": "string",
      "required": "Optional",
      "description": "Supported: en-US, zh, ne, es, hi. Defaults to en-US."
    }
  ],
  "pagination": {
    "type": "Cursor-based",
    "parameters": [
      "limit (max 100)",
      "after (opaque cursor string)"
    ],
    "response": {
      "items": "T[]",
      "nextCursor": "string|null (null = end of collection)"
    }
  },
  "errors": {
    "format": "RFC 7807 Problem Details",
    "shape": {
      "type": "string",
      "title": "string",
      "status": "int",
      "errorCode": "string",
      "field": "string|null",
      "correlationId": "string",
      "errors": "object[]|null"
    },
    "commonCodes": [
      "auth.invalid_token",
      "auth.expired_token",
      "idempotency.duplicate",
      "validation.required_field",
      "entity.not_found",
      "entity.duplicate",
      "entity.conflict",
      "business.rule_violation",
      "forbidden",
      "rate_limited",
      "system.internal_error"
    ]
  },
  "paymentMethods": [
    "Visa/Mastercard (3DS)",
    "PayPal (Orders v2)",
    "eSewa (Epay v2)",
    "Cash on Delivery"
  ],
  "payoutMethods": [
    "NIMB Bank",
    "Laxmi Bank",
    "PayPal",
    "eSewa"
  ],
  "signalR": [
    {
      "hub": "/hubs/notifications",
      "description": "Real-time in-app notifications"
    },
    {
      "hub": "/hubs/companion",
      "description": "Minty AI companion chat"
    },
    {
      "hub": "/hubs/live/{sessionId:guid}",
      "description": "Live commerce real-time reactions and purchases"
    }
  ]
}