ConsentStack API

openapi: 3.1.0
info:
  title: ConsentStack API
  version: '2026-11-04'
  description: 'GENERATED FROM DOCUMENTATION by API Evangelist on 2026-11-04: 3 operation(s) read from 2 public documentation page(s) (each operation
    names its page in x-source). This is not the provider''s published contract; ConsentStack has published no machine-readable contract that
    the pipeline could find. Engine: local.'
  x-evidence-tiers:
    code-example: 0
    documentation: 3
    pages-with-code: 0
    pages-read: 2
  x-generated-from: documentation
  x-provenance: generated
  x-authored-by: API Evangelist
  x-generated: '2026-11-04'
  x-generator: generate-contract-from-docs.py
  x-engine: local
  x-sources:
  - https://www.consentstack.io/docs/api-reference
  - https://www.consentstack.io/docs/developers/content-security-policy
servers:
- url: https://origins.consentstack.io
paths:
  /functions/v1/config:
    get:
      operationId: get_functions_v1_config
      tags:
      - Functions
      summary: Returns the published consent configuration for a site, resolved for the visitor's region and language.
      description: 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.
      x-source: https://www.consentstack.io/docs/api-reference
      parameters:
      - name: site_key
        in: query
        required: true
        schema:
          type: string
        description: Your public site key (found in the dashboard under Site Settings).
      - name: region
        in: query
        required: false
        schema:
          type: string
        description: Override automatic geo-detection with a specific region ID (e.g. gdpr , us_state_laws ).
      - name: lang
        in: query
        required: false
        schema:
          type: string
        description: Override automatic language detection with a language code (e.g. de , fr ).
      - name: Origin
        in: header
        required: true
        schema:
          type: string
        description: The requesting domain. Must match a domain registered for this site.
      responses:
        '200':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetFunctionsV1ConfigResponse'
      x-evidence:
        kind: documentation
  /functions/v1/consent:
    post:
      operationId: post_functions_v1_consent
      tags:
      - Functions
      summary: Records a visitor's consent decision.
      description: The server adds several fields before storing the consent log, including hashing the anon_id, parsing User-Agent, detecting
        country, and linking to the published config.
      x-source: https://www.consentstack.io/docs/api-reference
      parameters:
      - name: Origin
        in: header
        required: true
        schema:
          type: string
        description: Must match a registered domain for the site.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostFunctionsV1ConsentRequest'
      responses:
        '201':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostFunctionsV1ConsentResponse'
      x-evidence:
        kind: documentation
  /functions/v1/scripts:
    post:
      operationId: post_functions_v1_scripts
      tags:
      - Functions
      summary: Reports third-party scripts detected on the page.
      description: For each reported script, the server upserts by domain, auto-categorizes known tracker domains, and updates sync status if
        a sync_id is provided.
      x-source: https://www.consentstack.io/docs/api-reference
      parameters:
      - name: sync_id
        in: query
        required: false
        schema:
          type: string
        description: Links this report to a tracker sync session initiated from the dashboard.
      - name: Origin
        in: header
        required: true
        schema:
          type: string
        description: Must match a registered domain for the site.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostFunctionsV1ScriptsRequest'
      responses:
        '201':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostFunctionsV1ScriptsResponse'
      x-evidence:
        kind: documentation
components:
  schemas:
    GetFunctionsV1ConfigResponse:
      type: object
      properties:
        config:
          type: object
          description: The full published config object (appearance, content, categories, regions, consent rules). Falls back to built-in defaults
            if no config is published.
        sdkCategories:
          type: array
          description: Consent categories resolved for the visitor's region. Each entry includes id, name, description, and the applicable consentModel.
        resolvedRegion:
          type: string
          description: The region ID matched from the visitor's location (e.g. gdpr, us_state_laws, default). null if no region matched.
        resolvedLanguage:
          type: string
          description: The language code used for content (e.g. en, de).
        resolvedContent:
          type: object
          description: Banner and preferences UI strings in the resolved language, with consent-model-specific overrides applied.
        resolvedUi:
          type: object
          description: Translated UI labels (e.g. the "Required" badge text).
        showBranding:
          type: boolean
          description: Whether to display ConsentStack branding.
        version:
          type: number
          description: The published config version number.
        site_name:
          type: string
          description: The site name from your dashboard.
        scriptRules:
          type: array
          description: Active script blocking rules. Each entry has a pattern and a category.
    PostFunctionsV1ConsentRequest:
      type: object
      properties:
        site_key:
          type: string
          description: Your public site key.
        anon_id:
          type: string
          description: A client-generated anonymous visitor ID (max 100 chars). Hashed server-side before storage.
        categories:
          type: object
          description: A map of category IDs to booleans representing the visitor's consent choices.
        event_type:
          type: string
          description: One of initial (first interaction), update (changed preferences), or impression (banner was shown).
        event_action:
          type: string
          description: 'The action taken: opt_in, opt_out, partial, or acknowledge.'
        config_version:
          type: number
          description: The config version the visitor saw (for audit trail).
        region:
          type: string
          description: The resolved region ID at the time of consent.
        consent_model:
          type: string
          description: 'The active consent model: opt_in, opt_out, notice, or notice_required.'
        regulation:
          type: string
          description: The regulation that applied (e.g. gdpr, us_state_laws).
        time_to_action_ms:
          type: number
          description: Milliseconds between banner display and visitor action.
        interaction:
          type: string
          description: How the visitor interacted (e.g. accept_all, reject_all, save_preferences).
        preferences_opened:
          type: boolean
          description: Whether the visitor opened the preferences panel before deciding.
        banner_load_time_ms:
          type: number
          description: Milliseconds the banner took to render.
        banner_position:
          type: string
          description: Banner layout position (e.g. bottom-full, center-modal).
        page_url:
          type: string
          description: The page URL where consent was given.
        sdk_version:
          type: string
          description: The SDK version that sent the request.
        language:
          type: string
          description: The visitor's browser language.
        resolved_language:
          type: string
          description: The language the banner was displayed in.
      required:
      - site_key
      - anon_id
      - categories
      - event_type
    PostFunctionsV1ConsentResponse:
      type: object
      properties:
        success:
          type: boolean
          description: Consent log recorded successfully.
    PostFunctionsV1ScriptsRequest:
      type: object
      properties:
        site_key:
          type: string
          description: Your public site key.
        page_url:
          type: string
          description: The page URL where scripts were detected.
        scripts:
          type: array
          description: Array of detected scripts (max 100). Each entry contains src, domain, category, blocked, timestamp, and optional sync_id.
        timestamp:
          type: number
          description: Unix timestamp of the detection.
        sync_id:
          type: string
          description: UUID linking to a dashboard-initiated sync (deprecated in body; use query parameter).
      required:
      - site_key
      - page_url
      - scripts
      - timestamp
    PostFunctionsV1ScriptsResponse:
      type: object
      properties:
        success:
          type: boolean
          description: Scripts processed successfully.
  securitySchemes:
    Site_Key:
      type: apiKey
      in: query
      name: Authorization
      x-source: https://www.consentstack.io/docs/developers/theming-tokens
tags:
- name: Functions
security:
- Site_Key: []