{"openapi":"3.1.0","info":{"title":"DPulse Haraj Marketplace API","version":"2.0.0","description":"Official REST API for haraj.dpulse.sa \u2014 Haraj Storefront, Annual Memberships, Admin-Exclusive Theme Engine, Live Auctions, Smart Escrow, ZATCA Phase 1 & 2, PDPL Compliance, and AI Router.","contact":{"name":"Data Pulse Engineering","url":"https:\/\/haraj.dpulse.sa\/docs\/api"}},"servers":[{"url":"https:\/\/haraj.dpulse.sa\/api\/v1","description":"Active Environment"},{"url":"https:\/\/haraj.dpulse.sa\/api\/v1","description":"Production Live Demo"}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"DPulse-PAT"},"WebhookHmac":{"type":"apiKey","in":"header","name":"X-Signature"}}},"paths":{"\/bootstrap\/theme-config":{"get":{"tags":["Bootstrap"],"summary":"Admin-governed active theme preset, fonts, logos & feature flags with ETag"}},"\/memberships":{"get":{"tags":["Memberships"],"summary":"List Haraj annual & monthly membership plans"}},"\/auth\/otp\/request":{"post":{"tags":["Identity & Auth"],"summary":"Request Saudi mobile SMS OTP (Rate-Limited 5\/min)"}},"\/auth\/otp\/verify":{"post":{"tags":["Identity & Auth"],"summary":"Verify OTP and issue SHA-256 Bearer Token"}},"\/geo\/regions":{"get":{"tags":["Geo & Catalog"],"summary":"Saudi 13 regions, cities, and districts"}},"\/categories":{"get":{"tags":["Geo & Catalog"],"summary":"Marketplace categories & dynamic attributes"}},"\/listings":{"get":{"tags":["Listings"],"summary":"Search and filter listings by category, brand, model, year, city & ad_number"},"post":{"tags":["Listings"],"summary":"Create authenticated listing","security":[{"BearerAuth":[]}]}},"\/listings\/{uuid}":{"get":{"tags":["Listings"],"summary":"Show listing details"},"put":{"tags":["Listings"],"summary":"Update own listing (ListingPolicy)","security":[{"BearerAuth":[]}]},"delete":{"tags":["Listings"],"summary":"Delete own listing (ListingPolicy)","security":[{"BearerAuth":[]}]}},"\/commissions\/calculate":{"post":{"tags":["Finance & ZATCA"],"summary":"Calculate commission + 15% VAT"}},"\/invoices\/{uuid}":{"get":{"tags":["Finance & ZATCA"],"summary":"Fetch ZATCA tax invoice (InvoicePolicy)","security":[{"BearerAuth":[]}]}},"\/conversations\/{id}":{"get":{"tags":["Messaging"],"summary":"Read private chat thread (ConversationPolicy)","security":[{"BearerAuth":[]}]}},"\/stories":{"get":{"tags":["Showrooms & Plugins"],"summary":"Active 24h showroom stories"}},"\/auctions":{"get":{"tags":["Auctions"],"summary":"Active live auctions"}},"\/auctions\/{id}\/bids":{"post":{"tags":["Auctions"],"summary":"Place atomic bid with 60s Anti-Sniping"}},"\/ai\/listings\/generate":{"post":{"tags":["AI Router"],"summary":"Fast listing copy & attribute extraction via Client BYOK AI"}},"\/ai\/listings\/from-voice":{"post":{"tags":["AI Router"],"summary":"Saudi dialect Voice-to-Ad via Client BYOK AI"}},"\/ai\/search\/visual-lens":{"post":{"tags":["AI Router"],"summary":"Visual Lens search via Client BYOK AI"}},"\/buyer-requests":{"get":{"tags":["Showrooms & Plugins"],"summary":"Reverse Haraj buyer requests"}},"\/showrooms":{"get":{"tags":["Showrooms & Plugins"],"summary":"Verified showrooms & subscription plans"}},"\/reviews":{"post":{"tags":["Showrooms & Plugins"],"summary":"Verified-deal-only review submission"}},"\/webhooks\/{provider}":{"post":{"tags":["Security"],"summary":"HMAC-signed & idempotent webhook receiver","security":[{"WebhookHmac":[]}]}},"\/account\/pdpl\/delete":{"delete":{"tags":["Privacy"],"summary":"PDPL self-service account anonymization"}},"\/admin\/system\/health-doctor":{"get":{"tags":["Operations"],"summary":"System readiness diagnostics"}}}}