openapi: 3.1.0
info:
  title: Sentrial SDK Events Sessions 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: Sessions
  description: Create and manage agent sessions.
paths:
  /api/sdk/sessions:
    post:
      operationId: createSession
      summary: Create a session
      description: Create a new agent session. A session is a complete record of a single agent interaction.
      tags:
      - Sessions
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateSessionRequest'
            example:
              name: Customer Support Request
              agentName: support-agent
              userId: user_123
              metadata:
                ticketId: TKT-789
                channel: web_chat
      responses:
        '200':
          description: Session created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Session'
              example:
                id: sess_abc123def456
                name: Customer Support Request
                agentName: support-agent
                userId: user_123
                status: active
                createdAt: '2025-01-12T10:30:00Z'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '500':
          $ref: '#/components/responses/ServerError'
  /api/sdk/sessions/{id}:
    patch:
      operationId: updateSession
      summary: Update a session
      description: Update a session's status and record final metrics (cost, duration, token usage, custom metrics).
      tags:
      - Sessions
      parameters:
      - name: id
        in: path
        required: true
        description: ID of the session to update.
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateSessionRequest'
            example:
              status: completed
              success: true
              estimatedCost: 0.045
              durationMs: 3500
              promptTokens: 1500
              completionTokens: 500
              totalTokens: 2000
              customMetrics:
                satisfaction: 4.5
                resolution_time: 120
      responses:
        '200':
          description: Session updated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Session'
              example:
                id: sess_abc123def456
                name: Customer Support Request
                status: completed
                success: true
                estimatedCost: 0.045
                durationMs: 3500
                completedAt: '2025-01-12T10:30:03Z'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/ServerError'
components:
  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'
    Forbidden:
      description: API key does not have permission for this action.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  schemas:
    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
    Session:
      type: object
      properties:
        id:
          type: string
          description: Session ID (prefix sess_).
        name:
          type: string
        agentName:
          type: string
        userId:
          type: string
        status:
          type: string
          enum:
          - active
          - completed
          - failed
        success:
          type: boolean
        estimatedCost:
          type: number
        durationMs:
          type: number
        createdAt:
          type: string
          format: date-time
        completedAt:
          type: string
          format: date-time
    UpdateSessionRequest:
      type: object
      properties:
        status:
          type: string
          enum:
          - completed
          - failed
          description: Terminal status of the session.
        success:
          type: boolean
          description: Whether the session completed successfully.
        failureReason:
          type: string
          description: Reason the session failed.
        estimatedCost:
          type: number
          description: Total cost in USD.
        durationMs:
          type: number
          description: Duration in milliseconds.
        promptTokens:
          type: number
          description: Input tokens used.
        completionTokens:
          type: number
          description: Output tokens used.
        totalTokens:
          type: number
          description: Total tokens.
        customMetrics:
          type: object
          additionalProperties: true
          description: Custom numeric metrics.
    CreateSessionRequest:
      type: object
      required:
      - name
      - agentName
      - userId
      properties:
        name:
          type: string
          description: Descriptive name for the session.
        agentName:
          type: string
          description: Agent identifier for grouping.
        userId:
          type: string
          description: External user identifier.
        metadata:
          type: object
          additionalProperties: true
          description: Custom key-value data.
  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.