Extole Report Types 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 Report Types 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: Report Types
paths:
  /v6/report-types/{id}/clients:
    get:
      description: 'Returns the ids of every client that currently has access to the supplied report type. Useful for auditing PRIVATE report types whose access list is managed via `PUT /v6/report-types/{id}/clients`. Marked `expert`: most integrators do not need cross-client access lists.'
      operationId: listReportTypeClients
      parameters:
      - description: The Extole unique report type identifier.
        in: path
        name: id
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                items:
                  type: string
                type: array
          description: Client ids that currently have access to the report type.
        '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'
                report_type_has_dependent_types:
                  $ref: '#/components/examples/report_type_has_dependent_types'
                report_type_missing:
                  $ref: '#/components/examples/report_type_missing'
              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
        '404':
          content:
            application/json:
              examples:
                report_type_not_found:
                  $ref: '#/components/examples/report_type_not_found'
          description: Report type was not found. The supplied id does not match any report type accessible to the calling client.
        '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 clients with access to a report type
      tags:
      - Report Types
      x-extole-bundle: management-expert
      x-extole-visibility: expert
    put:
      description: Replaces the set of clients that have access to a PRIVATE report type with the supplied list. The body is the complete new list - clients omitted lose access. Only applicable to PRIVATE report types; other visibilities return `400 report_type_change_clients_invalid`. Marked `expert`.
      operationId: updateReportTypeClients
      parameters:
      - description: The Extole unique report type identifier.
        in: path
        name: id
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            example:
            - value
            schema:
              items:
                type: string
              type: array
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReportTypeResponse'
          description: Report type definition including display metadata, parameters, formats, scopes, visibility, tags, and component references.
        '400':
          content:
            application/json:
              examples:
                report_type_change_clients_invalid:
                  $ref: '#/components/examples/report_type_change_clients_invalid'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Validation failed. The named examples below cover this operation's most common rejections; other 400 causes are auto-derived from the request body - inspect the response `code` field for the specific error.
        '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'
                report_type_display_name_illegal_character:
                  $ref: '#/components/examples/report_type_display_name_illegal_character'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Forbidden
        '404':
          content:
            application/json:
              examples:
                report_type_not_found:
                  $ref: '#/components/examples/report_type_not_found'
          description: Report type was not found. The supplied id does not match any report type accessible to the calling client.
        '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: Replace the report type's client access list
      tags:
      - Report Types
      x-extole-bundle: management-expert
      x-extole-visibility: expert
    delete:
      description: Removes the supplied `client_ids` from the report type's access list. Only applicable to PRIVATE report types; other visibilities return `400 report_type_change_clients_invalid`. Returns the report type after the revoke.
      operationId: deleteReportTypeClients
      parameters:
      - description: The Extole unique report type identifier.
        in: path
        name: id
        required: true
        schema:
          type: string
      - in: query
        name: client_ids
        schema:
          items:
            type: string
          type: array
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReportTypeResponse'
          description: Report type definition including display metadata, parameters, formats, scopes, visibility, tags, and component references.
        '400':
          content:
            application/json:
              examples:
                report_type_change_clients_invalid:
                  $ref: '#/components/examples/report_type_change_clients_invalid'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Validation failed. The named examples below cover this operation's most common rejections; other 400 causes are auto-derived from the request body - inspect the response `code` field for the specific error.
        '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'
                report_type_display_name_illegal_character:
                  $ref: '#/components/examples/report_type_display_name_illegal_character'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Forbidden
        '404':
          content:
            application/json:
              examples:
                report_type_not_found:
                  $ref: '#/components/examples/report_type_not_found'
          description: Report type was not found. The supplied id does not match any report type accessible to the calling client.
        '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: Revoke client access to a report type
      tags:
      - Report Types
      x-extole-bundle: management-expert
      x-extole-visibility: expert
  /v6/report-types:
    post:
      description: 'Creates a new report-type definition (SQL- or CONFIGURED-shaped). Returns the persisted report type with its server-assigned id and any defaulted fields. Marked `expert`: report-type definitions are typically managed by Extole staff.'
      operationId: createReportType
      requestBody:
        content:
          application/json:
            example:
              allowed_scopes:
              - CLIENT_ADMIN
              categories:
              - categorie
              component_ids:
              - component_id
              component_references:
              - component_id: component_id
                socket_names:
                - socket_name
              data_start: '2025-10-24T09:00:00.000Z'
              description: description
              display_name: display_name
              formats:
              - CSV
              parameters:
              - category: category
                default_value: default_value
                description: description
                display_name: display_name
                is_required: true
                name: name
                order: 1
                type: DYNAMIC
                type_name: AUDIENCE_ID
                values:
                - value
              parent_report_type_id: parent_report_type_id
              scopes:
              - CLIENT_ADMIN
              tags:
              - name: name
                type: GLOBAL
              type: CONFIGURED
              visibility: EXTOLE_ONLY
            schema:
              $ref: '#/components/schemas/ReportTypeCreateRequest'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReportTypeResponse'
          description: Report type definition including display metadata, parameters, formats, scopes, visibility, tags, and component references.
        '400':
          content:
            application/json:
              examples:
                report_type_description_too_long:
                  $ref: '#/components/examples/report_type_description_too_long'
                report_type_display_name_too_long:
                  $ref: '#/components/examples/report_type_display_name_too_long'
                report_type_empty_parameter_name:
                  $ref: '#/components/examples/report_type_empty_parameter_name'
                report_type_empty_tag_name:
                  $ref: '#/components/examples/report_type_empty_tag_name'
                report_type_invalid_description_link:
                  $ref: '#/components/examples/report_type_invalid_description_link'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Validation failed. The named examples below cover this operation's most common rejections; other 400 causes are auto-derived from the request body - inspect the response `code` field for the specific error.
        '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'
                report_type_display_name_illegal_character:
                  $ref: '#/components/examples/report_type_display_name_illegal_character'
              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 report type
      tags:
      - Report Types
      x-extole-bundle: management-expert
      x-extole-visibility: expert
    get:
      description: Returns the report types visible to the calling client, filtered and ordered by the supplied query parameters. Supports paging via `limit` / `offset` and ordering via `order_by` / `order`. Use this to populate report-builder pickers and to discover the available `parameters`, `formats`, and `scopes` for each report type.
      operationId: listReportTypes
      parameters:
      - in: query
        name: report_type_id
        schema:
          type: string
      - in: query
        name: display_name
        schema:
          type: string
      - in: query
        name: description
        schema:
          type: string
      - in: query
        name: visibility
        schema:
          enum:
          - EXTOLE_ONLY
          - PRIVATE
          - PUBLIC
          type: string
      - in: query
        name: tags
        schema:
          type: string
      - in: query
        name: exclude_tags
        schema:
          type: string
      - in: query
        name: search_query
        schema:
          type: string
      - in: query
        name: limit
        schema:
          format: int32
          type: integer
      - in: query
        name: offset
        schema:
          format: int32
          type: integer
      - in: query
        name: order_by
        schema:
          enum:
          - DISPLAY_NAME
          - ID
          - TYPE
          - VISIBILITY
          type: string
      - in: query
        name: order
        schema:
          enum:
          - ASCENDING
          - DESCENDING
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/ReportTypeResponse'
                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_limit:
                  $ref: '#/components/examples/invalid_limit'
                invalid_offset:
                  $ref: '#/components/examples/invalid_offset'
                invalid_parameter:
                  $ref: '#/components/examples/invalid_parameter'
                max_fetch_size_1000:
                  $ref: '#/components/examples/max_fetch_size_1000'
                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 report types
      tags:
      - Report Types
      x-extole-bundle: management
      x-extole-visibility: visible
  /v6/report-types/{id}/parameters-add:
    put:
      description: Appends the supplied dynamic parameters to the report type's `parameters` list. Static parameters cannot be added via this endpoint - use `createReportType` or `updateReportType` to configure those. Returns the report type after the update.
      operationId: addReportTypeParameters
      parameters:
      - description: The Extole unique report type identifier.
        in: path
        name: id
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            example:
            - category: category
              default_value: default_value
              description: description
              display_name: display_name
              is_required: true
              name: name
              order: 1
              type: DYNAMIC
              type_name: AUDIENCE_ID
              values:
              - value
            schema:
              items:
                $ref: '#/components/schemas/DynamicReportTypeParameterDetailsRequest'
              type: array
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReportTypeResponse'
          description: Report type definition including display metadata, parameters, formats, scopes, visibility, tags, and component references.
        '400':
          content:
            application/json:
              examples:
                report_type_empty_parameter_name:
                  $ref: '#/components/examples/report_type_empty_parameter_name'
                report_type_parameter_description_too_long:
                  $ref: '#/components/examples/report_type_parameter_description_too_long'
                report_type_parameter_static_add:
                  $ref: '#/components/examples/report_type_parameter_static_add'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Validation failed. The named examples below cover this operation's most common rejections; other 400 causes are auto-derived from the request body - inspect the response `code` field for the specific error.
        '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'
                report_type_display_name_illegal_character:
                  $ref: '#/components/examples/report_type_display_name_illegal_character'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Forbidden
        '404':
          content:
            application/json:
              examples:
                report_type_not_found:
                  $ref: '#/components/examples/report_type_not_found'
          description: Report type was not found. The supplied id does not match any report type accessible to the calling client.
        '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: Add dynamic parameters to a report type
      tags:
      - Report Types
      x-extole-bundle: management-expert
      x-extole-visibility: expert
  /v6/report-types/{id}/parameters-delete:
    put:
      description: Removes the supplied parameters (by name) from the report type's `parameters` list. Static parameters cannot be deleted via this endpoint - they are part of the report type's contract and changing them requires a `updateReportType` call. Returns the report type after the update.
      operationId: deleteReportTypeParameters
      parameters:
      - description: The Extole unique report type identifier.
        in: path
        name: id
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            example:
            - value
            schema:
              items:
                type: string
              type: array
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReportTypeResponse'
          description: Report type definition including display metadata, parameters, formats, scopes, visibility, tags, and component references.
        '400':
          content:
            application/json:
              examples:
                report_type_parameter_static_delete:
                  $ref: '#/components/examples/report_type_parameter_static_delete'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Validation failed. The named examples below cover this operation's most common rejections; other 400 causes are auto-derived from the request body - inspect the response `code` field for the specific error.
        '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'
                report_type_display_name_illegal_character:
                  $ref: '#/components/examples/report_type_display_name_illegal_character'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Forbidden
        '404':
          content:
            application/json:
              examples:
                report_type_not_found:
                  $ref: '#/components/examples/report_type_not_found'
          description: Report type was not found. The supplied id does not match any report type accessible to the calling client.
        '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: Remove dynamic parameters from a report type
      tags:
      - Report Types
      x-extole-bundle: management-expert
      x-extole-visibility: expert
  /v6/report-types/{id}/tags-add:
    put:
      description: Appends the supplied tags to the report type's tag list. Existing tags are left unchanged; duplicates in the body are ignored. Returns the report type after the update.
      operationId: addReportTypeTags
      parameters:
      - description: The Extole unique report type identifier.
        in: path
        name: id
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            example:
            - value
            schema:
              items:
                type: string
              type: array
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReportTypeResponse'
          description: Report type definition including display metadata, parameters, formats, scopes, visibility, tags, and component references.
        '400':
          content:
            application/json:
              examples:
                report_type_empty_tag_name:
                  $ref: '#/components/examples/report_type_empty_tag_name'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Validation failed. The named examples below cover this operation's most common rejections; other 400 causes are auto-derived from the request body - inspect the response `code` field for the specific error.
        '401':
          content:
            application/json:
              examples:
                method_unauthorized:
                  $ref: '#/components/examples/method_unauthorized'
              schema:
                $ref: '#/components/schemas/R

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