REST endpoints for the entire Nuvi platform — Medusa v2 commerce surface, Nuvi extensions for every module (blog, pages, forms, media, search, brand, themes, localization, currency, metafields, redirects, events, travel, subscriptions, quotes, email marketing, tracking, cookie consent), social login (Google, Apple, Facebook, GitHub, Microsoft), and the AI assistant — powered by your own model key (OpenAI, Gemini, DeepL, ElevenLabs) or pay-as-you-go credits — with 24 skills exposed via /admin/ai/* and /v1/*.
Storefront calls authenticate with a publishable API key (header `x-publishable-api-key`). Customer-scoped calls add a JWT bearer issued by the Medusa v2 auth endpoints. Admin calls require an admin JWT.
/auth/customer/emailpassIssue a customer JWT from email + password
/auth/customer/emailpass/registerRegister a new customer
/auth/sessionInvalidate the current session
Standard Medusa v2 product endpoints. Variants, prices, and inventory return inline. Use the dedicated /store/search endpoint for full-text search powered by MeiliSearch.
/store/productsList products with filters (collection, category, region, price range)
/store/products/:idRetrieve a single product by id or handle
/store/product-templatesList product templates for the admin product editor
/store/collectionsList product collections (Medusa default)
/store/categoriesList product categories (Medusa default)
/store/products/:product_id/reviewsList approved reviews for a product (paginated, sorted)
/store/products/:product_id/reviewsSubmit a new review (status: pending until moderated)
MeiliSearch-backed unified search across products, blog posts, pages, and tours. Typo-tolerant, faceted, sub-50ms median.
/store/searchFull-text search across all indexed resources
Standard Medusa cart endpoints plus Nuvi extensions for event tickets and tour bookings. Payment sessions are created against your Stripe / Iyzico accounts.
/store/cartsCreate an empty cart
/store/carts/:id/line-itemsAdd a product line item
/store/carts/:id/event-itemsAdd an event ticket as a line item (Nuvi)
/store/carts/:id/event-items/:lineItemIdRemove an event ticket line item
/store/carts/:id/tour-itemsAdd a tour booking line item (Nuvi)
/store/carts/:id/tour-items/:lineItemIdRemove a tour line item
/store/carts/:id/payment-sessionsCreate payment sessions for available providers
/store/carts/:id/completeConvert the cart to an order
/store/checkout-configActive checkout configuration: enabled fields, payment providers, shipping options
/store/payment-configPer-region payment provider configuration
/store/bank-infoBank-transfer payment instructions for the storefront
Standard Medusa order endpoints plus a customer-side cancel route.
/store/orders/meList orders for the authenticated customer
/store/orders/:idRetrieve a single order by id
/store/orders/:id/cancelCancel an order (within the cancellation window)
Standard Medusa customer endpoints. The authenticated customer can manage their own profile and addresses.
/store/customers/meGet current customer profile
/store/customers/meUpdate profile fields
/store/customers/me/addressesAdd a shipping address
Subscription module endpoints — list available plans, create / manage a customer subscription, and run lifecycle actions (pause, resume, change plan, cancel).
/store/subscription-plansList available subscription plans
/store/subscriptionsList the authenticated customer's subscriptions
/store/subscriptionsCreate a new subscription
/store/subscriptions/:idRetrieve a subscription
/store/subscriptions/checkoutStart a subscription checkout (creates the payment session)
/store/subscriptions/:id/pausePause an active subscription
/store/subscriptions/:id/resumeResume a paused subscription
/store/subscriptions/:id/change-planSwitch to a different plan (prorated)
/store/subscriptions/:id/cancelCancel a subscription
Customer-side endpoints for the Quote module — submit ISG / B2B quote requests, browse the public quote catalogue, and download generated PDFs.
/store/quote-requestsSubmit a quote request with line items + custom fields
/store/quote-requests/:quote_number/pdfDownload the generated quote PDF
/store/quote-requests/isg-configPublic ISG pricing configuration (services, base rates, location modifiers)
/store/quote-servicesList quotable services for the dropdown selector
Public blog content from the page module. Locale-aware, drafts and scheduled posts filtered out automatically.
/store/blog-postsList published posts (locale-aware)
/store/blog-posts/:slugRetrieve post body + sanitized HTML
/store/blog-posts/:slug/commentsList comments on a post
/store/blog-posts/:slug/commentsSubmit a new comment (moderated)
/store/blog-categoriesList categories with post counts
/store/blog-categories/:slugRetrieve a single category and its posts
/store/blog-tagsList tags with post counts
/store/blog-tags/:slugRetrieve a single tag and its posts
/store/blog-authors/:idAuthor profile with their published posts
Static CMS pages with SEO meta. Render-ready HTML body included.
/store/pagesList all published pages
/store/pages/:slugRetrieve a static page by slug
Public form definitions and submission endpoint. Forms are configured in the admin and can be embedded anywhere.
/store/forms/:slugRetrieve a form definition (fields, validation, redirects)
/store/forms/popupRetrieve the active popup form (if any)
/store/form-submissionsSubmit a form (with optional spam token + reCAPTCHA)
Public read-only access to media assets — used by the storefront to render images with metadata.
/store/media/:idRetrieve a single asset by ID (URL, dimensions, alt text)
List subscriptions, unsubscribe flows, and the public mailbox preview endpoint used by the customer portal.
/store/email-subscribeSubscribe an email to a list (with optional double opt-in)
/store/email-unsubscribeUnsubscribe by token (one-click link)
/store/email-unsubscribeConfirm unsubscribe and capture reason
/store/newsletterNewsletter sign-up (homepage / footer widgets)
Email open + click tracking endpoints, plus a generic event ingest. Open tracker returns a 1×1 GIF; click tracker 302-redirects to the destination.
/store/track/open/:campaignId/:subscriberIdPixel-track an email open
/store/track/click/:campaignId/:subscriberIdClick-tracking redirect
/store/track/eventsGeneric analytics event ingest (page_view, add_to_cart, …)
Read-only access to the active theme config, section definitions, and resolved menus — used by the storefront to render dynamic pages.
/store/themeActive theme: tokens, sections, settings
/store/menus/:handleResolved menu items for a handle (main-menu, footer-menu, …)
Brand identity (logo, colors, typography, social links, contact info) used by themes to keep visuals consistent across pages.
/store/brandResolved brand settings for the active store
Available locales for the active store and field-level translation overrides.
/store/localesList enabled locales with default + RTL flag
/store/translationsBulk-fetch translation overrides for a resource type
Live FX rates served to the storefront. Sources include manual overrides, ECB, and Frankfurter (auto-failover).
/store/currency-ratesActive rates per configured currency pair
/store/exchange-ratesRaw exchange-rate snapshot (with `base` query param)
Shopify-style typed custom fields, attachable to products, orders, customers, and any custom resource.
/store/metafields/:resource_type/:resource_idList metafields attached to a specific resource
Active 301 / 302 redirects served to the storefront edge. Used by the storefront middleware to honor migration mappings.
/store/redirectsList all active redirects (source, target, status code)
Public event endpoints — list events, drill into a single event, list available tickets, and look up the customer's registrations.
/store/eventsList published events (locale + region aware)
/store/events/:slugRetrieve a single event with schedule + speakers
/store/events/:slug/ticketsList ticket variants and remaining inventory
/store/events/my-registrationsAuthenticated customer's registered events
Travel module endpoints — list tours, destinations, categories, and submit / read tour reviews.
/store/toursList published tours with filter (destination, duration, price)
/store/tours/:slugRetrieve a single tour with itinerary + departures
/store/tours/:slug/reviewsList approved reviews for a tour
/store/tours/:slug/reviewsSubmit a new review (moderated)
/store/destinationsList travel destinations
/store/destinations/:slugRetrieve a single destination with related tours
/store/tour-categoriesList tour categories
Generic booking endpoint for service-based businesses — appointment, consultation, workshop slots.
/store/service-bookingsList bookable slots for a service
/store/service-bookingsCreate a new booking
Connect powerful AI models — bring your own OpenAI, Gemini, DeepL, or ElevenLabs key, or use pay-as-you-go credits. The assistant ships with 24 capability packs (skills) — store setup, e-commerce editor, theme editor, marketing manager, SEO auditor, image creator, and more. The full skill catalogue is at /ai-skills. Three integration paths: (1) admin-authenticated proxies under /admin/ai/* for in-product AI features, (2) direct nuvi-agent API at /v1/* for server-to-server work (Bearer NUVI_AGENT_API_KEY, never expose to a browser), (3) a real-time streaming variant via SSE for multi-action approval flows.
/admin/ai/chatSingle-turn chat — pass message + sessionId, get a response. Auto-detects intent and runs the right skill.
/admin/ai/chat/streamSSE streaming chat — emits incremental tokens, plus action-plan events that the client must approve or reject before execution
/admin/ai/chat/stream/:streamId/approveApprove a pending multi-action plan (proceeds to execute)
/admin/ai/chat/stream/:streamId/rejectReject a pending plan (skips execution, no side effects)
/admin/ai/skillsList the 24 available skills with category, examples, and icon name
/admin/ai/skills-configPer-store skill enablement (which skills the operator has turned on for this tenant)
/admin/ai/store-contextStore-aware context the assistant uses (catalog size, currencies, locale, configured modules)
/admin/ai/translateOne-shot LLM translation — input string + target locale, returns translated string. Used by the admin's 11-locale i18n pipeline.
/admin/ai/voice/blogGenerate AI voiceover for a blog post (audio URL returned when complete)
/admin/ai/voice/synthesize-chunkSynthesize a single chunk on demand (used during incremental editor playback)
/admin/ai/marketing/social/draftAI drafts a social post (caption + hashtags) from a brief
/admin/ai/marketing/social/publishPublish a draft to a connected social account (Facebook, Instagram, ...)
/admin/ai/marketing/social/scheduleSchedule a draft for future publish
/admin/ai/marketing/metrics/dashboardCross-channel campaign metrics (Google Ads, Meta) — spend, impressions, conversions
/v1/chatDirect nuvi-agent chat — Bearer auth with NUVI_AGENT_API_KEY (server-side only)
/v1/chat/streamSSE stream variant — multi-action approval flow events
/v1/extract-actionsExtract structured actions from natural language (no execution, plan-only)
/v1/skillsList all 24 skills with metadata (id, category, model_tier, icon)
/v1/setup-statusTenant onboarding state — which skills are configured, which need credentials
Outbound event delivery is on the near-term roadmap. Today, subscribe to internal events via the built-in workflow engine. The shape below is the planned signed-payload format — HMAC-SHA256 (header `x-nuvi-signature`).
order.placedFired when a cart converts to an order
order.payment_capturedFired when payment is captured
order.fulfilment_shippedFired when fulfilment ships
customer.createdFired on new customer registration
subscription.renewedFired on each successful renewal cycle
quote.submittedFired when a customer submits a quote request
All errors return JSON with `code`, `message`, and `type`. HTTP status follows convention: 400 for validation, 401 for auth, 403 for permission, 404 for not found, 429 for rate-limit, 5xx for server.
Storefront calls: 60 req/sec per IP. Admin calls: 30 req/sec per token. Soft-fail responses include `Retry-After` and `X-RateLimit-Remaining` headers — back off and retry.
Public POST endpoints (form submissions, blog comments, quote requests, newsletter sign-up) require an anti-spam token issued by the storefront and pass through reCAPTCHA Enterprise. Calls without a valid token return 403. Never expose your admin JWT to client code — keep it server-side and proxy through your own backend.
Get a publishable API key from the dashboard and start integrating in five minutes. Native SDKs for JS, Python, and PHP coming soon — REST works everywhere today.
Social Login
Per-tenant OAuth 2.0 / OpenID Connect for Google, Apple, Facebook, GitHub, and Microsoft. The storefront kicks off the flow by redirecting to `/auth/social/{provider}/start`; the provider returns to `/auth/social/{provider}/callback` and the customer JWT is set on the storefront cookie. Apple uses `response_mode=form_post` (POST callback). State + PKCE are persisted in Redis with a 10-minute TTL.
/store/auth/social/:provider/startBegin an OAuth flow — returns `{ authorization_url }`
/store/auth/social/:provider/callbackExchange code + state → `{ token, customer_id, is_new_link, return_to }`. Set the token as `nuvi_customer_token` cookie on your storefront.
/store/auth/social/apple/callbackApple form_post variant — same response shape, body is `application/x-www-form-urlencoded`
/store/auth/social/linked-accountsList the authenticated customer's connected providers (avatar, email, last_login_at). Requires customer JWT.
/store/auth/social/linked-accounts/:idUnlink a single provider. Linked-account records are scoped per-customer; cross-customer access returns 404.