Skip to content
Nudova Docs

API overview

Nudova ships a standard REST API. This reference is generated from the API’s OpenAPI schema — the same contract the code serves — so it stays in sync with your deployment instead of rotting like hand-written prose.

Base URL

Section titled “Base URL”

Every deployment serves the API on its own host:

https://api.your-domain.com/api

api.your-domain.com derives from your DOMAIN (see Store settings & branding). Paths in this reference are relative to that base.

Versioning

Section titled “Versioning”

Endpoints are versioned in the path: the current version is v1 (e.g. /api/v1/commerce/catalog/, /api/auth/v1/login/). A future v2 would be served alongside v1 — the reference is generated per version, so it always matches what’s deployed.

Authentication

Section titled “Authentication”

The API uses JWT bearer tokens.

  1. Log in — POST /auth/v1/login/ with your credentials returns an access and a refresh token.

  2. Call authenticated endpoints — send the access token on each request:

    Authorization: Bearer <access-token>

  3. Refresh — when the access token expires, POST /auth/v1/token/refresh/ with the refresh token returns a new access token.

Public endpoints — the catalog, the storefront config, health, login itself — need no token. Everything else (your orders, your profile) requires the bearer header; without it you get 401.

Two utility endpoints worth knowing

Section titled “Two utility endpoints worth knowing”
Endpoint Purpose
GET /health/ Liveness for Docker / load balancers — {"status":"success"}. Used by the runbooks.
GET /v1/config/ The public, config-as-data storefront config (brand, theme, currency, flags). No secrets.

How this reference stays in sync

Section titled “How this reference stays in sync”

This is generated, not written — so it can’t drift from the code:

  1. The Django API describes itself with drf-yasg, served at /api/v1/swagger.json.
  2. That schema is exported and split by domain into two files the docs consume — src/schemas/commerce.json and src/schemas/platform.json — by scripts/sync-openapi.mjs.
  3. starlight-openapi renders the reference pages from those schemas at build time.

To refresh after an API change — pull the schema from any running deployment (the API serves its own contract), then split and rebuild:

Terminal window
# 1. grab the live contract (uses the app's own drf-yasg schema view):
curl -s https://api.your-domain.com/api/v1/swagger.json -o openapi.json


# 2. split it by domain into the two schemas the docs render:
npm run sync:openapi -- openapi.json          # → src/schemas/{commerce,platform}.json


# 3. re-render:
npm run build

The current reference was generated exactly this way. Maintainers without a live deployment can export it offline from the nudova-core Docker image instead — see the README and scripts/generate-schema.py.