> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agnost.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Capture Session

> Start a session at the beginning of a conversation

Call once per conversation. Reuse `session_id` on every event that follows.

## Body

| Field           | Type            | Required | Description                                                          |
| --------------- | --------------- | -------- | -------------------------------------------------------------------- |
| `session_id`    | `string` (UUID) | Required | Session UUID. Reuse on every event in this conversation.             |
| `user_data`     | `object`        | Required | End-user identity. Must contain `user_id`; other keys are free-form. |
| `metadata`      | `object`        | Optional | Free-form session metadata.                                          |
| `timestamp`     | `integer` (ms)  | Optional | Unix time in ms when the session began. Defaults to server time.     |
| `client_config` | `string`        | Optional | Free-form client/SDK label.                                          |


## OpenAPI

````yaml POST /api/v1/capture-session
openapi: 3.0.3
info:
  title: Agnost AI 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.1
  contact:
    name: Agnost AI
    url: https://agnost.ai
servers:
  - url: https://api.agnost.ai
    description: Production
security: []
tags:
  - name: SDK
    description: Event ingestion endpoints used by SDKs
  - name: Dashboard
    description: Analytics and metrics for the dashboard
  - name: Organizations
    description: Organization management
  - name: Alerts
    description: Alert configuration and monitoring
  - name: SOPs
    description: Standard Operating Procedures
  - name: Sentiments
    description: Sentiment and intent analysis
  - name: Conversations
    description: Conversation message and span retrieval
  - name: Classification
    description: LLM-based classification operations
  - name: Onboarding
    description: First-run helpers used during organization setup
  - name: Connections
    description: External integrations (Slack)
  - name: Billing
    description: Stripe billing management
  - name: API Keys
    description: API key management
  - name: Auth
    description: OAuth authentication callbacks
  - name: System
    description: Health checks, webhooks, internal endpoints
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 keys are
                    free-form.
                  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.
                  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'
components:
  responses:
    BadRequest:
      description: Invalid request body
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  schemas:
    Error:
      type: object
      properties:
        error:
          type: string
      required:
        - error
      example:
        error: Invalid request body

````