Conversations and end users

Every answer you get through an API key, the CLI or the MCP server is kept in a conversation. Ask the next question with the previous answer’s conversation_id and Lookio reads the history itself: you send only the new question.

This page is for products that put an assistant in front of their own users. A person’s chats in the app are a different thing: they are personal. See Chat.

Continue a conversation

The first answer returns two ids. conversation_id continues the conversation. message_id is the answer’s own id, the one you need to forward a thumb.

# First question
curl https://api.lookio.app/v1/assistants/ASSISTANT_ID/query \
  -H "Authorization: Bearer $LOOKIO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"question": "How much does the Pro plan cost?", "end_user": "user_42"}'

# The answer has "conversation_id": "CONVERSATION_ID" and "message_id": "MESSAGE_ID".
# Follow-up: only the new question.
curl https://api.lookio.app/v1/assistants/ASSISTANT_ID/query \
  -H "Authorization: Bearer $LOOKIO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"question": "And for the annual plan?", "conversation_id": "CONVERSATION_ID", "end_user": "user_42"}'

const first = await lookio.assistants.ask("ASSISTANT_ID", {
  question: "How much does the Pro plan cost?",
  end_user: "user_42",
});
const followUp = await lookio.assistants.ask("ASSISTANT_ID", {
  question: "And for the annual plan?",
  conversationId: first.conversation_id!,
  end_user: "user_42",
});

lookio ask ASSISTANT_ID "How much does the Pro plan cost?" --end-user user_42
lookio ask ASSISTANT_ID "And for the annual plan?" --conversation CONVERSATION_ID --end-user user_42

The MCP tool ask_assistant takes the same conversation_id, end_user and store. The streamed answer returns both ids in its done event: see Streaming.

A conversation:

• belongs to the API key that started it. Another key, even in the same workspace, gets resource_not_found.
• stays with one assistant. Asking another assistant with that conversation_id gets resource_not_found.
• uses the last six turns as context, the same as a chat in the app.

Two ways to keep a conversation

Sending both conversation_id and history fails with invalid_request.

Name the people who use your product with end_user

end_user is your own id for the person asking, such as a user id of your product. It is optional.

• It is 1 to 200 characters: letters, digits and . _ @ : + -. Anything else fails with invalid_parameter.
• Prefer an opaque id such as user_42 to an email address. The id appears in your workspace’s logs.
• It groups that person’s conversations. List them with GET /v1/conversations?end_user=user_42.
• It binds the conversation. A conversation started with end_user: "user_42" can only be continued, read, renamed, deleted or rated by a call that sends the same end_user. Another one gets resource_not_found. Your backend can rely on this to stop one of your users from opening another’s conversation, even if an id leaks.
• A conversation started without end_user is reached only by calls that send none, and a call that sends end_user reaches only that person’s conversations. Pick one habit for a product and keep it.

end_user and store are for API keys. A person’s connection that sends them gets invalid_parameter, rather than having them silently ignored.

Keep nothing with store false

Send store: false for a question that must not be kept. Nothing is written: no conversation, no entry in the logs, and conversation_id and message_id come back null. You are charged the same, and the answer cannot be continued with conversation_id. Bring the previous turns yourself in history if you need a follow-up.

store: false cannot be combined with conversation_id: a conversation you want to continue is a conversation you keep.

How long it is kept

Lookio deletes a conversation 90 days after its last message. A new message restarts that clock. You can delete one earlier with DELETE /v1/conversations/{conversation_id}, which also removes it from the workspace’s logs and figures: nobody can read it afterwards. To honour a user’s request to erase their data, list their conversations with end_user and delete each one.

Who can read a kept conversation:

• you, with the API key that started it (the endpoints below);
• the people of the workspace who may read the logs.

Members’ own chats are never in the logs.

Read and tidy your key’s conversations

Each row has an MCP tool with the same job: see Standard tools. Every conversation has a channel: api for a key through REST, the CLI or the SDK, mcp for a key through the MCP server, and personal for a person’s own chat. A key lists only its own.

Errors you may meet