> ## Documentation Index > Fetch the complete documentation index at: https://docs.mixpeek.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # Create Session > 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 } }' ``` ## OpenAPI ````yaml post /v1/agents/sessions openapi: 3.1.0 info: title: Mixpeek API description: >- This is the Mixpeek API, providing access to various endpoints for data processing and retrieval. termsOfService: https://mixpeek.com/terms contact: name: Mixpeek Support url: https://mixpeek.com/contact email: info@mixpeek.com version: '0.82' servers: - url: https://api.mixpeek.com description: Production security: [] paths: /v1/agents/sessions: post: tags: - Agent Sessions summary: Create Session description: >- 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 } }' ``` operationId: create_session_v1_agents_sessions_post parameters: [] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateSessionRequest' responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/CreateSessionResponse' '400': description: Bad Request content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '403': description: Forbidden content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: Not Found content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' '500': description: Internal Server Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' components: schemas: CreateSessionRequest: properties: agent_config: $ref: '#/components/schemas/AgentConfig' description: Agent configuration (REQUIRED) quotas: anyOf: - $ref: '#/components/schemas/SessionQuotas' - type: 'null' description: Session quotas and rate limits (OPTIONAL) user_id: anyOf: - type: string - type: 'null' title: User Id description: User identifier (OPTIONAL) user_memory: additionalProperties: true type: object title: User Memory description: Initial user memory/preferences (OPTIONAL) metadata: additionalProperties: true type: object title: Metadata description: Session metadata (OPTIONAL) enable_memory: type: boolean title: Enable Memory description: >- Enable semantic memory for conversation context (OPTIONAL, default: True) default: true type: object required: - agent_config title: CreateSessionRequest description: |- 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"}} ) ``` examples: - agent_config: available_tools: - search_retrievers - execute_retriever - list_collections max_tokens: 4096 model: claude-3-5-sonnet-20241022 system_prompt: You are a helpful video search assistant. temperature: 0.7 quotas: max_messages: 100 max_tokens_total: 100000 max_tool_calls: 50 user_id: user_123 user_memory: preferences: domain: tech language: en CreateSessionResponse: properties: session_id: type: string title: Session Id description: Unique session identifier namespace_id: type: string title: Namespace Id description: Namespace identifier internal_id: type: string title: Internal Id description: Organization internal ID session_name: anyOf: - type: string - type: 'null' title: Session Name description: >- Auto-generated session name based on first conversation (set after first message) status: $ref: '#/components/schemas/SessionStatus' description: Session status created_at: type: string format: date-time title: Created At description: Session creation timestamp expires_at: type: string format: date-time title: Expires At description: Session expiration timestamp type: object required: - session_id - namespace_id - internal_id - status - created_at - expires_at title: CreateSessionResponse description: |- 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) ) ``` ErrorResponse: properties: success: type: boolean title: Success description: Always false for error responses default: false status: type: integer title: Status description: HTTP status code for this error error: $ref: '#/components/schemas/ErrorDetail' description: Error details payload type: object required: - status - error title: ErrorResponse description: Error response model. examples: - error: details: id: ns_123 resource: namespace message: Namespace not found type: NotFoundError status: 404 success: false HTTPValidationError: properties: detail: items: $ref: '#/components/schemas/ValidationError' type: array title: Detail type: object title: HTTPValidationError AgentConfig: properties: model: type: string title: Model description: >- LLM model identifier. Options: 'gemini-2.5-flash-lite' (fastest, cheapest), 'gemini-2.5-pro' (better quality), 'gpt-4o-mini', 'gpt-4o' default: gemini-2.5-flash-lite temperature: type: number maximum: 2 minimum: 0 title: Temperature description: >- 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. default: 0.7 max_tokens: type: integer maximum: 100000 minimum: 1 title: Max Tokens description: Maximum tokens per response default: 4096 system_prompt: type: string title: System Prompt description: System prompt that defines agent behavior and persona default: >- You are a helpful AI assistant with access to Mixpeek's data infrastructure. available_tools: items: type: string type: array title: Available Tools description: >- 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. type: object title: AgentConfig description: >- 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" ] ) ``` examples: - available_tools: - list_retrievers - get_retriever - execute_retriever - list_collections - get_collection max_tokens: 4096 model: claude-sonnet-4-5-20250929 system_prompt: >- You are a video analysis assistant that helps users find and analyze video content. temperature: 0.7 - available_tools: - list_retrievers - execute_retriever max_tokens: 2048 model: claude-3-haiku-20240307 system_prompt: You are a quick search assistant. Be concise. temperature: 0.3 SessionQuotas: properties: max_messages: anyOf: - type: integer minimum: 1 - type: 'null' title: Max Messages description: Maximum messages allowed in session. Unset = unlimited. max_tokens_total: anyOf: - type: integer minimum: 1 - type: 'null' title: Max Tokens Total description: Maximum cumulative tokens for session. Unset = unlimited. max_tool_calls: anyOf: - type: integer minimum: 1 - type: 'null' title: Max Tool Calls description: Maximum tool calls per session. Unset = unlimited. max_session_duration_minutes: anyOf: - type: integer minimum: 1 - type: 'null' title: Max Session Duration Minutes description: Maximum session lifetime in minutes. Unset = no time limit. rate_limit_messages_per_minute: anyOf: - type: integer minimum: 1 - type: 'null' title: Rate Limit Messages Per Minute description: Max messages per minute to prevent spam. Unset = unlimited. type: object title: SessionQuotas description: |- 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 ) ``` examples: - max_messages: 100 max_tokens_total: 100000 max_tool_calls: 50 rate_limit_messages_per_minute: 10 SessionStatus: type: string enum: - active - idle - archived - terminated title: SessionStatus description: |- 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 ErrorDetail: properties: message: type: string title: Message description: Human-readable error message type: type: string title: Type description: Stable error type identifier (machine-readable) code: anyOf: - type: string - type: 'null' title: Code description: >- Fine-grained error code for programmatic handling (e.g., namespace_name_taken, feature_extractor_not_found). Present only when consumers may need to branch on a specific error condition. details: anyOf: - additionalProperties: true type: object - type: 'null' title: Details description: >- Optional structured details to help debugging (validation errors, IDs, etc.) type: object required: - message - type title: ErrorDetail description: Error detail model. ValidationError: properties: loc: items: anyOf: - type: string - type: integer type: array title: Location msg: type: string title: Message type: type: string title: Error Type input: title: Input ctx: type: object title: Context type: object required: - loc - msg - type title: ValidationError ````