Extole Components 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 Components 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: Components
paths:
  /v1/component-facets:
    get:
      description: Returns component facet (category) definitions for the calling client. Facets group component types into logical categories shown in the campaign editor. Use `GET /v1/component-facets/default` to retrieve the platform-default categories.
      operationId: listComponentFacets
      parameters:
      - in: query
        name: include_archived
        schema:
          type: boolean
      - in: query
        name: limit
        schema:
          format: int32
          type: integer
      - in: query
        name: offset
        schema:
          format: int32
          type: integer
      responses:
        '200':
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/ComponentFacetResponse'
                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 component categories
      tags:
      - Components
      x-extole-bundle: management-expert
      x-extole-visibility: expert
    post:
      description: Creates a new component facet (category) definition and returns the persisted record. Component facets group types shown in the campaign editor.
      operationId: createComponentFacet
      requestBody:
        content:
          application/json:
            example:
              allowed_values:
              - color: color
                description: description
                display_name: display_name
                icon: icon
                value: value
              display_name: display_name
              name: name
            schema:
              $ref: '#/components/schemas/ComponentFacetCreateRequest'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ComponentFacetResponse'
          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_facet_display_name_length_out_of_range:
                  $ref: '#/components/examples/component_facet_display_name_length_out_of_range'
                component_facet_name_already_exists:
                  $ref: '#/components/examples/component_facet_name_already_exists'
                component_facet_name_illegal_character:
                  $ref: '#/components/examples/component_facet_name_illegal_character'
                component_facet_name_is_missing:
                  $ref: '#/components/examples/component_facet_name_is_missing'
                component_facet_name_length_out_of_range:
                  $ref: '#/components/examples/component_facet_name_length_out_of_range'
                component_facet_not_found:
                  $ref: '#/components/examples/component_facet_not_found'
                component_facet_value_color_invalid:
                  $ref: '#/components/examples/component_facet_value_color_invalid'
                component_facet_value_description_illegal_character:
                  $ref: '#/components/examples/component_facet_value_description_illegal_character'
                component_facet_value_description_length_out_of_range:
                  $ref: '#/components/examples/component_facet_value_description_length_out_of_range'
                component_facet_value_display_name_length_out_of_range:
                  $ref: '#/components/examples/component_facet_value_display_name_length_out_of_range'
                component_facet_value_icon_illegal_character:
                  $ref: '#/components/examples/component_facet_value_icon_illegal_character'
                component_facet_value_icon_length_out_of_range:
                  $ref: '#/components/examples/component_facet_value_icon_length_out_of_range'
                component_facet_value_illegal_character:
                  $ref: '#/components/examples/component_facet_value_illegal_character'
                component_facet_value_length_out_of_range:
                  $ref: '#/components/examples/component_facet_value_length_out_of_range'
                component_facet_values_size_out_of_range:
                  $ref: '#/components/examples/component_facet_values_size_out_of_range'
                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'
                facet_associated_with_components:
                  $ref: '#/components/examples/facet_associated_with_components'
                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_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'
                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 component category
      tags:
      - Components
      x-extole-bundle: management-expert
      x-extole-visibility: expert
  /v1/component-facets/default:
    get:
      description: Returns the platform-default component facet (category) definitions. Default facets are provided by Extole and are available to all clients.
      operationId: listDefaultComponentFacets
      responses:
        '200':
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/ComponentFacetResponse'
                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 default component categories
      tags:
      - Components
      x-extole-bundle: management-expert
      x-extole-visibility: expert
  /v1/component-facets/{name}:
    get:
      description: Returns the component facet (category) definition for the supplied name. Returns `400 component_facet_not_found` if the name does not match any accessible facet.
      operationId: getComponentFacet
      parameters:
      - description: Name of the component category to retrieve.
        in: path
        name: name
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ComponentFacetResponse'
          description: Component facet definition that describes a campaign component category and its allowed values.
        '400':
          content:
            application/json:
              examples:
                component_facet_not_found:
                  $ref: '#/components/examples/component_facet_not_found'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Component facet (category) was not found. The supplied name does not match any component facet 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 component category
      tags:
      - Components
      x-extole-bundle: management-expert
      x-extole-visibility: expert
    put:
      description: Applies a partial update to the supplied component facet. Returns `400 component_facet_not_found` if the name does not match any accessible facet.
      operationId: updateComponentFacet
      parameters:
      - description: Name of the component category to update.
        in: path
        name: name
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            example:
              allowed_values:
              - color: color
                description: description
                display_name: display_name
                icon: icon
                value: value
              display_name: display_name
            schema:
              $ref: '#/components/schemas/ComponentFacetUpdateRequest'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ComponentFacetResponse'
          description: Component facet definition that describes a campaign component category and its allowed values.
        '400':
          content:
            application/json:
              examples:
                component_facet_not_found:
                  $ref: '#/components/examples/component_facet_not_found'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Component facet (category) was not found. The supplied name does not match any component facet 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 component category
      tags:
      - Components
      x-extole-bundle: management-expert
      x-extole-visibility: expert
    delete:
      description: Archives the supplied component facet. Fails with `400 facet_associated_with_components` if the facet is still assigned to active components. Remove those associations before archiving. Returns the archived facet.
      operationId: archiveComponentFacet
      parameters:
      - description: Name of the component category to archive.
        in: path
        name: name
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ComponentFacetResponse'
          description: Archived component facet definition.
        '400':
          content:
            application/json:
              examples:
                component_facet_not_found:
                  $ref: '#/components/examples/component_facet_not_found'
                facet_associated_with_components:
                  $ref: '#/components/examples/facet_associated_with_components'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Cannot archive the component facet because it is still associated with one or more components. Remove those associations first.
        '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 component category
      tags:
      - Components
      x-extole-bundle: management-expert
      x-extole-visibility: expert
  /v1/components:
    get:
      description: Returns all components visible to the current client. Components are the reusable building blocks that campaigns assemble — creatives, content blocks, and sub-experiences.
      operationId: listComponents
      parameters:
      - in: query
        name: name
        schema:
          type: string
      - in: query
        name: owner
        schema:
          type: string
      - in: query
        name: state
        schema:
          type: string
      - in: query
        name: version_state
        schema:
          enum:
          - LATEST
          - PUBLISHED
          type: string
      - in: query
        name: campaign_ids
        schema:
          type: string
      - in: query
        name: having_any_tags
        schema:
          type: string
      - in: query
        name: having_all_tags
        schema:
          type: string
      - in: query
        name: exclude_having_any_tags
        schema:
          type: string
      - in: query
        name: exclude_having_all_tags
        schema:
          type: string
      - in: query
        name: having_any_types
        schema:
          type: string
      - in: query
        name: having_all_types
        schema:
          type: string
      - in: query
        name: having_any_settings
        schema:
          type: string
      - in: query
        name: having_all_settings
        schema:
          type: string
      - in: query
        name: target_component_id
        schema:
          type: string
      - in: query
        name: target_setting_name
        schema:
          type: string
      - in: query
        name: target_setting_filter_collection
        schema:
          type: string
      - in: query
        name: target_socket_name
        schema:
          type: string
      - in: query
        name: show_all
        schema:
          type: boolean
      - in: query
        name: include_granted
        schema:
          type: boolean
      - in: query
        name: include_subscribed
        schema:
          type: boolean
      - in: query
        name: limit
        schema:
          format: int32
          type: integer
      - in: query
        name: offset
        schema:
          format: int32
          type: integer
      responses:
        '200':
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/ComponentResponse'
                type: array
          description: Successful response
        '400':
          content:
            application/json:
              examples:
                binding_error:
                  $ref: '#/components/examples/binding_error'
                component_id_not_accessible:
                  $ref: '#/components/examples/component_id_not_accessible'
                component_not_found:
                  $ref: '#/components/examples/component_not_found'
                component_owner_not_supported:
                  $ref: '#/components/examples/component_owner_not_supported'
                component_state_not_supported:
                  $ref: '#/components/examples/component_state_not_supported'
                default_key_not_allowed:
                  $ref: '#/components/examples/default_key_not_allowed'
                display_name_has_illegal_character:
                  $ref: '#/components/examples/display_name_has_illegal_character'
                invalid_json:
                  $ref: '#/components/examples/invalid_json'
                invalid_limit:
                  $ref: '#/components/examples/invalid_limit'
                invalid_offset:
                  $ref: '#/components/examples/invalid_offset'
                invalid_parameter:
                  $ref: '#/components/examples/invalid_parameter'
                invalid_setting_filter:
                  $ref: '#/components/examples/invalid_setting_filter'
                invalid_translatable_value:
                  $ref: '#/components/examples/invalid_translatable_value'
                max_fetch_size_1000:
                  $ref: '#/components/examples/max_fetch_size_1000'
                missing_request_body:
                  $ref: '#/components/examples/missing_request_body'
                multiple_components_installed_into_single_socket:
                  $ref: '#/components/examples/multiple_components_installed_into_single_socket'
                non_translatable_variable_can_not_be_updated:
                  $ref: '#/components/examples/non_translatable_variable_can_not_be_updated'
                reward_supplier_id_list_invalid_configuration:
                  $ref: '#/components/examples/reward_supplier_id_list_invalid_configuration'
                setting_batch_update_missing_request:
                  $ref: '#/components/examples/setting_batch_update_missing_request'
                setting_display_name_length_out_of_range:
                  $ref: '#/components/examples/setting_display_name_length_out_of_range'
                setting_filter_component_facet_name_missing:
                  $ref: '#/components/examples/setting_filter_component_facet_name_missing'
                setting_filter_component_facet_value_missing:
                  $ref: '#/components/examples/setting_filter_component_facet_value_missing'
                setting_filter_component_type_missing:
                  $ref: '#/components/examples/setting_filter_component_type_missing'
                setting_filter_expression_evaluation_failed:
                  $ref: '#/components/examples/setting_filter_expression_evaluation_failed'
                setting_filter_invalid_component_facet:
                  $ref: '#/components/examples/setting_filter_invalid_component_facet'
                setting_filter_invalid_component_type:
                  $ref: '#/components/examples/setting_filter_invalid_component_type'
                setting_name_duplicated:
                  $ref: '#/components/examples/setting_name_duplicated'
                setting_name_length_out_of_range:
                  $ref: '#/components/examples/setting_name_length_out_of_range'
                setting_name_missing:
                  $ref: '#/components/examples/setting_name_missing'
                setting_name_reserved:
                  $ref: '#/components/examples/setting_name_reserved'
                setting_validation_exception:
                  $ref: '#/components/examples/setting_validation_exception'
                socket_missing_required_parameter:
                  $ref: '#/components/examples/socket_missing_required_parameter'
                tag_length_out_of_range:
                  $ref: '#/components/examples/tag_length_out_of_range'
                unavailable_referenced_variable:
                  $ref: '#/components/examples/unavailable_referenced_variable'
                unknown_source_clients:
                  $ref: '#/compo

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