---
title: "Create Session"
method: POST
path: "/v1/agents/sessions"
tags: ["Agent Sessions"]
---

# Create Session

`POST /v1/agents/sessions`

Create a new agent session.

A session represents a stateful conversation with an AI agent that can
call tools to search data, filter results, and perform multi-step reasoning.

Args:
    request: FastAPI request with tenant context
    payload: Session creation request

Returns:
    CreateSessionResponse with session metadata

Example:
    ```bash
    curl -X POST http://localhost:8000/v1/agents/sessions \
      -H "Authorization: Bearer {api_key}" \
      -H "X-Namespace: {namespace_id}" \
      -H "Content-Type: application/json" \
      -d '{
        "agent_config": {
          "model": "claude-3-5-sonnet-20241022",
          "temperature": 0.7,
          "available_tools": ["search_retrievers", "execute_retriever"]
        },
        "quotas": {
          "max_messages": 100,
          "max_tokens_total": 100000
        }
      }'
    ```

## Request body

- CreateSessionRequest — Request payload for creating a new agent session. Attributes: agent_config: Agent configuration (model, temperature, tools, etc.) quotas: Optional session quotas and rate limits user_id: Optional user identifier user_memory: Optional initial user memory/preferences metadata: Optional session metadata Example: ```python request = CreateSessionRequest( agent_config=AgentConfig( model="claude-3-5-sonnet-20241022", temperature=0.7, available_tools=["search_retrievers", "execute_retriever"] ), quotas=SessionQuotas( max_messages=100, max_tokens_total=100000 ), user_id="user_123", user_memory={"preferences": {"language": "en"}} ) ```
  - `agent_config` AgentConfig, required — Agent configuration for session. This config is immutable after session creation (similar to RetrieverConfig). To change agent config, create a new session. Attributes: model: LLM model identifier. Supported models: - gemini-2.5-flash (fastest, cheapest) - gemini-2.5-pro (better quality) - gpt-4o-mini, gpt-4o temperature: Sampling temperature for LLM responses (0.0-2.0) - 0.0-0.3: More deterministic, focused responses - 0.5-0.7: Balanced creativity and coherence - 0.8-2.0: More creative, varied responses max_tokens: Maximum tokens per response (1-100000) system_prompt: System prompt that defines agent behavior and persona available_tools: List of tools the agent can call (see AvailableTool enum) Example: ```python config = AgentConfig( model="gemini-2.5-flash-lite", temperature=0.7, max_tokens=4096, system_prompt="You are a helpful video search assistant.", available_tools=[ "smart_search", "execute_retriever", "list_collections" ] ) ```
    - `model` string — LLM model identifier. Options: 'gemini-2.5-flash-lite' (fastest, cheapest), 'gemini-2.5-pro' (better quality), 'gpt-4o-mini', 'gpt-4o'
    - `temperature` number — Sampling temperature for LLM responses (0.0-2.0). Lower values (0.0-0.3) are more deterministic. Higher values (0.8-2.0) are more creative.
    - `max_tokens` integer — Maximum tokens per response
    - `system_prompt` string — System prompt that defines agent behavior and persona
    - `available_tools` string[] — List of API operations the agent is allowed to call. See AvailableTool enum for full list. When provided, the agent's meta-tools will restrict API calls to only these operations. When empty (default), the agent can call any API operation. Key operations: smart_search, execute_retriever, execute_adhoc_retriever, list_collections, list_retrievers, list_buckets, create_upload, analyze_sample_with_pipeline, export_manifest, generate_manifest, detect_intent.
  - `quotas` SessionQuotas — Session-level quotas and rate limits. These limits are enforced per-session to prevent runaway costs. All fields are optional - unset means unlimited. Attributes: max_messages: Maximum messages allowed in session (prevents long conversations) max_tokens_total: Maximum cumulative tokens for session (cost control) max_tool_calls: Maximum tool calls per session (limits API usage) max_session_duration_minutes: Maximum session lifetime in minutes rate_limit_messages_per_minute: Max messages per minute (prevents spam) Example: ```python # Basic quotas for a demo session quotas = SessionQuotas( max_messages=50, max_tokens_total=50000, max_tool_calls=25 ) # Strict quotas for production quotas = SessionQuotas( max_messages=100, max_tokens_total=100000, max_tool_calls=50, max_session_duration_minutes=60, rate_limit_messages_per_minute=10 ) ```
    - `max_messages` integer, nullable — Maximum messages allowed in session. Unset = unlimited.
    - `max_tokens_total` integer, nullable — Maximum cumulative tokens for session. Unset = unlimited.
    - `max_tool_calls` integer, nullable — Maximum tool calls per session. Unset = unlimited.
    - `max_session_duration_minutes` integer, nullable — Maximum session lifetime in minutes. Unset = no time limit.
    - `rate_limit_messages_per_minute` integer, nullable — Max messages per minute to prevent spam. Unset = unlimited.
  - `user_id` string, nullable — User identifier (OPTIONAL)
  - `user_memory` object — Initial user memory/preferences (OPTIONAL)
  - `metadata` object — Session metadata (OPTIONAL)
  - `enable_memory` boolean — Enable semantic memory for conversation context (OPTIONAL, default: True)

## Response `200`

Successful Response

- CreateSessionResponse — Response for session creation. Attributes: session_id: Unique session identifier namespace_id: Namespace identifier internal_id: Organization internal ID session_name: Auto-generated session name (null until first message) status: Session status created_at: Session creation timestamp expires_at: Session expiration timestamp Example: ```python response = CreateSessionResponse( session_id="ses_abc123", namespace_id="ns_xyz789", internal_id="int_abc123", session_name=None, # Will be set after first message status="active", created_at=current_time(), expires_at=current_time() + timedelta(days=7) ) ```
  - `session_id` string, required — Unique session identifier
  - `namespace_id` string, required — Namespace identifier
  - `internal_id` string, required — Organization internal ID
  - `session_name` string, nullable — Auto-generated session name based on first conversation (set after first message)
  - `status` 'active' | 'idle' | 'archived' | 'terminated', required — Session lifecycle states. Attributes: ACTIVE: Session is actively processing messages IDLE: Session exists but no recent activity ARCHIVED: Session archived (read-only) TERMINATED: Session permanently closed
  - `created_at` string, date-time, required — Session creation timestamp
  - `expires_at` string, date-time, required — Session expiration timestamp

## Other responses

- `400` — Bad Request
- `401` — Unauthorized
- `403` — Forbidden
- `404` — Not Found
- `422` — Validation Error
- `500` — Internal Server Error

---

[API](https://skmtc.net/mixpeek/apis/mixpeek-api.md) · [All operations](https://skmtc.net/mixpeek/apis/mixpeek-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/mixpeek/mixpeek-api/versions/23e05292e326/schema)