Sentrial Events API

openapi: 3.1.0
info:
  title: Sentrial SDK Events API
  version: '1.0'
  description: Sentrial is an AI agent observability platform. The SDK/ingestion REST API lets you create and manage agent sessions and record the events (tool calls, LLM decisions, state changes, errors) that happen inside them, so Sentrial can detect issues, diagnose root causes, and help you fix them in code. This specification was generated by API Evangelist from Sentrial's published documentation (https://www.sentrial.com/docs/api/*) — every field, request, response, and error is transcribed from the docs, not inferred.
  contact:
    name: Sentrial
    url: https://sentrial.com
  x-apievangelist-generated: true
  x-apievangelist-source: https://www.sentrial.com/docs/api/sessions.md, https://www.sentrial.com/docs/api/events.md, https://www.sentrial.com/docs/api/auth.md
servers:
- url: https://api.sentrial.com
  description: Production
security:
- bearerAuth: []
tags:
- name: Events
  description: Track events within agent sessions.
paths:
  /api/sdk/events:
    post:
      operationId: createEvent
      summary: Create an event
      description: Record an event (tool call, LLM decision, state change, or error) within an agent session.
      tags:
      - Events
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateEventRequest'
            example:
              sessionId: sess_abc123def456
              eventType: tool_call
              toolName: search_kb
              toolInput:
                query: password reset
              toolOutput:
                results:
                - KB-001
                - KB-002
              reasoning: User needs password help
              estimatedCost: 0.001
      responses:
        '200':
          description: Event created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Event'
              example:
                id: evt_xyz789
                sessionId: sess_abc123def456
                eventType: tool_call
                toolName: search_kb
                createdAt: '2025-01-12T10:30:01Z'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/ServerError'
components:
  schemas:
    CreateEventRequest:
      type: object
      required:
      - sessionId
      - eventType
      properties:
        sessionId:
          type: string
          description: ID of the parent session.
        eventType:
          type: string
          enum:
          - tool_call
          - llm_decision
          - state_change
          - error
          description: The type of event being recorded.
        toolName:
          type: string
          description: Name of the tool called (for tool_call events).
        toolInput:
          type: object
          additionalProperties: true
          description: Input passed to the tool.
        toolOutput:
          type: object
          additionalProperties: true
          description: Output returned by the tool.
        reasoning:
          type: string
          description: Agent's reasoning for this action.
        alternativesConsidered:
          type: array
          items:
            type: string
          description: Other options the agent considered.
        confidence:
          type: number
          description: Confidence score (0.0 to 1.0).
        estimatedCost:
          type: number
          description: Cost for this event in USD.
    Error:
      type: object
      properties:
        error:
          type: string
          description: Short error code/title.
        message:
          type: string
          description: Human-readable explanation.
      example:
        error: Unauthorized
        message: Invalid or missing API key
    Event:
      type: object
      properties:
        id:
          type: string
          description: Event ID (prefix evt_).
        sessionId:
          type: string
        eventType:
          type: string
          enum:
          - tool_call
          - llm_decision
          - state_change
          - error
        toolName:
          type: string
        createdAt:
          type: string
          format: date-time
  responses:
    ServerError:
      description: Server error, please retry.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: Invalid or missing API key.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    BadRequest:
      description: Missing required fields or invalid data.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: Session ID not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: API key passed as a Bearer token in the Authorization header. Keys follow the format sentrial_live_xxxxxxxxxxxxx and are created in organization Settings -> API Keys.