openapi: 3.0.1
info:
  title: Trubrics Ingestion Events API
  description: Public, write-only HTTP ingestion API for the Trubrics product analytics platform for AI applications. Publish batches of up to 100 product analytics events or LLM events to your Trubrics project, authenticated with a project x-api-key. The API contains public write endpoints only; analysis is done in the Trubrics application.
  termsOfService: https://www.trubrics.com/terms-of-use
  contact:
    name: Trubrics
    url: https://www.trubrics.com
  version: '1.0'
servers:
- url: https://app.trubrics.com/api/ingestion
  description: Trubrics ingestion API
security:
- apiKeyAuth: []
tags:
- name: Events
paths:
  /publish_events:
    post:
      operationId: publishEvents
      tags:
      - Events
      summary: Publish events
      description: Publish a batch of up to 100 product analytics events to your Trubrics project. Each event has a user_id, an event name, a timestamp, and optional custom properties (the reserved $thread_id property groups events into a conversation thread).
      security:
      - apiKeyAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              maxItems: 100
              items:
                $ref: '#/components/schemas/Event'
            example:
            - user_id: user_123
              event: Sign up
              timestamp: '2026-06-20T12:00:00Z'
              properties:
                country: US
            - user_id: user_123
              event: Converted
              timestamp: '2026-06-20T12:05:00Z'
              properties:
                plan: team
      responses:
        '200':
          description: Events accepted for ingestion.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IngestionResponse'
        '401':
          description: Missing or invalid x-api-key.
        '422':
          description: Validation error in the event payload.
components:
  schemas:
    IngestionResponse:
      type: object
      description: Acknowledgement that the batch was accepted for ingestion.
      properties:
        status:
          type: string
          example: success
    Event:
      type: object
      required:
      - user_id
      - event
      - timestamp
      properties:
        user_id:
          type: string
          description: Distinct ID of the signed-in user.
          example: user_123
        event:
          type: string
          description: Name of the event being tracked.
          example: User prompt
        timestamp:
          type: string
          format: date-time
          description: Event timestamp.
          example: '2026-06-20T12:00:00Z'
        properties:
          type: object
          additionalProperties: true
          description: Custom event/user properties used for filtering analysis. The reserved $thread_id property groups events into a conversation.
          example:
            country: US
            $thread_id: thread_abc
  securitySchemes:
    apiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: Project-scoped write-only API key, copied from the project settings page in the Trubrics application.