Conversations

Conversations save chat history for you. Agent Studio stores every completion request that includes messages. You can fetch the exchange later, including questions, answers, tool calls, and metadata. For example, a support agent can reopen a user’s troubleshooting session from yesterday. They can continue with the full context of what was already tried and discussed.

How conversations work

Persistence is automatic. You don’t need to send identifiers. If you omit them, Agent Studio generates a conversation ID and message IDs. It returns the conversation ID in the X-Conversation-Id response header. You can also supply your own IDs. This sets the storage key upfront, so you can reference it without reading the header. Agent Studio automatically:

Saves every completion request that includes messages, even when you don’t supply IDs.
Returns the stored conversation ID in the X-Conversation-Id response header.
Generates conversation titles from the first user message (60-character maximum).
Respects your app’s retention policies (0, 30, 60, or 90 days).
Supports unauthenticated access, which needs an API key with the logs ACL.
Supports authenticated access, which is user-scoped with a secure JWT.

Control the conversation ID

To set the storage key, add a conversation ID and message IDs to 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 optional:

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

If you omit either property, Agent Studio generates it. It also returns the conversation ID in the X-Conversation-Id response header.

Unauthenticated conversations

Unauthenticated conversations offer basic persistence without user authentication. Conversations aren’t associated with a user identity: retrieve them with their conversation ID. This approach works well for testing and internal admin tools. It also suits single-tenant apps without user accounts.

When to use

Apps without a backend for authentication: when your app doesn’t have a backend to create secure user tokens.
Single-tenant apps: all users share the same data, so you don’t need to isolate them.
Internal admin tools: where all users have full access to all conversations.
Development and testing: for testing without setting up authentication.
Prototypes and demos: for proof-of-concept work.

How authenticated scoping works

Include the conversation and message IDs in your request. You don’t need any extra authentication:

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_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 -X GET "https://$ALGOLIA_APPLICATION_ID.algolia.net/agent-studio/1/agents/$AGENT_ID/conversations" \
  -H "X-Algolia-Application-Id: $ALGOLIA_APPLICATION_ID" \
  -H "X-Algolia-API-Key: $ALGOLIA_API_KEY"

curl -X GET "https://$ALGOLIA_APPLICATION_ID.algolia.net/agent-studio/1/agents/$AGENT_ID/conversations/alg_cnv_support_12345" \
  -H "X-Algolia-Application-Id: $ALGOLIA_APPLICATION_ID" \
  -H "X-Algolia-API-Key: $ALGOLIA_API_KEY"

Limitations

No user-specific retrieval: can’t get conversations for one user. You get every conversation for the agent, or none.
Requires the logs ACL which grants admin-level access.
Not suitable for multi-tenant apps: can’t isolate conversations by user.
Not recommended for multi-user apps: use authenticated conversations to manage them per user.

Security limitations

Since unauthenticated conversations aren’t associated with user identities, Agent Studio can’t determine which user created them. To associate conversations with users, use authenticated conversations with the X-Algolia-Secure-User-Token header. 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

Authentication links each conversation to a specific user. This enables user-scoped retrieval and management. For production apps, use authenticated conversations.

Benefits

User scope: the JWT links conversations to authenticated users.
User-specific retrieval: users can retrieve only their own conversations. The system filters by user ID.
Multi-user support: each user in your app gets their own conversation history.
Memory integration: the same user tokens work for both conversations and memory features.

How to set up

Authenticated conversations need secure user tokens. These tokens 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:

# Send message with user authentication
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_SEARCH_API_KEY" \
  -H "X-Algolia-Secure-User-Token: $SECURE_USER_TOKEN" \
  -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 -X GET "https://$ALGOLIA_APPLICATION_ID.algolia.net/agent-studio/1/agents/$AGENT_ID/conversations" \
  -H "X-Algolia-Application-Id: $ALGOLIA_APPLICATION_ID" \
  -H "X-Algolia-API-Key: $ALGOLIA_SEARCH_API_KEY" \
  -H "X-Algolia-Secure-User-Token: $SECURE_JWT_TOKEN"

curl -X GET "https://$ALGOLIA_APPLICATION_ID.algolia.net/agent-studio/1/agents/$AGENT_ID/conversations/alg_cnv_user_chat_001" \
  -H "X-Algolia-Application-Id: $ALGOLIA_APPLICATION_ID" \
  -H "X-Algolia-API-Key: $ALGOLIA_SEARCH_API_KEY" \
  -H "X-Algolia-Secure-User-Token: $SECURE_JWT_TOKEN"

How user filtering works

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

Token validation: Agent Studio validates the JWT signature using your secret key (HS256 algorithm).
User extraction: Agent Studio extracts the user ID from the token’s sub (subject) claim.
User scope:
- For creation: the backend links the conversation to the authenticated user from the JWT.
- For retrieval: queries return only conversations linked to that user ID.
Automatic scoping: the server scopes every conversation operation to the authenticated user. This relies on the signed token.

Why this approach is secure:

User identity comes only from the X-Algolia-Secure-User-Token header.
There’s no way to provide a user ID in the request body or query parameters.
Clients can’t provide an arbitrary user ID. It must come from a signed JWT that only your backend can create.

ACL requirements by mode

Mode	API key ACL	User link	Retrieval scope
Authenticated	`search`	Linked to users	User-specific: retrieve by user ID
Unauthenticated	`logs`	No link	Retrieves all conversations for the agent

Use authenticated mode with the search ACL for production apps. This lets you scope retrieval by user and avoid 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 -X GET "https://$ALGOLIA_APPLICATION_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_APPLICATION_ID" \
  -H "X-Algolia-API-Key: $ALGOLIA_SEARCH_API_KEY"

Response structure

JSON

{
  "data": [
    {
      "id": "alg_cnv_abc123",
      "agentId": "b3f1c2d4-5e6f-7a8b-9c0d-1e2f3a4b5c6d",
      "title": "How do I reset my password?",
      "createdAt": "2024-11-20T10:30:00Z",
      "updatedAt": "2024-11-20T10:35:00Z",
      "lastActivityAt": "2024-11-20T10:35:00Z",
      "userToken": "user_123",
      "isFromDashboard": false,
      "messageCount": 8,
      "totalInputTokens": 950,
      "totalOutputTokens": 300,
      "totalTokens": 1250,
      "conversationMetadata": null,
      "feedback": null
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "totalCount": 95,
    "totalPages": 5
  }
}

Get single conversation

Retrieve a complete conversation including all messages:

curl -X GET "https://$ALGOLIA_APPLICATION_ID.algolia.net/agent-studio/1/agents/$AGENT_ID/conversations/$CONVERSATION_ID" \
  -H "X-Algolia-Application-Id: $ALGOLIA_APPLICATION_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 setting: 0, 30, 60, or 90 days. Agent Studio deletes conversations when the retention period expires. Export conversations you need to keep before then. With a retention of 0 days, Agent Studio processes conversations as normal but doesn’t store them. Use this for apps that need real-time processing without persistence.

Filtering and export

Filter conversations by date range and export in bulk:

curl -X GET "https://$ALGOLIA_APPLICATION_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_APPLICATION_ID" \
  -H "X-Algolia-API-Key: $ALGOLIA_API_KEY" \
  -o conversations_export.json

Bulk delete conversations matching filters:

curl -X DELETE "https://$ALGOLIA_APPLICATION_ID.algolia.net/agent-studio/1/agents/$AGENT_ID/conversations?startDate=2024-01-01&endDate=2024-01-31" \
  -H "X-Algolia-Application-Id: $ALGOLIA_APPLICATION_ID" \
  -H "X-Algolia-API-Key: $ALGOLIA_API_KEY"

Auto-generated titles

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

Maximum length: 60 characters.
Generation timing: Agent Studio generates titles after the first user message.
Fallback: if generation fails, the title falls back to the conversation ID.

You don’t need to provide conversation titles. Agent Studio creates them 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: Agent Studio scopes both conversations and memories to the authenticated user.
Unified experience: users get custom agents with both conversation history and memory.

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

Search and Discovery platform

Optimization and Personalization

AI-powered experiences

Production and scale

How conversations work

Control the conversation ID

Unauthenticated conversations

When to use

How authenticated scoping works

Limitations

Security limitations

Authenticated conversations with secure user tokens

Benefits

How to set up

Send authenticated requests

Retrieve user’s conversations

How user filtering works

ACL requirements by mode

Retrieve conversation history

List conversations

Response structure

Get single conversation

Manage retention and exports

Retention policies

Filtering and export

Auto-generated titles

Integration with memory

See also

​How conversations work

​Control the conversation ID

​Unauthenticated conversations

​When to use

​How authenticated scoping works

​Limitations

​Security limitations

​Authenticated conversations with secure user tokens

​Benefits

​How to set up

​Send authenticated requests

​Retrieve user’s conversations

​How user filtering works

​ACL requirements by mode

​Retrieve conversation history

​List conversations

​Response structure

​Get single conversation

​Manage retention and exports

​Retention policies

​Filtering and export

​Auto-generated titles

​Integration with memory

​See also

How conversations work

Control the conversation ID

Unauthenticated conversations

When to use

How authenticated scoping works

Limitations

Security limitations

Authenticated conversations with secure user tokens

Benefits

How to set up

Send authenticated requests

Retrieve user’s conversations

How user filtering works

ACL requirements by mode

Retrieve conversation history

List conversations

Response structure

Get single conversation

Manage retention and exports

Retention policies

Filtering and export

Auto-generated titles

Integration with memory

See also