openapi: 3.0.3
info:
  title: Agnost AI Alerts SDK API
  description: 'Complete REST API for Agnost AI: an analytics and monitoring platform for AI agents.


    **Authentication**:

    - SDK ingestion endpoints (`/api/v1/*`) use `x-org-id` header (UUID)

    - Dashboard endpoints use `Authorization: Bearer <jwt>` + `x-org-id` header, or `x-api-key` header

    - API key management uses JWT only (no API key auth)

    '
  version: 2.1.2
  contact:
    name: Agnost AI
    url: https://agnost.ai
servers:
- url: https://api.agnost.ai
  description: Production
tags:
- name: SDK
  description: Event ingestion endpoints used by SDKs
paths:
  /api/v1/capture-session:
    post:
      tags:
      - SDK
      summary: Capture session
      description: Start a session. Call once per conversation; reuse `session_id` on every event.
      operationId: captureSession
      parameters:
      - name: x-org-id
        in: header
        required: true
        description: Your organization ID (UUID, case-insensitive).
        schema:
          type: string
          example: <org-id>
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - session_id
              - user_data
              properties:
                session_id:
                  type: string
                  format: uuid
                  description: Session UUID. Reuse on every event in this conversation.
                  example: a3f9c182-7d4e-4b6a-9e21-c5d8f0b4e731
                user_data:
                  type: object
                  description: End-user identity. `user_id` is required; other traits are supported for analytics. The example shows shape, but production integrations should prefer a stable pseudonymous ID and avoid raw email, name, phone, or other personal data unless explicitly approved.
                  required:
                  - user_id
                  properties:
                    user_id:
                      type: string
                      example: user-anon-002
                  additionalProperties:
                    type: string
                  example:
                    user_id: user-anon-002
                    email: user@example.com
                    user_plan: pro
                metadata:
                  type: object
                  additionalProperties:
                    type: string
                  description: Free-form session metadata. Prefer allowlisted operational fields; do not send secrets or sensitive personal data.
                  example:
                    language: hi-IN
                timestamp:
                  type: integer
                  format: int64
                  description: Unix time in **ms** when the session began. Defaults to server time.
                  example: 1714867200000
                client_config:
                  type: string
                  description: Free-form client/SDK label.
                  example: client-segment-001
      responses:
        '200':
          description: Session created
          content:
            application/json:
              schema:
                type: object
                properties:
                  session_id:
                    type: string
        '400':
          $ref: '#/components/responses/BadRequest'
  /api/v1/capture-event:
    post:
      tags:
      - SDK
      summary: Capture event
      description: Record one turn-pair or tool call. Generate `event_id` client-side so children can reference parents.
      operationId: captureEvent
      parameters:
      - name: x-org-id
        in: header
        required: true
        description: Your organization ID (UUID, case-insensitive).
        schema:
          type: string
          example: <org-id>
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - event_id
              - session_id
              - primitive_name
              - args
              - result
              properties:
                event_id:
                  type: string
                  format: uuid
                  description: Client-generated UUID. Use as `parent_id` on child events.
                  example: e8b1c52f-3a9d-4e7c-8f0b-2d6a91c4ef58
                session_id:
                  type: string
                  format: uuid
                  description: Session UUID from `capture-session`.
                  example: a3f9c182-7d4e-4b6a-9e21-c5d8f0b4e731
                primitive_name:
                  type: string
                  description: Agent name (turn-pair) or tool name (tool call).
                  example: your-agent-name
                args:
                  type: string
                  description: Input — user message or JSON-encoded tool args.
                  example: your input in plain text or JSON-encoded string
                result:
                  type: string
                  description: Output — assistant reply or JSON-encoded tool result.
                  example: your output in plain text or JSON-encoded string
                success:
                  type: boolean
                  description: Defaults to `true`.
                latency:
                  type: integer
                  description: Execution time in **ms**.
                  example: 5200
                timestamp:
                  type: integer
                  format: int64
                  description: Unix time in **ms** when the event occurred. Defaults to server time.
                  example: 1714867201000
                parent_id:
                  type: string
                  format: uuid
                  description: Parent event UUID. Set on tool calls to point at the agent turn (or parent tool) that triggered them.
                  example: 4c7d2e8a-1b95-4f3d-a08e-7b3c9d12f5e6
                metadata:
                  type: object
                  additionalProperties:
                    type: string
                  description: Free-form event metadata.
                  example:
                    language: hi-IN
      responses:
        '200':
          description: Event recorded
          content:
            application/json:
              schema:
                type: object
                properties:
                  event_id:
                    type: string
                    format: uuid
        '400':
          $ref: '#/components/responses/BadRequest'
components:
  schemas:
    Error:
      type: object
      properties:
        error:
          type: string
      required:
      - error
      example:
        error: Invalid request body
  responses:
    BadRequest:
      description: Invalid request body
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    OrgId:
      type: apiKey
      in: header
      name: x-org-id
      description: Organization ID (UUID). Used by SDKs for event ingestion. Header is case-insensitive.
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: JWT token from OAuth login.
    ApiKey:
      type: apiKey
      in: header
      name: x-api-key
      description: API key (`agnost_<64-hex>`) for programmatic dashboard access. Issued via Settings → API Keys.
    OrgScope:
      type: apiKey
      in: header
      name: x-org-id
      description: Optional. Selects which organization a JWT- or API-key-authenticated request targets when the credential has access to multiple.