Create Session

curl --request POST \
  --url https://api.mixpeek.com/v1/agents/sessions \
  --header 'Content-Type: application/json' \
  --data @- <<EOF
{
  "agent_config": {
    "model": "gpt-4o-mini",
    "temperature": 0.7,
    "max_tokens": 4096,
    "system_prompt": "You are a helpful AI assistant with access to Mixpeek's data infrastructure.",
    "available_tools": [
      "<string>"
    ]
  },
  "quotas": {
    "max_messages": 100,
    "max_tokens_total": 100000,
    "max_tool_calls": 50,
    "rate_limit_messages_per_minute": 10
  },
  "user_id": "<string>",
  "user_memory": {},
  "metadata": {},
  "enable_memory": true
}
EOF

{
  "session_id": "<string>",
  "namespace_id": "<string>",
  "internal_id": "<string>",
  "status": "active",
  "created_at": "2023-11-07T05:31:56Z",
  "expires_at": "2023-11-07T05:31:56Z",
  "session_name": "<string>"
}

Agent Sessions

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:

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
    }
  }'

POST

agents

sessions

Create Session

curl --request POST \
  --url https://api.mixpeek.com/v1/agents/sessions \
  --header 'Content-Type: application/json' \
  --data @- <<EOF
{
  "agent_config": {
    "model": "gpt-4o-mini",
    "temperature": 0.7,
    "max_tokens": 4096,
    "system_prompt": "You are a helpful AI assistant with access to Mixpeek's data infrastructure.",
    "available_tools": [
      "<string>"
    ]
  },
  "quotas": {
    "max_messages": 100,
    "max_tokens_total": 100000,
    "max_tool_calls": 50,
    "rate_limit_messages_per_minute": 10
  },
  "user_id": "<string>",
  "user_memory": {},
  "metadata": {},
  "enable_memory": true
}
EOF

{
  "session_id": "<string>",
  "namespace_id": "<string>",
  "internal_id": "<string>",
  "status": "active",
  "created_at": "2023-11-07T05:31:56Z",
  "expires_at": "2023-11-07T05:31:56Z",
  "session_name": "<string>"
}

Headers

Authorization

string

REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.

X-Namespace

string

REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'

Body

application/json

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 · object

required

Agent configuration (REQUIRED)

Show child attributes

agent_config.model

string

default:gpt-4o-mini

LLM model identifier. Options: 'gpt-4o-mini' (fastest), 'gpt-4o' (recommended), 'claude-3-5-sonnet-20241022', 'claude-3-haiku-20240307'

agent_config.temperature

number

default:0.7

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.

Required range: 0 <= x <= 2

agent_config.max_tokens

integer

default:4096

Maximum tokens per response

Required range: 1 <= x <= 100000

agent_config.system_prompt

string

default:You are a helpful AI assistant with access to Mixpeek's data infrastructure.

System prompt that defines agent behavior and persona

agent_config.available_tools

string[]

List of tool names the agent can call. Available tools: RETRIEVER: list_retrievers, get_retriever, explain_retriever, execute_retriever, search_retrievers. COLLECTION: list_collections, get_collection, create_collection, update_collection, delete_collection. TAXONOMY: list_taxonomies, get_taxonomy, create_taxonomy, update_taxonomy, delete_taxonomy. REGISTRY: list_stages, list_extractors. INGEST: ingest_document. CLUSTER: list_clusters. OBJECT: get_object.

quotas

SessionQuotas · object

Session quotas and rate limits (OPTIONAL)

Show child attributes

quotas.max_messages

integer | null

Maximum messages allowed in session. Unset = unlimited.

Required range: x >= 1

quotas.max_tokens_total

integer | null

Maximum cumulative tokens for session. Unset = unlimited.

Required range: x >= 1

quotas.max_tool_calls

integer | null

Maximum tool calls per session. Unset = unlimited.

Required range: x >= 1

quotas.max_session_duration_minutes

integer | null

Maximum session lifetime in minutes. Unset = no time limit.

Required range: x >= 1

quotas.rate_limit_messages_per_minute

integer | null

Max messages per minute to prevent spam. Unset = unlimited.

Required range: x >= 1

Example:

{
  "max_messages": 100,
  "max_tokens_total": 100000,
  "max_tool_calls": 50,
  "rate_limit_messages_per_minute": 10
}

user_id

string | null

User identifier (OPTIONAL)

user_memory

User Memory · object

Initial user memory/preferences (OPTIONAL)

metadata

Metadata · object

Session metadata (OPTIONAL)

enable_memory

boolean

default:true

Enable semantic memory for conversation context (OPTIONAL, default: True)

Response

Successful Response

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=datetime.utcnow(), expires_at=datetime.utcnow() + timedelta(days=7) )

session_id

string

required

Unique session identifier

namespace_id

string

required

Namespace identifier

internal_id

string

required

Organization internal ID

status

enum<string>

required

Session status

Available options:

active,

idle,

archived,

terminated

created_at

string<date-time>

required

Session creation timestamp

expires_at

string<date-time>

required

Session expiration timestamp

session_name

string | null

Auto-generated session name based on first conversation (set after first message)

Execute Raw Inference List Sessions

⌘I

Health

Organizations

Namespaces

Buckets

Feature Extractors

Collections

Retrievers

Taxonomies

Clusters

Templates

Analytics

Resource Search

Inference

Agent Sessions

Tasks

Webhooks

Notifications

Triggers

Create Session

Headers

Body

Response