Public API Routes

Base path: /consenti/api/v1 (default — set via basePath in createConsenti()). No authentication required.

Static profile file serving (hot path)

The primary way to serve profiles at scale. Locale JSON files are written to disk when a profile is activated in the dashboard. These routes serve them directly from the filesystem — no DB query on the hot path.

GET /profiles/:tenantId/:complianceGroup/:locale

Serves the active locale JSON for a compliance group from ${storage.path}/profiles/${tenantId}/${complianceGroup}/${locale}.json. Returns Cache-Control: public, max-age=3600, stale-while-revalidate=60 — safe for CDN caching.

If the requested locale file does not exist, responds with 303 See Other to .../default, which serves default.json (the defaultLocale content).

// GET /consenti/api/v1/profiles/default/opt-in/en HTTP/1.1

GET /profiles/:tenantId/:profileId/:entryId/:locale

Serves the locale JSON for one version snapshot — used by the dashboard edit-history viewer. These files are written once and never modified. :profileIdis the profile's stable id; :entryId is the version number (from GET /admin/profiles/:id/versions).

// GET /consenti/api/v1/profiles/default/prof-a1b2c3/2/fr-FR HTTP/1.1

Resolve profile

GET /resolve-profile

Used by widgets configured with compliance.type: 'auto'. Call this once on page load to discover which compliance group and locale file the visitor should receive. The widget then fetches that file directly — zero subsequent DB queries.

Geo resolution uses the geoDataProvider configured in createConsenti(). The returned path is always a path on this server (/consenti/api/v1/profiles/...), even when S3 sync is enabled — see the s3Api config docs if you want an external CDN or edge function to serve straight from S3 instead.

// Widget encodes automatically — equivalent manual call:
const data = btoa(JSON.stringify({
  timezone: 'Europe/Paris',
  languages: ['fr-FR', 'fr'],
  language: 'fr-FR',
  locale: 'fr-FR',
}))
fetch(`/consenti/api/v1/resolve-profile?data=${encodeURIComponent(data)}`)

DB-backed profile routes

These routes query the database on each request. Use them for server-side rendering or when you need a fully resolved profile object including the translations map. For high-traffic public-facing widget use, prefer the static file serving routes above.

Both endpoints return the same response shape. The only difference is which locale is resolved: /profiles/:id uses the profile's defaultLocale, while /profiles/:id/:locale uses the requested locale (falling back to defaultLocale if no translation exists).

Response shape

Both endpoints return a fully-resolved profile — banner text, modal copy, and button labels are already merged for the active locale. There is no raw translations map.

GET /profiles/:id

Returns the profile resolved in its defaultLocale. currentLocale will equal defaultLocale.

// GET /consenti/api/v1/profiles/my-profile-id HTTP/1.1

GET /profiles/:id/:locale

Same response shape as /profiles/:id, but currentLocale is set to :locale and all banner/modal strings are resolved for that locale. If the requested locale has no translation, the response falls back to defaultLocale (and currentLocale reflects the requested locale regardless).

// GET /consenti/api/v1/profiles/my-profile-id/fr HTTP/1.1

GET /profiles/auto/:locale Legacy

Legacy geo-resolution route — returns a fully resolved profile object from the database. Prefer GET /resolve-profile (above) for new integrations: it returns a file path so the widget fetches the locale JSON directly from disk or CDN, removing all DB overhead from the hot path.

Geo-resolves the visitor's compliance group from geo signals, finds the active profile tagged to that group, and returns it resolved for :locale. The response includes resolvedComplianceGroup. Falls back to the default profile when no active profile exists for the resolved group.

Requires compliance.type: 'auto' in createConsenti().

// GET /consenti/api/v1/profiles/auto/en?tz=Europe/Paris HTTP/1.1

Consent

Consent records are keyed by visitorId. The visitor ID is persisted in a cookie (consenti_vid) set by the widget after the first submission.

POST /consent

Creates or updates a consent record. If visitorId is omitted, the server generates one and sets it as a cookie in the response.

// POST /consenti/api/v1/consent HTTP/1.1
// Content-Type: application/json

{
  "profileId": "my-profile-id",  // required
  "consentJson": {               // required
    "necessary": "granted",
    "analytics": "granted",
    "marketing": "denied"
  },
  "visitorId": "uuid-v4",        // optional — generated if omitted
  "locale": "en",                // optional — defaults to "en"
  "gpcDetected": false,          // optional — defaults to false
  "source": "banner",            // optional — "banner" | "api" | "import"
  "ageVerified": true,           // optional — set by the widget's age gate, see UI Events
  "parentalConsentToken": "pcon_..." // optional — set when age gate requires parental consent
}

GET /consent/:visitorId

// GET /consenti/api/v1/consent/visitor-uuid HTTP/1.1

PUT /consent/:visitorId

Updates an existing consent record. Only the supplied fields are applied.

// PUT /consenti/api/v1/consent/visitor-uuid HTTP/1.1
// Content-Type: application/json

{
  "consentJson": {          // required
    "necessary": "granted",
    "analytics": "denied",
    "marketing": "denied"
  },
  "locale": "fr",           // optional
  "gpcDetected": true       // optional
}

DELETE /consent/:visitorId

GDPR right-to-erasure. Deletes the consent record, consent history, and visitor record for the given visitor ID. Also expires the consent cookie in the response.

// DELETE /consenti/api/v1/consent/visitor-uuid HTTP/1.1

GET /consent/:visitorId/verify

Checks whether the stored consent record is still valid — i.e. the consent's profileIdstill matches the compliance group's currently active profile id, and the record has not expired. The UI widget calls this on page load to decide whether to re-show the banner.

// GET /consenti/api/v1/consent/visitor-uuid/verify HTTP/1.1

POST /consent/:visitorId/parental-consent-request

Stateless parental-consent hook — issues a token (signed with compliance.dataSigningHash, auto-generated in memory if not set) that a host's own eventBus.on('consent.parentalConsentRequired', ...) listener can use to email/notify the parent. Requires the same visitor-ownership cookie as the other visitor-scoped routes above.

// POST /consenti/api/v1/consent/visitor-uuid/parental-consent-request HTTP/1.1
{ "profileId": "my-profile-id" }

POST /consent/parental-consent-resolve

Recovers visitorId/profileId from a token issued by the route above and emits consent.parentalConsentGranted— your own backend listener decides what "granted" means for stored consent. No visitor-ownership cookie required (recovered from the verified token instead), since this is typically called from the parent's own device.

// POST /consenti/api/v1/consent/parental-consent-resolve HTTP/1.1
{ "token": "pcon_eyJ2aXNpdG9ySWQiOi...ab12cd34..." }