Extole Event Prehandlers API

openapi: 3.0.1
info:
  description: 'Consumer-to-Extole integration endpoints: consumer event submission, zone rendering, profile management, and SDK-backing operations for browser and native app environments.'
  title: Integration API - Consumer to Extole Audiences Event Prehandlers API
  version: '1.0'
servers:
- description: Production
  url: https://{brand}.extole.io
  variables:
    brand:
      default: yourcompany
      description: Your Extole client subdomain (e.g. 'mycompany' for mycompany.extole.io)
security:
- HEADER: []
- QUERY: []
- COOKIE: []
tags:
- name: Event Prehandlers
paths:
  /v6/prehandlers:
    get:
      description: Returns all prehandlers for the client, sorted by their execution order. Prehandlers are pre-processing hooks that run before the main event-processing pipeline. Each entry includes its script, conditions, and current state (active or archived). Use `GET /v6/prehandlers/built` to retrieve the evaluated runtime version.
      operationId: listPrehandlers
      parameters:
      - in: query
        name: tags
        schema:
          items:
            type: string
          type: array
          uniqueItems: true
      - in: query
        name: limit
        schema:
          format: int32
          type: integer
      - in: query
        name: offset
        schema:
          format: int32
          type: integer
      - in: query
        name: include_archived
        schema:
          type: boolean
      responses:
        '200':
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/PrehandlerResponse'
                type: array
          description: Successful response
        '400':
          content:
            application/json:
              examples:
                binding_error:
                  $ref: '#/components/examples/binding_error'
                invalid_json:
                  $ref: '#/components/examples/invalid_json'
                invalid_parameter:
                  $ref: '#/components/examples/invalid_parameter'
                missing_request_body:
                  $ref: '#/components/examples/missing_request_body'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Bad Request
        '401':
          content:
            application/json:
              examples:
                method_unauthorized:
                  $ref: '#/components/examples/method_unauthorized'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Unauthorized
        '402':
          content:
            application/json:
              examples:
                payment_required:
                  $ref: '#/components/examples/payment_required'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Payment Required
        '403':
          content:
            application/json:
              examples:
                access_denied:
                  $ref: '#/components/examples/access_denied'
                method_unauthorized:
                  $ref: '#/components/examples/method_unauthorized'
                missing_access_token:
                  $ref: '#/components/examples/missing_access_token'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Forbidden
        '415':
          content:
            application/json:
              examples:
                unsupported_media_type:
                  $ref: '#/components/examples/unsupported_media_type'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Unsupported Media Type
        '429':
          content:
            application/json:
              examples:
                too_many_requests:
                  $ref: '#/components/examples/too_many_requests'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Too Many Requests
      summary: List prehandlers
      tags:
      - Event Prehandlers
      x-extole-bundle: management-expert
      x-extole-visibility: expert
    post:
      description: Creates a new prehandler definition and appends it to the end of the execution order. Returns the persisted prehandler with its server-assigned id. The prehandler is created in an active state; archive it with `POST /v6/prehandlers/{id}/archive` to disable it without deleting it.
      operationId: createPrehandler
      requestBody:
        content:
          application/json:
            example:
              actions:
              - expression: {}
                type: EXPRESSION
              component_ids:
              - component_id
              component_references:
              - component_id: component_id
                socket_names:
                - socket_name
              conditions:
              - considered_block_list_types:
                - CIDR
                type: BLOCK_MATCH
              description: description
              enabled: false
              name: name
              order: 0
              tags:
              - tag
            schema:
              $ref: '#/components/schemas/PrehandlerCreateRequest'
        description: PrehandlerCreateRequest object
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PrehandlerResponse'
          description: Successful response
        '400':
          content:
            application/json:
              examples:
                binding_error:
                  $ref: '#/components/examples/binding_error'
                campaign_component_absolute_name_missing:
                  $ref: '#/components/examples/campaign_component_absolute_name_missing'
                campaign_component_description_out_of_range:
                  $ref: '#/components/examples/campaign_component_description_out_of_range'
                campaign_component_display_name_contains_illegal_character:
                  $ref: '#/components/examples/campaign_component_display_name_contains_illegal_character'
                campaign_component_display_name_out_of_range:
                  $ref: '#/components/examples/campaign_component_display_name_out_of_range'
                campaign_component_id_missing:
                  $ref: '#/components/examples/campaign_component_id_missing'
                campaign_component_name_already_in_use:
                  $ref: '#/components/examples/campaign_component_name_already_in_use'
                campaign_component_name_contains_illegal_character:
                  $ref: '#/components/examples/campaign_component_name_contains_illegal_character'
                campaign_component_name_out_of_range:
                  $ref: '#/components/examples/campaign_component_name_out_of_range'
                campaign_component_type_validation_failed:
                  $ref: '#/components/examples/campaign_component_type_validation_failed'
                circular_component_reference:
                  $ref: '#/components/examples/circular_component_reference'
                component_facets_not_found:
                  $ref: '#/components/examples/component_facets_not_found'
                excessive_component_reference:
                  $ref: '#/components/examples/excessive_component_reference'
                external_element_is_referenced_by_active_configuration:
                  $ref: '#/components/examples/external_element_is_referenced_by_active_configuration'
                external_elements_cannot_have_multiple_references:
                  $ref: '#/components/examples/external_elements_cannot_have_multiple_references'
                invalid_component_installed_into_socket:
                  $ref: '#/components/examples/invalid_component_installed_into_socket'
                invalid_component_reference:
                  $ref: '#/components/examples/invalid_component_reference'
                invalid_component_reference_socket_name:
                  $ref: '#/components/examples/invalid_component_reference_socket_name'
                invalid_external_component_reference:
                  $ref: '#/components/examples/invalid_external_component_reference'
                invalid_json:
                  $ref: '#/components/examples/invalid_json'
                invalid_null:
                  $ref: '#/components/examples/invalid_null'
                invalid_parameter:
                  $ref: '#/components/examples/invalid_parameter'
                missing_request_body:
                  $ref: '#/components/examples/missing_request_body'
                orphan_external_component_reference:
                  $ref: '#/components/examples/orphan_external_component_reference'
                prehandler_build_failed:
                  $ref: '#/components/examples/prehandler_build_failed'
                prehandler_description_length_out_of_range:
                  $ref: '#/components/examples/prehandler_description_length_out_of_range'
                prehandler_name_contains_illegal_character:
                  $ref: '#/components/examples/prehandler_name_contains_illegal_character'
                prehandler_name_duplicated:
                  $ref: '#/components/examples/prehandler_name_duplicated'
                prehandler_name_length_out_of_range:
                  $ref: '#/components/examples/prehandler_name_length_out_of_range'
                prehandler_name_missing:
                  $ref: '#/components/examples/prehandler_name_missing'
                prehandler_tag_invalid:
                  $ref: '#/components/examples/prehandler_tag_invalid'
                redundant_component_reference:
                  $ref: '#/components/examples/redundant_component_reference'
                self_component_reference:
                  $ref: '#/components/examples/self_component_reference'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Bad Request
        '401':
          content:
            application/json:
              examples:
                method_unauthorized:
                  $ref: '#/components/examples/method_unauthorized'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Unauthorized
        '402':
          content:
            application/json:
              examples:
                payment_required:
                  $ref: '#/components/examples/payment_required'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Payment Required
        '403':
          content:
            application/json:
              examples:
                access_denied:
                  $ref: '#/components/examples/access_denied'
                method_unauthorized:
                  $ref: '#/components/examples/method_unauthorized'
                missing_access_token:
                  $ref: '#/components/examples/missing_access_token'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Forbidden
        '415':
          content:
            application/json:
              examples:
                unsupported_media_type:
                  $ref: '#/components/examples/unsupported_media_type'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Unsupported Media Type
        '429':
          content:
            application/json:
              examples:
                too_many_requests:
                  $ref: '#/components/examples/too_many_requests'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Too Many Requests
      summary: Create a prehandler
      tags:
      - Event Prehandlers
      x-extole-bundle: management-expert
      x-extole-visibility: expert
  /v6/prehandlers/built:
    get:
      description: Returns all prehandlers in their fully evaluated (built) runtime form, sorted by execution order. Built prehandlers have all evaluatable fields resolved and reflect the current live state of the pipeline. Use this when you need the effective script and condition values rather than the source definitions.
      operationId: listBuiltPrehandlers
      parameters:
      - in: query
        name: tags
        schema:
          items:
            type: string
          type: array
          uniqueItems: true
      - in: query
        name: limit
        schema:
          format: int32
          type: integer
      - in: query
        name: offset
        schema:
          format: int32
          type: integer
      - in: query
        name: include_archived
        schema:
          type: boolean
      responses:
        '200':
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/BuiltPrehandlerResponse'
                type: array
          description: Successful response
        '400':
          content:
            application/json:
              examples:
                binding_error:
                  $ref: '#/components/examples/binding_error'
                invalid_json:
                  $ref: '#/components/examples/invalid_json'
                invalid_parameter:
                  $ref: '#/components/examples/invalid_parameter'
                missing_request_body:
                  $ref: '#/components/examples/missing_request_body'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Bad Request
        '401':
          content:
            application/json:
              examples:
                method_unauthorized:
                  $ref: '#/components/examples/method_unauthorized'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Unauthorized
        '402':
          content:
            application/json:
              examples:
                payment_required:
                  $ref: '#/components/examples/payment_required'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Payment Required
        '403':
          content:
            application/json:
              examples:
                access_denied:
                  $ref: '#/components/examples/access_denied'
                method_unauthorized:
                  $ref: '#/components/examples/method_unauthorized'
                missing_access_token:
                  $ref: '#/components/examples/missing_access_token'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Forbidden
        '415':
          content:
            application/json:
              examples:
                unsupported_media_type:
                  $ref: '#/components/examples/unsupported_media_type'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Unsupported Media Type
        '429':
          content:
            application/json:
              examples:
                too_many_requests:
                  $ref: '#/components/examples/too_many_requests'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Too Many Requests
      summary: List built prehandlers
      tags:
      - Event Prehandlers
      x-extole-bundle: management-expert
      x-extole-visibility: expert
  /v6/prehandlers/{prehandlerId}:
    get:
      description: Returns the source definition of the supplied prehandler, including its script, conditions, and lifecycle state. Returns `400 prehandler_not_found` if the id does not exist or is not accessible to the calling client.
      operationId: getPrehandler
      parameters:
      - description: The id of the prehandler to be retrieved.
        in: path
        name: prehandlerId
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PrehandlerResponse'
          description: Prehandler source definition with build-time fields, conditions, actions, execution order, and component references.
        '400':
          content:
            application/json:
              examples:
                prehandler_not_found:
                  $ref: '#/components/examples/prehandler_not_found'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Prehandler was not found. The supplied id does not match any prehandler accessible to the calling client.
        '401':
          content:
            application/json:
              examples:
                method_unauthorized:
                  $ref: '#/components/examples/method_unauthorized'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Unauthorized
        '402':
          content:
            application/json:
              examples:
                payment_required:
                  $ref: '#/components/examples/payment_required'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Payment Required
        '403':
          content:
            application/json:
              examples:
                access_denied:
                  $ref: '#/components/examples/access_denied'
                method_unauthorized:
                  $ref: '#/components/examples/method_unauthorized'
                missing_access_token:
                  $ref: '#/components/examples/missing_access_token'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Forbidden
        '415':
          content:
            application/json:
              examples:
                unsupported_media_type:
                  $ref: '#/components/examples/unsupported_media_type'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Unsupported Media Type
        '429':
          content:
            application/json:
              examples:
                too_many_requests:
                  $ref: '#/components/examples/too_many_requests'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Too Many Requests
      summary: Get a prehandler
      tags:
      - Event Prehandlers
      x-extole-bundle: management-expert
      x-extole-visibility: expert
    put:
      description: Applies a partial update to the supplied prehandler. Only the fields present in the body are changed; omitted fields are left intact. Returns the persisted prehandler after the update. Returns `400 prehandler_not_found` if the id does not exist.
      operationId: updatePrehandler
      parameters:
      - description: The id of the prehandler to be updated.
        in: path
        name: prehandlerId
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            example:
              actions:
              - expression: {}
                type: EXPRESSION
              component_ids:
              - component_id
              component_references:
              - component_id: component_id
                socket_names:
                - socket_name
              conditions:
              - considered_block_list_types:
                - CIDR
                type: BLOCK_MATCH
              description: description
              enabled: true
              name: name
              order: 1
              tags:
              - tag
            schema:
              $ref: '#/components/schemas/PrehandlerUpdateRequest'
        description: PrehandlerUpdateRequest object
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PrehandlerResponse'
          description: Prehandler source definition with build-time fields, conditions, actions, execution order, and component references.
        '400':
          content:
            application/json:
              examples:
                prehandler_not_found:
                  $ref: '#/components/examples/prehandler_not_found'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Prehandler was not found. The supplied id does not match any prehandler accessible to the calling client.
        '401':
          content:
            application/json:
              examples:
                method_unauthorized:
                  $ref: '#/components/examples/method_unauthorized'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Unauthorized
        '402':
          content:
            application/json:
              examples:
                payment_required:
                  $ref: '#/components/examples/payment_required'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Payment Required
        '403':
          content:
            application/json:
              examples:
                access_denied:
                  $ref: '#/components/examples/access_denied'
                method_unauthorized:
                  $ref: '#/components/examples/method_unauthorized'
                missing_access_token:
                  $ref: '#/components/examples/missing_access_token'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Forbidden
        '415':
          content:
            application/json:
              examples:
                unsupported_media_type:
                  $ref: '#/components/examples/unsupported_media_type'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Unsupported Media Type
        '429':
          content:
            application/json:
              examples:
                too_many_requests:
                  $ref: '#/components/examples/too_many_requests'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Too Many Requests
      summary: Update a prehandler
      tags:
      - Event Prehandlers
      x-extole-bundle: management-expert
      x-extole-visibility: expert
    delete:
      description: Permanently deletes the supplied prehandler from the pipeline. Unlike archiving, deletion is irreversible. Returns the deleted prehandler record on success. Returns `400 prehandler_not_found` if the id does not exist.
      operationId: deletePrehandler
      parameters:
      - description: The id of the prehandler to be deleted.
        in: path
        name: prehandlerId
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PrehandlerResponse'
          description: Deleted prehandler source definition.
        '400':
          content:
            application/json:
              examples:
                prehandler_not_found:
                  $ref: '#/components/examples/prehandler_not_found'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Prehandler was not found. The supplied id does not match any prehandler accessible to the calling client.
        '401':
          content:
            application/json:
              examples:
                method_unauthorized:
                  $ref: '#/components/examples/method_unauthorized'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Unauthorized
        '402':
          content:
            application/json:
              examples:
                payment_required:
                  $ref: '#/components/examples/payment_required'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Payment Required
        '403':
          content:
            application/json:
              examples:
                access_denied:
                  $ref: '#/components/examples/access_denied'
                method_unauthorized:
                  $ref: '#/components/examples/method_unauthorized'
                missing_access_token:
                  $ref: '#/components/examples/missing_access_token'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Forbidden
        '415':
          content:
            application/json:
              examples:
                unsupported_media_type:
                  $ref: '#/components/examples/unsupported_media_type'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Unsupported Media Type
        '429':
          content:
            application/json:
              examples:
                too_many_requests:
                  $ref: '#/components/examples/too_many_requests'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Too Many Requests
      summary: Delete a prehandler
      tags:
      - Event Prehandlers
      x-extole-bundle: management-expert
      x-extole-visibility: expert
  /v6/prehandlers/{prehandlerId}/built:
    get:
      description: Returns the fully evaluated (built) runtime form of the supplied prehandler, with all evaluatable fields resolved. Returns `400 prehandler_not_found` if the id does not exist or is not accessible.
      operationId: getBuiltPrehandler
      parameters:
      - description: The id of the prehandler to be retrieved.
        in: path
        name: prehandlerId
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BuiltPrehandlerResponse'
          description: Built prehandler with evaluated runtime values used by the event-processing pipeline.
        '400':
          content:
            application/json:
              examples:
                prehandler_not_found:
                  $ref: '#/components/examples/prehandler_not_found'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Prehandler was not found. The supplied id does not match any prehandler accessible to the calling client.
        '401':
          content:
            application/json:
              examples:
                method_unauthorized:
                  $ref: '#/components/examples/method_unauthorized'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Unauthorized
        '402':
          content:
            application/json:
              examples:
                payment_required:
                  $ref: '#/components/examples/payment_required'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Payment Required
        '403':
          content:
            application/json:
              examples:
                access_denied:
                  $ref: '#/components/examples/access_denied'
                method_unauthorized:
                  $ref: '#/components/examples/method_unauthorized'
                missing_access_token:
                  $ref: '#/components/examples/missing_access_token'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Forbidden
        '415':
          content:
            application/json:
              examples:
                unsupported_media_type:
                  $ref: '#/components/examples/unsupported_media_type'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Unsupported Media Type
        '429':
          content:
            application/json:
              examples:
                too_many_requests:
                  $ref: '#/components/examples/too_many_requests'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Too Many Requests
      summary: Get a built prehandler
      tags:
      - Event Prehandlers
      x-extole-bundle: management-expert
      x-extole-visibility: expert
  /v6/prehandlers/{prehandlerId}/archive:
    post:
      description: Archives (soft-deletes) the supplied prehandler. The prehandler is removed from the execution pipeline immediately but its definition is retained. Restore it with `POST /v6/prehandlers/{id}/unarchive`. Returns the updated prehandler.
      operationId: archivePrehandler
      parameters:
      - description: The id of the prehandler to be archived.
        in: path
        name: prehandlerId
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PrehandlerResponse'
          description: Archived prehandler source definition.
        '400':
          content:
            application/json:
              examples:
                prehandler_not_found:
                  $ref: '#/components/examples/prehandler_not_found'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Prehandler was not found. The supplied id does not match any prehandler accessible to the calling client.
        '401':
          content:
            application/json:
              examples:
                method_unauthorized:
                  $ref: '#/components/examples/method_unauthorized'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Unauthorized
        '402':
          content:
            application/json:
              examples:
                payment_required:
                  $ref: '#/components/examples/payment_required'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Payment Required
        '403':
          content:
            application/json:
              examples:
                access_denied:
                  $ref: '#/components/examples/access_denied'
                method_unauthorized:
                  $ref: '#/components/examples/method_unauthorized'
                missing_access_token:
                  $ref: '#/components/examples/missing_access_token'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Forbidden
        '415':
          content:
            application/json:
              examples:
                unsupported_media_type:
                  $ref: '#/components/examples/unsupported_media_type'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Unsupported Media Type
        '429':
          content:
            application/json:
              examples:
                too_many_requests:
                  $ref: '#/components/examples/too_many_requests'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Too Many Requests
      summary: Archive a prehandler
      tags:
      - Event Prehandlers
      x-extole-bundle: management-expert
      x-extole-visibility: expert
  /v6/prehandlers/{prehandlerId}/unarchive:
    post:
      description: Restores a previously archived prehandler and re-inserts it into the execution pipeline. Returns the restored prehandler. Returns `400 prehandler_not_found` if the id does not exist.
      operationId: unarchivePrehandler
      parameters:
      - description: The id of the prehandler to be unarchived.
        in: path
        name: prehandlerId
        required: t

# --- truncated at 32 KB (105 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/extole/refs/heads/main/openapi/extole-event-prehandlers-api-openapi.yml