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

# Create Session

> Initialize a new conversation session

### Authorization

<ParamField header="Authorization" type="string" required>
  Bearer token. Format: `Bearer synthra_live_abc123def456`
</ParamField>

### Body Parameters

<ParamField body="userId" type="string" required>
  Unique identifier for the user. Format: `user_<16 chars>`
</ParamField>

<ParamField body="metadata" type="object">
  Optional metadata to attach to the session.

  Example: `{ "source": "web", "language": "en" }`
</ParamField>

<ParamField body="contextConfig" type="object">
  Context window configuration.

  Properties:

  * `maxTokens` (number): Maximum context window size. Default: 4096
  * `compressionEnabled` (boolean): Enable automatic compression. Default: true
  * `retentionPolicy` (string): Strategy for message retention. Options: `fifo`, `priority`, `semantic`
</ParamField>

### Response

<ResponseField name="sessionId" type="string">
  Unique session identifier. Format: `session_<16 chars>`
</ResponseField>

<ResponseField name="userId" type="string">
  User identifier associated with this session
</ResponseField>

<ResponseField name="createdAt" type="string">
  ISO 8601 timestamp of session creation
</ResponseField>

<ResponseField name="expiresAt" type="string">
  ISO 8601 timestamp when session will auto-expire (24 hours)
</ResponseField>

<ResponseField name="messageCount" type="number">
  Current number of messages in session. Initially 0.
</ResponseField>

<ResponseField name="tokenUsage" type="object">
  Token usage statistics

  Properties:

  * `total` (number): Total tokens used
  * `prompt` (number): Tokens in prompts
  * `completion` (number): Tokens in completions
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl --request POST \
    --url https://api.synthra.ai/v1/sessions \
    --header 'Authorization: Bearer synthra_live_abc123def456' \
    --header 'Content-Type: application/json' \
    --data '{
      "userId": "user_9f8e7d6c5b4a",
      "metadata": {
        "source": "web",
        "language": "en"
      },
      "contextConfig": {
        "maxTokens": 8192,
        "compressionEnabled": true,
        "retentionPolicy": "semantic"
      }
    }'
  ```

  ```javascript Node.js theme={null}
  const response = await fetch('https://api.synthra.ai/v1/sessions', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.SYNTHRA_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      userId: 'user_9f8e7d6c5b4a',
      metadata: {
        source: 'web',
        language: 'en'
      },
      contextConfig: {
        maxTokens: 8192,
        compressionEnabled: true,
        retentionPolicy: 'semantic'
      }
    })
  });
  const data = await response.json();
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      'https://api.synthra.ai/v1/sessions',
      headers={
          'Authorization': f'Bearer {api_key}',
          'Content-Type': 'application/json'
      },
      json={
          'userId': 'user_9f8e7d6c5b4a',
          'metadata': {
              'source': 'web',
              'language': 'en'
          },
          'contextConfig': {
              'maxTokens': 8192,
              'compressionEnabled': True,
              'retentionPolicy': 'semantic'
          }
      }
  )
  ```
</RequestExample>

<ResponseExample>
  ```json 200 - Success theme={null}
  {
    "sessionId": "session_abc123def456",
    "userId": "user_9f8e7d6c5b4a",
    "createdAt": "2024-03-08T14:30:00Z",
    "expiresAt": "2024-03-09T14:30:00Z",
    "messageCount": 0,
    "tokenUsage": {
      "total": 0,
      "prompt": 0,
      "completion": 0
    }
  }
  ```

  ```json 400 - Bad Request theme={null}
  {
    "error": {
      "code": "validation_error",
      "message": "userId must be a valid string with format user_<16 chars>",
      "field": "userId"
    }
  }
  ```

  ```json 401 - Unauthorized theme={null}
  {
    "error": {
      "code": "invalid_token",
      "message": "The provided authentication token is invalid or expired"
    }
  }
  ```

  ```json 429 - Rate Limited theme={null}
  {
    "error": {
      "code": "rate_limit_exceeded",
      "message": "Rate limit exceeded. Maximum 100 requests per minute.",
      "retryAfter": 45
    }
  }
  ```
</ResponseExample>