API Reference

ConsentStack exposes three edge-function endpoints that power the consent banner on your site. The SDK calls these automatically — you only need this reference if you are building a custom integration or debugging network requests.

Base URL: https://origins.consentstack.io

All endpoints return JSON and include CORS headers. Every request that references a site must include a valid Origin header matching a domain registered in your dashboard.

GET /functions/v1/config

Returns the published consent configuration for a site, resolved for the visitor's region and language.

GET https://origins.consentstack.io/functions/v1/config?site_key=YOUR_SITE_KEY

Query parameters

Request headers

Response (200)

{
  "config": { ... },
  "sdkCategories": [
    {
      "id": "essential",
      "name": "Essential",
      "description": "Required for the website to function properly.",
      "consentModel": "exempt"
    },
    {
      "id": "analytics",
      "name": "Analytics",
      "description": "Help us understand how visitors interact with our website.",
      "consentModel": "opt_in"
    }
  ],
  "resolvedRegion": "gdpr",
  "resolvedLanguage": "en",
  "resolvedContent": {
    "title": "We value your privacy",
    "description": "...",
    "acceptAllText": "Accept All",
    "rejectAllText": "Reject All",
    "customizeText": "Customize",
    "savePreferencesText": "Save Preferences",
    "closeText": "Close"
  },
  "resolvedUi": {
    "required": "Required"
  },
  "showBranding": true,
  "version": 3,
  "site_name": "My Website",
  "scriptRules": [
    { "pattern": "google-analytics.com", "category": "analytics" }
  ]
}

Response fields

Error responses

Caching

Responses include Cache-Control: private, no-store. Config changes take effect immediately — there is no CDN caching layer between publish and delivery.

Usage cap

Free-tier sites that exceed their monthly active user cap receive a 200 response with {"disabled": true, "reason": "cap_exceeded"} instead of the config payload. The SDK gracefully hides the banner when it receives this response.

POST /functions/v1/consent

Records a visitor's consent decision. The SDK calls this endpoint when a visitor interacts with the banner (accept, reject, customize) and on page load for returning visitors.

POST https://origins.consentstack.io/functions/v1/consent
Content-Type: application/json

Request body

Request headers

Example request

{
  "site_key": "sk_live_abc123",
  "anon_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "categories": {
    "essential": true,
    "analytics": true,
    "marketing": false
  },
  "event_type": "initial",
  "event_action": "partial",
  "config_version": 3,
  "region": "gdpr",
  "consent_model": "opt_in",
  "time_to_action_ms": 4200,
  "interaction": "save_preferences",
  "preferences_opened": true,
  "page_url": "https://example.com/pricing",
  "sdk_version": "0.1.0"
}

Server-side enrichment

The server adds several fields before storing the consent log:

• Visitor ID hashing -- The anon_id is hashed with SHA-256 before storage. The raw ID is never persisted.
• User-Agent parsing -- Browser name, OS, and device type (desktop, mobile, tablet) are extracted from the User-Agent header.
• Country detection -- The visitor's country code is read from infrastructure headers at the network edge.
• Config linkage -- The consent log is linked to the published config ID for a complete audit trail.

Response codes

POST /functions/v1/scripts

Reports third-party scripts detected on the page. The SDK scans the DOM for script elements, extracts their domains, and sends them to this endpoint. The server upserts each script and auto-categorizes known tracker domains.

POST https://origins.consentstack.io/functions/v1/scripts
Content-Type: application/json

Query parameters

Request body

Script entry fields

Example request

{
  "site_key": "sk_live_abc123",
  "page_url": "https://example.com/",
  "scripts": [
    {
      "src": "https://www.google-analytics.com/analytics.js",
      "domain": "google-analytics.com",
      "category": "analytics",
      "blocked": true
    },
    {
      "src": "https://cdn.example.com/widget.js",
      "domain": "cdn.example.com",
      "category": null,
      "blocked": false
    }
  ],
  "timestamp": 1709654400
}

Server-side behavior

For each reported script, the server:

1. Upserts by domain -- If the domain has been seen before for this site, the existing record is updated. New domains are inserted.
2. Auto-categorizes -- Known tracker domains are matched against a built-in database and assigned a category automatically.
3. Updates sync status -- If a sync_id is provided, the corresponding tracker sync record is marked as complete (or failed, if an error was included).

Response codes

Rate limiting

All endpoints are rate-limited at the CDN edge: 20 requests per 10 seconds per IP address (~120 requests/minute). This limit is for abuse prevention and should not affect normal SDK usage.

What's next

• Getting started -- Install the SDK and publish your first config.
• Dashboard guide -- Manage sites, configs, and view consent logs.