openapi: 3.0.0
info:
  title: Schematic accesstokens events API
  version: '0.1'
  description: Schematic API
  x-rules-engine-schema-version: v97288f60
servers:
- url: https://api.schematichq.com
security:
- ApiKeyAuth: []
tags:
- name: events
paths:
  /event-batch:
    post:
      operationId: createEventBatch
      summary: Create event batch
      tags:
      - events
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateEventBatchRequestBody'
        required: true
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/RawEventBatchResponseData'
                  params:
                    type: object
                    description: Input parameters
                    title: CreateEventBatchParams
                required:
                - data
                - params
                title: CreateEventBatchResponse
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/ServerError'
  /event-types:
    get:
      operationId: getEventSummaries
      summary: Get event summaries
      tags:
      - events
      parameters:
      - name: q
        in: query
        schema:
          type: string
          maxLength: 512
      - name: event_subtypes
        in: query
        schema:
          type: array
          items:
            type: string
          maxItems: 100
      - name: limit
        in: query
        description: Page limit (default 100)
        schema:
          type: integer
          description: Page limit (default 100)
          format: int64
          example: '100'
      - name: offset
        in: query
        description: Page offset (default 0)
        schema:
          type: integer
          description: Page offset (default 0)
          format: int64
          example: '0'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/EventSummaryResponseData'
                    title: GetEventSummariesResponseData
                    maxItems: 250
                  params:
                    type: object
                    description: Input parameters
                    properties:
                      event_subtypes:
                        type: array
                        items:
                          type: string
                        maxItems: 100
                      limit:
                        type: integer
                        description: Page limit (default 100)
                        format: int64
                        example: '100'
                      offset:
                        type: integer
                        description: Page offset (default 0)
                        format: int64
                        example: '0'
                      q:
                        type: string
                        maxLength: 512
                    title: GetEventSummariesParams
                required:
                - data
                - params
                title: GetEventSummariesResponse
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/ServerError'
  /events:
    get:
      operationId: listEvents
      summary: List events
      tags:
      - events
      parameters:
      - name: company_id
        in: query
        schema:
          type: string
      - name: event_subtype
        in: query
        schema:
          type: string
          maxLength: 255
      - name: event_types
        in: query
        schema:
          type: array
          items:
            $ref: '#/components/schemas/EventType'
          maxItems: 100
      - name: flag_id
        in: query
        schema:
          type: string
      - name: idempotency_key
        in: query
        schema:
          type: string
          maxLength: 255
      - name: user_id
        in: query
        schema:
          type: string
      - name: limit
        in: query
        description: Page limit (default 100)
        schema:
          type: integer
          description: Page limit (default 100)
          format: int64
          example: '100'
      - name: offset
        in: query
        description: Page offset (default 0)
        schema:
          type: integer
          description: Page offset (default 0)
          format: int64
          example: '0'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/EventDetailResponseData'
                    title: ListEventsResponseData
                    maxItems: 250
                  params:
                    type: object
                    description: Input parameters
                    properties:
                      company_id:
                        type: string
                      event_subtype:
                        type: string
                        maxLength: 255
                      event_types:
                        type: array
                        items:
                          $ref: '#/components/schemas/EventType'
                        maxItems: 100
                      flag_id:
                        type: string
                      idempotency_key:
                        type: string
                        maxLength: 255
                      limit:
                        type: integer
                        description: Page limit (default 100)
                        format: int64
                        example: '100'
                      offset:
                        type: integer
                        description: Page offset (default 0)
                        format: int64
                        example: '0'
                      user_id:
                        type: string
                    title: ListEventsParams
                required:
                - data
                - params
                title: ListEventsResponse
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/ServerError'
    post:
      operationId: createEvent
      summary: Create event
      tags:
      - events
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateEventRequestBody'
        required: true
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/RawEventResponseData'
                  params:
                    type: object
                    description: Input parameters
                    title: CreateEventParams
                required:
                - data
                - params
                title: CreateEventResponse
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/ServerError'
  /events/{event_id}:
    get:
      operationId: getEvent
      summary: Get event
      tags:
      - events
      parameters:
      - name: event_id
        in: path
        description: event_id
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/EventDetailResponseData'
                  params:
                    type: object
                    description: Input parameters
                    title: GetEventParams
                required:
                - data
                - params
                title: GetEventResponse
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/ServerError'
  /segment-integration:
    get:
      operationId: getSegmentIntegrationStatus
      summary: Get segment integration status
      tags:
      - events
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/SegmentStatusResp'
                  params:
                    type: object
                    description: Input parameters
                    title: GetSegmentIntegrationStatusParams
                required:
                - data
                - params
                title: GetSegmentIntegrationStatusResponse
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/ServerError'
components:
  responses:
    Forbidden:
      description: Forbidden
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
    ServerError:
      description: Server error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
    NotFound:
      description: Not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
    Unauthorized:
      description: Unauthorized
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
    BadRequest:
      description: Bad request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
  schemas:
    RawEventBatchResponseData:
      type: object
      properties:
        events:
          type: array
          items:
            $ref: '#/components/schemas/RawEventResponseData'
          maxItems: 1000
      required:
      - events
      title: RawEventBatchResponseData
    EventType:
      type: string
      enum:
      - flag_check
      - identify
      - track
    ApiError:
      type: object
      properties:
        error:
          type: string
          description: Error message
      required:
      - error
    EventDetailResponseData:
      type: object
      properties:
        api_key:
          type: string
          nullable: true
        body:
          type: object
        body_preview:
          type: string
        captured_at:
          type: string
          format: date-time
        company:
          $ref: '#/components/schemas/PreviewObject'
        company_id:
          type: string
          nullable: true
        enriched_at:
          type: string
          format: date-time
          nullable: true
          deprecated: true
        environment_id:
          type: string
          nullable: true
        error_message:
          type: string
          nullable: true
        feature_ids:
          type: array
          items:
            type: string
          maxItems: 1000
        features:
          type: array
          items:
            $ref: '#/components/schemas/PreviewObject'
          maxItems: 1000
        id:
          type: string
        idempotency_key:
          type: string
          nullable: true
        loaded_at:
          type: string
          format: date-time
          nullable: true
        processed_at:
          type: string
          format: date-time
          nullable: true
          deprecated: true
        quantity:
          type: integer
          format: int64
        sent_at:
          type: string
          format: date-time
          nullable: true
        status:
          $ref: '#/components/schemas/EventStatus'
        subtype:
          type: string
          nullable: true
        type:
          $ref: '#/components/schemas/EventType'
        updated_at:
          type: string
          format: date-time
          nullable: true
          deprecated: true
        user:
          $ref: '#/components/schemas/PreviewObject'
        user_id:
          type: string
          nullable: true
      required:
      - body
      - body_preview
      - captured_at
      - type
      - feature_ids
      - id
      - quantity
      - status
      - features
      title: EventDetailResponseData
    EventSummaryResponseData:
      type: object
      properties:
        company_count:
          type: integer
          format: int64
        environment_id:
          type: string
        event_count:
          type: integer
          format: int64
        event_subtype:
          type: string
        last_seen_at:
          type: string
          format: date-time
          nullable: true
        user_count:
          type: integer
          format: int64
      required:
      - company_count
      - environment_id
      - event_count
      - event_subtype
      - user_count
      title: EventSummaryResponseData
    CreateEventBatchRequestBody:
      type: object
      properties:
        events:
          type: array
          items:
            $ref: '#/components/schemas/CreateEventRequestBody'
          maxItems: 1000
      required:
      - events
      title: CreateEventBatchRequestBody
    EventBodyIdentify:
      type: object
      properties:
        company:
          type: object
          description: Information about the company associated with the user; required only if it is a new user
          properties:
            keys:
              additionalProperties:
                type: string
              type: object
              description: Key-value pairs to identify the company
            name:
              type: string
              description: The display name of the company; required only if it is a new company
            traits:
              type: object
              description: A map of trait names to trait values
          required:
          - keys
          title: EventBodyIdentifyCompany
        keys:
          additionalProperties:
            type: string
          type: object
          description: Key-value pairs to identify the user
        name:
          type: string
          description: The display name of the user being identified; required only if it is a new user
        traits:
          type: object
          description: A map of trait names to trait values
      required:
      - keys
      title: EventBodyIdentify
    CreateEventRequestBody:
      type: object
      properties:
        body:
          $ref: '#/components/schemas/EventBody'
        event_type:
          allOf:
          - $ref: '#/components/schemas/EventType'
          description: Either 'identify' or 'track'
        idempotency_key:
          type: string
          description: Optional client-supplied key. Duplicate events with the same key (scoped to the environment) are dropped for 24h.
          nullable: true
          maxLength: 255
        sent_at:
          type: string
          description: Optionally provide a timestamp at which the event was sent to Schematic
          format: date-time
          nullable: true
      required:
      - event_type
      title: CreateEventRequestBody
    PreviewObject:
      type: object
      properties:
        description:
          type: string
          nullable: true
        id:
          type: string
        image_url:
          type: string
          nullable: true
        name:
          type: string
      required:
      - id
      - name
      title: PreviewObject
    EventStatus:
      type: string
      enum:
      - enriched
      - failed
      - pending
      - processed
      - unknown
    EventBodyFlagCheck:
      type: object
      properties:
        company_id:
          type: string
          description: Schematic company ID (starting with 'comp_') of the company evaluated, if any
          nullable: true
        error:
          type: string
          description: Report an error that occurred during the flag check
          nullable: true
        flag_id:
          type: string
          description: Schematic flag ID (starting with 'flag_') for the flag matching the key, if any
          nullable: true
        flag_key:
          type: string
          description: The key of the flag being checked
        reason:
          type: string
          description: The reason why the value was returned
        req_company:
          additionalProperties:
            type: string
          type: object
          description: Key-value pairs used to to identify company for which the flag was checked
          nullable: true
        req_user:
          additionalProperties:
            type: string
          type: object
          description: Key-value pairs used to to identify user for which the flag was checked
          nullable: true
        rule_id:
          type: string
          description: Schematic rule ID (starting with 'rule_') of the rule that matched for the flag, if any
          nullable: true
        user_id:
          type: string
          description: Schematic user ID (starting with 'user_') of the user evaluated, if any
          nullable: true
        value:
          type: boolean
          description: The value of the flag for the given company and/or user
      required:
      - flag_key
      - reason
      - value
      title: EventBodyFlagCheck
    EventBodyTrack:
      type: object
      properties:
        company:
          additionalProperties:
            type: string
          type: object
          description: Key-value pairs to identify company associated with track event
        event:
          type: string
          description: The name of the type of track event
        quantity:
          type: integer
          description: Optionally specify the quantity of the event
        traits:
          type: object
          description: A map of trait names to trait values
        user:
          additionalProperties:
            type: string
          type: object
          description: Key-value pairs to identify user associated with track event
      required:
      - event
      title: EventBodyTrack
    SegmentStatusResp:
      type: object
      properties:
        connected:
          type: boolean
        environment_id:
          type: string
        last_event_at:
          type: string
          format: date-time
          nullable: true
      required:
      - connected
      - environment_id
      title: SegmentStatusResp
    EventBody:
      type: object
      oneOf:
      - $ref: '#/components/schemas/EventBodyTrack'
      - $ref: '#/components/schemas/EventBodyFlagCheck'
      - $ref: '#/components/schemas/EventBodyIdentify'
      title: EventBody
    RawEventResponseData:
      type: object
      properties:
        captured_at:
          type: string
          format: date-time
        event_id:
          type: string
          nullable: true
        remote_addr:
          type: string
          nullable: true
        remote_ip:
          type: string
        user_agent:
          type: string
      required:
      - captured_at
      - remote_ip
      - user_agent
      title: RawEventResponseData
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-Schematic-Api-Key