Conversations

Enable automatic conversation persistence to maintain chat history and context across sessions.

This is a beta feature according to Algolia’s Terms of Service (“Beta Services”).

Conversations save (persist) chat history for you. If you send a conversation ID and message ID with each completion request, Agent Studio stores the full exchange so you can fetch it later, including questions, answers, tool calls, and metadata.

For example, a customer support agent can reopen a user’s troubleshooting session from yesterday and continue with the full context of what was already tried and discussed.

How conversations work

Conversation persistence operates automatically when you provide the required identifiers:

Agent Studio automatically:

• Saves conversations when both id (conversation ID) and message id fields are present
• Generates conversation titles from the first user message (60-character maximum)
• Respects your app’s retention policies (0, 30, 60, or 90 days)
• Supports two access modes: unauthenticated (requires an API key with the logs ACL) and authenticated (user-scoped with a secure JWT).

Enable conversation persistence

To enable automatic conversation saving, include both a conversation ID and message IDs in your completion request:

curl -X POST "https://ALGOLIA_APPLICATION_ID.algolia.net/agent-studio/1/agents/{agent_id}/completions" \
  -H "X-Algolia-Application-Id: ALGOLIA_APPLICATION_ID" \
  -H "X-Algolia-API-Key: ALGOLIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "alg_cnv_abc123",
    "messages": [
      {
        "id": "alg_msg_xyz789",
        "role": "user",
        "content": "How do I reset my password?"
      }
    ]
  }'

Both properties are required for persistence:

• id: the conversation identifier (prefix with alg_cnv_ for consistency)
• messages[].id: unique identifier for each message (prefix with alg_msg_)

If either property is missing, the conversation won’t be saved.

Unauthenticated conversations

Unauthenticated conversations provide basic persistence without user authentication. Conversations are not associated with any user—they exist as standalone entities accessible by conversation ID. This approach works well for testing, internal admin tools, and single-tenant applications without user accounts.

When to use

• Applications without backend authentication infrastructure: when your application doesn’t have a backend to generate secure user tokens
• Single-tenant apps: all users share the same data and user isolation isn’t required
• Internal admin tools: where all users have full access to all conversations
• Development and testing: for quick iteration without authentication setup
• Prototypes and demos: for proof-of-concept implementations

How authenticated scoping works

Include the conversation and message IDs in your request. No additional authentication is needed:

curl

curl -X POST "https://YOUR_APP_ID.algolia.net/agent-studio/1/agents/{agent_id}/completions" \
  -H "X-Algolia-Application-Id: ALGOLIA_APP_ID" \
  -H "X-Algolia-API-Key: ALGOLIA_SEARCH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "alg_cnv_support_12345",
    "messages": [
      {
        "id": "alg_msg_001",
        "role": "user",
        "content": "My order hasn't arrived yet"
      }
    ]
  }'

To retrieve conversations, your API key needs the logs ACL:

curl

curl -X GET "https://YOUR_APP_ID.algolia.net/agent-studio/1/agents/{agent_id}/conversations" \
  -H "X-Algolia-Application-Id: ALGOLIA_APP_ID" \
  -H "X-Algolia-API-Key: ALGOLIA_ADMIN_API_KEY"

curl -X GET "https://ALGOLIA_APP_ID.algolia.net/agent-studio/1/agents/{agent_id}/conversations/alg_cnv_support_12345" \
  -H "X-Algolia-Application-Id: ALGOLIA_APP_ID" \
  -H "X-Algolia-API-Key: ALGOLIA_ADMIN_API_KEY"

Limitations

• No user-specific retrieval: can’t retrieve conversations for a specific user. You get all conversations for the agent or none.
• Requires admin ACL: the logs ACL is needed for retrieval (admin-level access)
• Not suitable for multi-tenant apps: can’t isolate conversations by user
• Not recommended for multi-user apps: use authenticated conversations when you need to manage conversations per user

Security limitations

Unauthenticated conversations have no user association. The backend doesn’t track which user created a conversation or link conversations to user identities.

The only way to associate a conversation with a user is with the X-Algolia-Secure-User-Token header.

Conversations aren’t tied to any user.

Anyone with a conversation ID and proper API key can access it.

For multi-tenant SaaS apps, use authenticated conversations to enforce user-scoped data isolation.

Authenticated conversations with secure user tokens

Authenticated conversations link conversations to specific users, enabling user-scoped retrieval and management. This is the recommended approach for production apps.

Benefits

• User association: conversations are linked to authenticated users from the JWT
• User-specific retrieval: users can retrieve only their own conversations. They’re automatically filtered by user identity
• Multi-user support: enable personalized conversation history for each user in your application
• Memory integration: same user tokens work for both conversations and memory features
• Production-ready: a secure, scalable approach for multi-user apps

How to set up

Authenticated conversations require secure user tokens to link conversations to specific users.

For more information, see User authentication.

Send authenticated requests

Once you have set up user authentication, include the X-Algolia-Secure-User-Token header in your completion requests:

curl

# Send message with user authentication
curl -X POST "https://ALGOLIA_APP_ID.algolia.net/agent-studio/1/agents/{agent_id}/completions" \
  -H "X-Algolia-Application-Id: ALGOLIA_APP_ID" \
  -H "X-Algolia-API-Key: ALGOLIA_SEARCH_API_KEY" \
  -H "X-Algolia-Secure-User-Token: YOUR_SECURE_JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "alg_cnv_user_chat_001",
    "messages": [
      {
        "id": "alg_msg_user_001",
        "role": "user",
        "content": "Show me my recent orders"
      }
    ]
  }'

Retrieve user’s conversations

With a secure user token, users can retrieve only their own conversations (requires search ACL):

curl

curl -X GET "https://ALGOLIA_APP_ID.algolia.net/agent-studio/1/agents/{agent_id}/conversations" \
  -H "X-Algolia-Application-Id: ALGOLIA_APP_ID" \
  -H "X-Algolia-API-Key: YOUR_SEARCH_API_KEY" \
  -H "X-Algolia-Secure-User-Token: YOUR_SECURE_JWT"

curl -X GET "https://ALGOLIA_APP_ID.algolia.net/agent-studio/1/agents/{agent_id}/conversations/alg_cnv_user_chat_001" \
  -H "X-Algolia-Application-Id: ALGOLIA_APP_ID" \
  -H "X-Algolia-API-Key: ALGOLIA_SEARCH_API_KEY" \
  -H "X-Algolia-Secure-User-Token: YOUR_SECURE_JWT"

How user filtering works

When you provide the X-Algolia-Secure-User-Token header:

1. Token validation: a

Agent Studio validates the JWT signature using your secret key (HS256 algorithm) 2. User extraction: the user identifier is extracted from the token’s sub (subject) claim 3. User association:

• For creation: the backend links the conversation to the authenticated user from the JWT
• For retrieval: queries automatically return only conversations linked to that user identity

4. Automatic scoping: all conversation operations are scoped to the authenticated user—enforced server-side based on the cryptographically signed token

Why this approach is secure:

• User identity comes exclusively from the X-Algolia-Secure-User-Token header
• There’s no way to provide a user identifier in the request body or query parameters
• User identity can’t be manipulated by clients. It must come from a cryptographically signed JWT that only your backend can generate

ACL requirements by mode

Mode	API key ACL	User association	Retrieval scope
Authenticated	search	Linked to users	User-specific: retrieve by user identity
Unauthenticated	logs	No association	All-or-nothing: all conversations for the agent

Use authenticated mode with the search ACL for production environments. This enables user-specific conversation retrieval and avoids exposing admin-level API keys.

Retrieve conversation history

Agent Studio provides several endpoints to retrieve and manage conversation history.

List conversations

Retrieve a paginated list of conversations with optional date filtering:

curl

curl -X GET "https://ALGOLIA_APP_ID.algolia.net/agent-studio/1/agents/{agent_id}/conversations?page=1&limit=20&startDate=2024-01-01&endDate=2024-12-31" \
  -H "X-Algolia-Application-Id: ALGOLIA_APP_ID" \
  -H "X-Algolia-API-Key: ALGOLIA_SEARCH_API_KEY"

Response structure

JSON

{
  "data": [
    {
      "id": "alg_cnv_abc123",
      "title": "How do I reset my password?",
      "createdAt": "2024-11-20T10:30:00Z",
      "updatedAt": "2024-11-20T10:35:00Z",
      "messageCount": 8,
      "totalTokenCount": 1250,
      "metadata": {
        "agentVersion": "1.0",
        "user": "user_123"
      }
    }
  ],
  "pagination": {
    "page": 1,
    "totalPages": 5,
    "totalItems": 95,
    "itemsPerPage": 20
  }
}

Get single conversation

Retrieve a complete conversation including all messages:

curl

curl -X GET "https://ALGOLIA_APP_ID.algolia.net/agent-studio/1/agents/{agent_id}/conversations/{conversation_id}" \
  -H "X-Algolia-Application-Id: ALGOLIA_APP_ID" \
  -H "X-Algolia-API-Key: ALGOLIA_SEARCH_API_KEY"

Response includes:

• Conversation metadata (title, timestamps, token counts)
• All messages with roles, content, and tool calls
• Message IDs and timestamps
• Token usage per message

Manage retention and exports

Control retention and manage conversations in bulk with filtering, export, and deletion.

Retention policies

Conversations respect your app’s retention settings:

• 0 days: conversations are not persisted (ephemeral mode)
• 30 days: conversations are deleted after 30 days
• 60 days: conversations are deleted after 60 days
• 90 days: maximum retention period

When retention is 0, conversations are processed normally but not saved to the database. This is useful for apps that need real-time processing without persistence.

Agent Studio deletes conversations after the retention period expires. Export important conversations before they expire if you need long-term storage.

Filtering and export

Filter conversations by date range and export in bulk:

curl

curl -X GET "https://ALGOLIA_APP_ID.algolia.net/agent-studio/1/agents/{agent_id}/conversations/export?startDate=2024-01-01&endDate=2024-12-31" \
  -H "X-Algolia-Application-Id: ALGOLIA_APP_ID" \
  -H "X-Algolia-API-Key: ALGOLIA_ADMIN_API_KEY" \
  -o conversations_export.json

Bulk delete conversations matching filters:

curl

curl -X DELETE "https://ALGOLIA_APP_ID.algolia.net/agent-studio/1/agents/{agent_id}/conversations?startDate=2024-01-01&endDate=2024-01-31" \
  -H "X-Algolia-Application-Id: ALGOLIA_APP_ID" \
  -H "X-Algolia-API-Key: ALGOLIA_ADMIN_API_KEY"

Auto-generated titles

Agent Studio automatically generates conversation titles from the first user message:

• Maximum length: 60 characters
• Generation timing: titles are generated after the first user message.
• Fallback: if generation fails, the conversation ID is used as the title

You don’t need to provide titles manually: they’re created automatically to help users identify conversations in lists.

Integration with memory

Secure user tokens enable both conversations and memory features:

• Same authentication: one token works for both features
• User isolation: both conversations and memories are scoped to the authenticated user
• Unified experience: users get personalized agents with both conversation history and memory

When you set up secure user tokens for memory, conversation authentication works automatically.

See also

• How memory works and when to use it, see Memory overview
• Add Agent Studio to your app, see Integration
• Recommended security configuration, see Security