BlueConic Timeline Event Types API

openapi: 3.2.0
info:
  title: BlueConic REST API v2 Timeline Event Types API
  description: Welcome to the BlueConic REST API v2.
  termsOfService: https://www.blueconic.com/blueconic-terms-and-conditions
  contact:
    name: Contact us
    url: https://support.blueconic.com/hc/en-us/requests/new
  license:
    name: BlueConic
    url: https://github.com/blueconic/openapi/blob/main/LICENSE.MD
  version: '100.0'
servers:
- url: https://{blueconicHostname}/rest/v2
  description: The BlueConic server
  variables:
    blueconicHostname:
      description: BlueConic server hostname, e.g. 'tenant.blueconic.net'
      default: tenantname
tags:
- name: Timeline Event Types
  description: Timeline events store time-based data on events that occur for a profile, such as product orders or page views. In BlueConic, a Timeline event type defines how events are stored in a profile. For example, a Timeline event type for product orders might define event details such as the date, time, price, item URL, and item SKU. The following methods allow you to retrieve timeline event types. Read more
paths:
  /timelineEventTypes/{timelineEventType}:
    get:
      tags:
      - Timeline Event Types
      summary: Get one timeline event type
      description: Retrieves a single timeline event type.
      operationId: getOneTimelineEventType
      parameters:
      - name: timelineEventType
        in: path
        description: The ID of the timeline event type.
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Returns the timeline event type.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/timelineEventTypes'
              examples:
                Response body:
                  description: Response body
                  value: "{\n  \"creationDate\": \"2025-09-22T10:10:56.412Z\",\n  \"description\": \"This is an example event with nested properties that is used in example notebook.\",\n  \"fieldTypes\": [\n    {\n      \"dataSensitivity\": \"NON_PII\",\n      \"key\": \"total_value\",\n      \"value\": \"DECIMAL\"\n    },\n    {\n      \"key\": \"product\",\n      \"value\": [\n        {\n          \"dataSensitivity\": \"NON_PII\",\n          \"key\": \"quantity\",\n          \"value\": \"NUMBER\"\n        },\n        {\n          \"dataSensitivity\": \"NON_PII\",\n          \"key\": \"netprice\",\n          \"value\": \"DECIMAL\"\n        },\n        {\n          \"dataSensitivity\": \"NON_PII\",\n          \"key\": \"name\",\n          \"multiple\": false,\n          \"value\": \"TEXT\"\n        },\n        {\n          \"dataSensitivity\": \"NON_PII\",\n          \"key\": \"variant\",\n          \"multiple\": false,\n          \"value\": \"TEXT\"\n        },\n        {\n          \"dataSensitivity\": \"NON_PII\",\n          \"key\": \"id\",\n          \"multiple\": false,\n          \"value\": \"TEXT\"\n        }\n      ]\n    },\n    {\n      \"dataSensitivity\": \"NON_PII\",\n      \"key\": \"last_modified\",\n      \"value\": \"DATETIME\"\n    }\n  ],\n  \"id\": \"nested_event_example\",\n  \"lastModifiedDate\": \"2025-09-22T10:11:27.331Z\",\n  \"name\": \"Event type with nested item example\",\n  \"priority\": \"LOW\",\n  \"source\": \"PLUGIN\",\n  \"tags\": []\n}"
        '401':
          description: Authentication failed (unauthorized).
        '403':
          description: Authorization failed (incorrect permissions).
        '404':
          description: The timeline event type doesn't exist.
        '503':
          description: The server is too busy to handle the request.
      security:
      - oauth2:
        - read:timeline-event-types
  /timelineEventTypes:
    get:
      tags:
      - Timeline Event Types
      summary: Retrieves all timeline event types
      description: Retrieves all timeline event types.
      operationId: getTimelineEventTypes
      parameters:
      - name: startIndex
        in: query
        description: Specifies the index of the first item to include in the result.
        schema:
          type: integer
          format: int64
          default: 0
          example: 0
      - name: count
        in: query
        description: Specifies the number of results to return.
        schema:
          type: integer
          format: int64
          default: 20
          example: 10
      responses:
        '200':
          description: Returns the timeline event types.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/timelineEventType'
              examples:
                Response body:
                  description: Response body
                  value: "{\n  \"itemsPerPage\": 10,\n  \"startIndex\": 0,\n  \"timelineEventTypes\": [\n    {\n      \"creationDate\": \"2025-09-22T10:10:56.412Z\",\n      \"description\": \"This is an example event with nested properties that is used in example notebook.\",\n      \"fieldTypes\": [\n        {\n          \"dataSensitivity\": \"NON_PII\",\n          \"key\": \"total_value\",\n          \"value\": \"DECIMAL\"\n        },\n        {\n          \"key\": \"product\",\n          \"value\": [\n            {\n              \"dataSensitivity\": \"NON_PII\",\n              \"key\": \"quantity\",\n              \"value\": \"NUMBER\"\n            },\n            {\n              \"dataSensitivity\": \"NON_PII\",\n              \"key\": \"netprice\",\n              \"value\": \"DECIMAL\"\n            },\n            {\n              \"dataSensitivity\": \"NON_PII\",\n              \"key\": \"name\",\n              \"multiple\": false,\n              \"value\": \"TEXT\"\n            },\n            {\n              \"dataSensitivity\": \"NON_PII\",\n              \"key\": \"variant\",\n              \"multiple\": false,\n              \"value\": \"TEXT\"\n            },\n            {\n              \"dataSensitivity\": \"NON_PII\",\n              \"key\": \"id\",\n              \"multiple\": false,\n              \"value\": \"TEXT\"\n            }\n          ]\n        },\n        {\n          \"dataSensitivity\": \"NON_PII\",\n          \"key\": \"last_modified\",\n          \"value\": \"DATETIME\"\n        }\n      ],\n      \"id\": \"nested_event_example\",\n      \"lastModifiedDate\": \"2025-09-22T10:11:27.331Z\",\n      \"name\": \"Event type with nested item example\",\n      \"priority\": \"LOW\",\n      \"source\": \"PLUGIN\",\n      \"tags\": []\n    }\n  ],\n  \"totalPages\": 1,\n  \"totalResults\": 1\n}"
        '401':
          description: Authentication failed (unauthorized).
        '403':
          description: Authorization failed (incorrect permissions).
        '503':
          description: The server is too busy to handle the request.
      security:
      - oauth2:
        - read:timeline-event-types
components:
  schemas:
    FieldTypeBean:
      type: object
      description: A field type of a timeline event type.
      properties:
        dataSensitivity:
          type: string
          description: The data sensitivity of the field.
          enum:
          - NON_PII
          - PII
        description:
          type: string
          description: The description of the field.
        identifier:
          type: string
          description: The identifier of the field.
        key:
          type: string
          description: The key of the field.
        multiple:
          type: boolean
          description: Whether the field is multi-valued.
        name:
          type: string
          description: The name of the field.
        values:
          $ref: '#/components/schemas/fieldTypeWrapper'
    timelineEventType:
      type: object
      description: A timeline event type.
      properties:
        creationDate:
          type: string
          format: date-time
          description: The creation date of the object. Datetime in UTC in the https://www.ietf.org/rfc/rfc3339.txt format, example = "2025-01-22T11:21:33.872Z".
          readOnly: true
        creator:
          $ref: '#/components/schemas/UserBean'
        description:
          type: string
          description: The description.
        fieldTypes:
          type: array
          description: The field types of the timeline event type.
          items:
            $ref: '#/components/schemas/FieldTypeBean'
        id:
          type: string
          description: The object ID.
        lastModifiedDate:
          type: string
          format: date-time
          description: The last modified date of the object. Datetime in UTC in the https://www.ietf.org/rfc/rfc3339.txt format, example = "2025-01-22T11:21:33.872Z".
          readOnly: true
        lastModifiedUser:
          $ref: '#/components/schemas/UserBean'
        mappingFrontendEventType:
          type: string
          description: The identifier of the frontend event this event type maps on.
        mappingSystemEventType:
          type: string
          description: The identifier of the system event this event type maps on.
        name:
          type: string
          description: The object name.
        priority:
          type: string
          description: The priority of the timeline event type.
          enum:
          - HIGH
          - LOW
        retentionPeriod:
          type: integer
          format: int32
          description: The retention period of the timeline event type.
        source:
          type: string
          description: The source of the timeline event type.
          enum:
          - PLUGIN
          - REST
        tags:
          type: array
          description: The tags (i.e. labels).
          example: Address
          items:
            type: string
            description: The tags (i.e. labels).
            example: Address
    fieldTypeWrapper:
      type: object
      description: The value(s) of a type.
      properties:
        value:
          type: object
          description: The value of the field
    timelineEventTypes:
      type: object
      properties:
        itemsPerPage:
          type: integer
          format: int32
          description: Number of results per page.
          readOnly: true
        startIndex:
          type: integer
          format: int32
          description: The start index.
          readOnly: true
        timelineEventType:
          type: array
          description: The timeline event types.
          items:
            $ref: '#/components/schemas/timelineEventType'
        totalPages:
          type: integer
          format: int32
          description: The total number of pages.
          readOnly: true
        totalResults:
          type: integer
          format: int32
          description: The total number of results.
          readOnly: true
    UserBean:
      type: object
      description: BlueConic user.
      properties:
        fullName:
          type: string
          description: The full name of the user.
        userName:
          type: string
          description: The username.
      readOnly: true
  securitySchemes:
    oauth2:
      type: oauth2
      description: 'Authenticates a registered OAuth 2.0 client. The Authorization code flow and Client credentials flow are supported. Make sure to select the correct flow based on which flow the registered client supports. The client id and client secret can be found in BlueConic by opening the registered client under *Settings* > *Access management* > *Applications*.<br/>**NOTE:** When using the Authorization code flow, the redirect URL of the registered client in BlueConic must be set to `https://rest.apidoc.blueconic.com/oauth-receiver.html` and ''Send Proof Key for Code Exchange'' must be enabled.<br/><br/>To use a Bearer token for authentication, follow these steps: <br/>1. Acquire the token through authentication.<br/>2. Include the token in the request''s Authorization header as Bearer \<token\>.<br/>3. Send the request to access protected resources.<br/>4. Handle token expiration by refreshing or obtaining a new token.'
      flows:
        clientCredentials:
          tokenUrl: /rest/v2/oauth/token
        authorizationCode:
          authorizationUrl: /rest/v2/oauth/authorize
          tokenUrl: /rest/v2/oauth/token
          refreshUrl: /rest/v2/oauth/token