White-listed arguments from the completion API













Beta Conversations Endpoints
(beta) Conversations API












Examples
Real world code examples
List all created conversations.
GET /v1/conversations
Retrieve a list of conversation entities sorted by creation time.
page
page_size
metadata
200
Successful Response
ModelConversation
AgentConversation
Playground
Test the endpoints live
import { Mistral } from "@mistralai/mistralai";
const mistral = new Mistral({
apiKey: "MISTRAL_API_KEY",
});
async function run() {
const result = await mistral.beta.conversations.list({});
console.log(result);
}
run();
import { Mistral } from "@mistralai/mistralai";
const mistral = new Mistral({
apiKey: "MISTRAL_API_KEY",
});
async function run() {
const result = await mistral.beta.conversations.list({});
console.log(result);
}
run();
from mistralai.client import Mistral
import os
with Mistral(
api_key=os.getenv("MISTRAL_API_KEY", ""),
) as mistral:
res = mistral.beta.conversations.list(page=0, page_size=100)
# Handle response
print(res)
from mistralai.client import Mistral
import os
with Mistral(
api_key=os.getenv("MISTRAL_API_KEY", ""),
) as mistral:
res = mistral.beta.conversations.list(page=0, page_size=100)
# Handle response
print(res)
curl https://api.mistral.ai/v1/conversations \
-X GET \
-H 'Authorization: Bearer YOUR_APIKEY_HERE'curl https://api.mistral.ai/v1/conversations \
-X GET \
-H 'Authorization: Bearer YOUR_APIKEY_HERE'200
[
{
"created_at": "2025-12-17T10:25:07.818693Z",
"id": "019b2bd7-96e7-7219-8c0b-45a73da50088",
"model": "mistral-small-latest",
"updated_at": "2025-12-17T10:41:03.469341Z"
}
][
{
"created_at": "2025-12-17T10:25:07.818693Z",
"id": "019b2bd7-96e7-7219-8c0b-45a73da50088",
"model": "mistral-small-latest",
"updated_at": "2025-12-17T10:41:03.469341Z"
}
]Create a conversation and append entries to it.
POST /v1/conversations
Create a new conversation, using a base model or an agent and append entries. Completion and tool executions are run and the response is appended to the conversation.Use the returned conversation_id to continue the conversation.
agent_id
agent_version
description
guardrails
handoff_execution
instructions
metadata
model
name
store
stream
Default Value: false
200
Successful Response
conversation_id
guardrails
object
Default Value: "conversation.response"
Playground
Test the endpoints live
import { Mistral } from "@mistralai/mistralai";
const client = new Mistral({ apiKey: process.env.MISTRAL_API_KEY });
const conversation = await client.beta.conversations.start({
inputs: "Help me summarize this document.",
});
console.log(conversation.id);
import { Mistral } from "@mistralai/mistralai";
const client = new Mistral({ apiKey: process.env.MISTRAL_API_KEY });
const conversation = await client.beta.conversations.start({
inputs: "Help me summarize this document.",
});
console.log(conversation.id);
import os
from mistralai import Mistral
client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])
conversation = client.beta.conversations.start(
inputs="Help me summarize this document.",
stream=False,
)
print(conversation.id)
import os
from mistralai import Mistral
client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])
conversation = client.beta.conversations.start(
inputs="Help me summarize this document.",
stream=False,
)
print(conversation.id)
curl https://api.mistral.ai/v1/conversations \
-X POST \
-H 'Authorization: Bearer YOUR_APIKEY_HERE' \
-H 'Content-Type: application/json' \
-d '{
"inputs": "Example input."
}'curl https://api.mistral.ai/v1/conversations \
-X POST \
-H 'Authorization: Bearer YOUR_APIKEY_HERE' \
-H 'Content-Type: application/json' \
-d '{
"inputs": "Example input."
}'200
{
"conversation_id": "019b2bd7-96e7-7219-8c0b-45a73da50088",
"outputs": [
{
"content": "Example content."
}
],
"usage": {}
}{
"conversation_id": "019b2bd7-96e7-7219-8c0b-45a73da50088",
"outputs": [
{
"content": "Example content."
}
],
"usage": {}
}Retrieve a conversation information.
GET /v1/conversations/{conversation_id}
Given a conversation_id retrieve a conversation entity with its attributes.
conversation_id
ID of the conversation from which we are fetching metadata.
200
Successful Response
ModelConversation
AgentConversation
Playground
Test the endpoints live
import { Mistral } from "@mistralai/mistralai";
const mistral = new Mistral({
apiKey: "MISTRAL_API_KEY",
});
async function run() {
const result = await mistral.beta.conversations.get({
conversationId: "<id>",
});
console.log(result);
}
run();
import { Mistral } from "@mistralai/mistralai";
const mistral = new Mistral({
apiKey: "MISTRAL_API_KEY",
});
async function run() {
const result = await mistral.beta.conversations.get({
conversationId: "<id>",
});
console.log(result);
}
run();
from mistralai.client import Mistral
import os
with Mistral(
api_key=os.getenv("MISTRAL_API_KEY", ""),
) as mistral:
res = mistral.beta.conversations.get(conversation_id="<id>")
# Handle response
print(res)
from mistralai.client import Mistral
import os
with Mistral(
api_key=os.getenv("MISTRAL_API_KEY", ""),
) as mistral:
res = mistral.beta.conversations.get(conversation_id="<id>")
# Handle response
print(res)
curl https://api.mistral.ai/v1/conversations/{conversation_id} \
-X GET \
-H 'Authorization: Bearer YOUR_APIKEY_HERE'curl https://api.mistral.ai/v1/conversations/{conversation_id} \
-X GET \
-H 'Authorization: Bearer YOUR_APIKEY_HERE'200
{
"created_at": "2025-12-17T10:25:07.818693Z",
"id": "019b2bd7-96e7-7219-8c0b-45a73da50088",
"model": "mistral-small-latest",
"updated_at": "2025-12-17T10:41:03.469341Z"
}{
"created_at": "2025-12-17T10:25:07.818693Z",
"id": "019b2bd7-96e7-7219-8c0b-45a73da50088",
"model": "mistral-small-latest",
"updated_at": "2025-12-17T10:41:03.469341Z"
}Append new entries to an existing conversation.
POST /v1/conversations/{conversation_id}
Run completion on the history of the conversation and the user entries. Return the new created entries.
conversation_id
ID of the conversation to which we append entries.
handoff_execution
Default Value: "server"
store
Default Value: true
Whether to store the results into our servers or not.
stream
Default Value: false
tool_confirmations
200
Successful Response
conversation_id
guardrails
object
Default Value: "conversation.response"
Playground
Test the endpoints live
import { Mistral } from "@mistralai/mistralai";
const mistral = new Mistral({
apiKey: "MISTRAL_API_KEY",
});
async function run() {
const result = await mistral.beta.conversations.append({
conversationId: "<id>",
conversationAppendRequest: {
inputs: [],
},
});
console.log(result);
}
run();
import { Mistral } from "@mistralai/mistralai";
const mistral = new Mistral({
apiKey: "MISTRAL_API_KEY",
});
async function run() {
const result = await mistral.beta.conversations.append({
conversationId: "<id>",
conversationAppendRequest: {
inputs: [],
},
});
console.log(result);
}
run();
from mistralai.client import Mistral
import os
with Mistral(
api_key=os.getenv("MISTRAL_API_KEY", ""),
) as mistral:
res = mistral.beta.conversations.append(conversation_id="<id>", stream=False, store=True, handoff_execution="server", completion_args={
"response_format": {
"type": "text",
},
})
# Handle response
print(res)
from mistralai.client import Mistral
import os
with Mistral(
api_key=os.getenv("MISTRAL_API_KEY", ""),
) as mistral:
res = mistral.beta.conversations.append(conversation_id="<id>", stream=False, store=True, handoff_execution="server", completion_args={
"response_format": {
"type": "text",
},
})
# Handle response
print(res)
curl https://api.mistral.ai/v1/conversations/{conversation_id} \
-X POST \
-H 'Authorization: Bearer YOUR_APIKEY_HERE' \
-H 'Content-Type: application/json' \
-d '{}'curl https://api.mistral.ai/v1/conversations/{conversation_id} \
-X POST \
-H 'Authorization: Bearer YOUR_APIKEY_HERE' \
-H 'Content-Type: application/json' \
-d '{}'200
{
"conversation_id": "019b2bd7-96e7-7219-8c0b-45a73da50088",
"outputs": [
{
"content": "Example content."
}
],
"usage": {}
}{
"conversation_id": "019b2bd7-96e7-7219-8c0b-45a73da50088",
"outputs": [
{
"content": "Example content."
}
],
"usage": {}
}Delete a conversation.
DELETE /v1/conversations/{conversation_id}
Delete a conversation given a conversation_id.
conversation_id
ID of the conversation from which we are fetching metadata.
Playground
Test the endpoints live
from mistralai.client import Mistral
import os
with Mistral(
api_key=os.getenv("MISTRAL_API_KEY", ""),
) as mistral:
mistral.beta.conversations.delete(conversation_id="<id>")
# Use the SDK ...
from mistralai.client import Mistral
import os
with Mistral(
api_key=os.getenv("MISTRAL_API_KEY", ""),
) as mistral:
mistral.beta.conversations.delete(conversation_id="<id>")
# Use the SDK ...
curl https://api.mistral.ai/v1/conversations/{conversation_id} \
-X DELETE \
-H 'Authorization: Bearer YOUR_APIKEY_HERE' \
-H 'Content-Type: application/json'curl https://api.mistral.ai/v1/conversations/{conversation_id} \
-X DELETE \
-H 'Authorization: Bearer YOUR_APIKEY_HERE' \
-H 'Content-Type: application/json'Retrieve all entries in a conversation.
GET /v1/conversations/{conversation_id}/history
Given a conversation_id retrieve all the entries belonging to that conversation. The entries are sorted in the order they were appended, those can be messages, connectors or function_call.
conversation_id
ID of the conversation from which we are fetching entries.
200
Successful Response
conversation_id
object
Default Value: "conversation.history"
Playground
Test the endpoints live
import { Mistral } from "@mistralai/mistralai";
const mistral = new Mistral({
apiKey: "MISTRAL_API_KEY",
});
async function run() {
const result = await mistral.beta.conversations.getHistory({
conversationId: "<id>",
});
console.log(result);
}
run();
import { Mistral } from "@mistralai/mistralai";
const mistral = new Mistral({
apiKey: "MISTRAL_API_KEY",
});
async function run() {
const result = await mistral.beta.conversations.getHistory({
conversationId: "<id>",
});
console.log(result);
}
run();
from mistralai.client import Mistral
import os
with Mistral(
api_key=os.getenv("MISTRAL_API_KEY", ""),
) as mistral:
res = mistral.beta.conversations.get_history(conversation_id="<id>")
# Handle response
print(res)
from mistralai.client import Mistral
import os
with Mistral(
api_key=os.getenv("MISTRAL_API_KEY", ""),
) as mistral:
res = mistral.beta.conversations.get_history(conversation_id="<id>")
# Handle response
print(res)
curl https://api.mistral.ai/v1/conversations/{conversation_id}/history \
-X GET \
-H 'Authorization: Bearer YOUR_APIKEY_HERE'curl https://api.mistral.ai/v1/conversations/{conversation_id}/history \
-X GET \
-H 'Authorization: Bearer YOUR_APIKEY_HERE'200
{
"conversation_id": "019b2bd7-96e7-7219-8c0b-45a73da50088",
"entries": [
{
"content": "Example content.",
"role": "assistant"
}
]
}{
"conversation_id": "019b2bd7-96e7-7219-8c0b-45a73da50088",
"entries": [
{
"content": "Example content.",
"role": "assistant"
}
]
}Retrieve all messages in a conversation.
GET /v1/conversations/{conversation_id}/messages
Given a conversation_id retrieve all the messages belonging to that conversation. This is similar to retrieving all entries except we filter the messages only.
conversation_id
ID of the conversation from which we are fetching messages.
200
Successful Response
conversation_id
object
Default Value: "conversation.messages"
Playground
Test the endpoints live
import { Mistral } from "@mistralai/mistralai";
const mistral = new Mistral({
apiKey: "MISTRAL_API_KEY",
});
async function run() {
const result = await mistral.beta.conversations.getMessages({
conversationId: "<id>",
});
console.log(result);
}
run();
import { Mistral } from "@mistralai/mistralai";
const mistral = new Mistral({
apiKey: "MISTRAL_API_KEY",
});
async function run() {
const result = await mistral.beta.conversations.getMessages({
conversationId: "<id>",
});
console.log(result);
}
run();
from mistralai.client import Mistral
import os
with Mistral(
api_key=os.getenv("MISTRAL_API_KEY", ""),
) as mistral:
res = mistral.beta.conversations.get_messages(conversation_id="<id>")
# Handle response
print(res)
from mistralai.client import Mistral
import os
with Mistral(
api_key=os.getenv("MISTRAL_API_KEY", ""),
) as mistral:
res = mistral.beta.conversations.get_messages(conversation_id="<id>")
# Handle response
print(res)
curl https://api.mistral.ai/v1/conversations/{conversation_id}/messages \
-X GET \
-H 'Authorization: Bearer YOUR_APIKEY_HERE'curl https://api.mistral.ai/v1/conversations/{conversation_id}/messages \
-X GET \
-H 'Authorization: Bearer YOUR_APIKEY_HERE'200
{
"conversation_id": "019b2bd7-96e7-7219-8c0b-45a73da50088",
"messages": [
{
"content": "Example content.",
"role": "assistant"
}
]
}{
"conversation_id": "019b2bd7-96e7-7219-8c0b-45a73da50088",
"messages": [
{
"content": "Example content.",
"role": "assistant"
}
]
}Restart a conversation starting from a given entry.
POST /v1/conversations/{conversation_id}/restart
Given a conversation_id and an id, recreate a conversation from this point and run completion. A new conversation is returned with the new entries returned.
conversation_id
ID of the original conversation which is being restarted.
Request to restart a new conversation from a given entry in the conversation.
agent_version
Specific version of the agent to use when restarting. If not provided, uses the current version.
from_entry_id
guardrails
handoff_execution
Default Value: "server"
metadata
Custom metadata for the conversation.
store
Default Value: true
Whether to store the results into our servers or not.
stream
Default Value: false
200
Successful Response
conversation_id
guardrails
object
Default Value: "conversation.response"
Playground
Test the endpoints live
import { Mistral } from "@mistralai/mistralai";
const client = new Mistral({ apiKey: process.env.MISTRAL_API_KEY });
const conversation = await client.beta.conversations.restart({
conversationId: "019b2bd7-96e7-7219-8c0b-45a73da50088",
conversationRestartRequest: {
inputs: "Start again from this message.",
fromEntryId: "019b2bd7-96e7-7219-8c0b-45a73da50088",
},
});
console.log(conversation.id);
import { Mistral } from "@mistralai/mistralai";
const client = new Mistral({ apiKey: process.env.MISTRAL_API_KEY });
const conversation = await client.beta.conversations.restart({
conversationId: "019b2bd7-96e7-7219-8c0b-45a73da50088",
conversationRestartRequest: {
inputs: "Start again from this message.",
fromEntryId: "019b2bd7-96e7-7219-8c0b-45a73da50088",
},
});
console.log(conversation.id);
import os
from mistralai import Mistral
client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])
conversation = client.beta.conversations.restart(
conversation_id="019b2bd7-96e7-7219-8c0b-45a73da50088",
inputs="Start again from this message.",
from_entry_id="019b2bd7-96e7-7219-8c0b-45a73da50088",
stream=False,
)
print(conversation.id)
import os
from mistralai import Mistral
client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])
conversation = client.beta.conversations.restart(
conversation_id="019b2bd7-96e7-7219-8c0b-45a73da50088",
inputs="Start again from this message.",
from_entry_id="019b2bd7-96e7-7219-8c0b-45a73da50088",
stream=False,
)
print(conversation.id)
curl https://api.mistral.ai/v1/conversations/{conversation_id}/restart \
-X POST \
-H 'Authorization: Bearer YOUR_APIKEY_HERE' \
-H 'Content-Type: application/json' \
-d '{
"from_entry_id": "019b2bd7-96e7-7219-8c0b-45a73da50088"
}'curl https://api.mistral.ai/v1/conversations/{conversation_id}/restart \
-X POST \
-H 'Authorization: Bearer YOUR_APIKEY_HERE' \
-H 'Content-Type: application/json' \
-d '{
"from_entry_id": "019b2bd7-96e7-7219-8c0b-45a73da50088"
}'200
{
"conversation_id": "019b2bd7-96e7-7219-8c0b-45a73da50088",
"outputs": [
{
"content": "Example content."
}
],
"usage": {}
}{
"conversation_id": "019b2bd7-96e7-7219-8c0b-45a73da50088",
"outputs": [
{
"content": "Example content."
}
],
"usage": {}
}Create a conversation and append entries to it.
POST /v1/conversations#stream
Create a new conversation, using a base model or an agent and append entries. Completion and tool executions are run and the response is appended to the conversation.Use the returned conversation_id to continue the conversation.
agent_id
agent_version
description
guardrails
handoff_execution
instructions
metadata
model
name
store
stream
Default Value: true
200
Playground
Test the endpoints live
import { Mistral } from "@mistralai/mistralai";
const client = new Mistral({ apiKey: process.env.MISTRAL_API_KEY });
const events = await client.beta.conversations.startStream({
inputs: "Help me summarize this document.",
});
for await (const event of events) {
console.log(event);
}
import { Mistral } from "@mistralai/mistralai";
const client = new Mistral({ apiKey: process.env.MISTRAL_API_KEY });
const events = await client.beta.conversations.startStream({
inputs: "Help me summarize this document.",
});
for await (const event of events) {
console.log(event);
}
import os
from mistralai import Mistral
client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])
with client.beta.conversations.start_stream(
inputs="Help me summarize this document.",
) as events:
for event in events:
print(event)
import os
from mistralai import Mistral
client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])
with client.beta.conversations.start_stream(
inputs="Help me summarize this document.",
) as events:
for event in events:
print(event)
curl https://api.mistral.ai/v1/conversations#stream \
-X POST \
-H 'Authorization: Bearer YOUR_APIKEY_HERE' \
-H 'Content-Type: application/json' \
-d '{
"inputs": "Example input."
}'curl https://api.mistral.ai/v1/conversations#stream \
-X POST \
-H 'Authorization: Bearer YOUR_APIKEY_HERE' \
-H 'Content-Type: application/json' \
-d '{
"inputs": "Example input."
}'200
nullnullAppend new entries to an existing conversation.
POST /v1/conversations/{conversation_id}#stream
Run completion on the history of the conversation and the user entries. Return the new created entries.
conversation_id
ID of the conversation to which we append entries.
handoff_execution
Default Value: "server"
store
Default Value: true
Whether to store the results into our servers or not.
stream
Default Value: true
tool_confirmations
200
Playground
Test the endpoints live
import { Mistral } from "@mistralai/mistralai";
const client = new Mistral({ apiKey: process.env.MISTRAL_API_KEY });
const events = await client.beta.conversations.appendStream({
conversationId: "019b2bd7-96e7-7219-8c0b-45a73da50088",
conversationAppendStreamRequest: {
inputs: "Continue with more detail.",
},
});
for await (const event of events) {
console.log(event);
}
import { Mistral } from "@mistralai/mistralai";
const client = new Mistral({ apiKey: process.env.MISTRAL_API_KEY });
const events = await client.beta.conversations.appendStream({
conversationId: "019b2bd7-96e7-7219-8c0b-45a73da50088",
conversationAppendStreamRequest: {
inputs: "Continue with more detail.",
},
});
for await (const event of events) {
console.log(event);
}
import os
from mistralai import Mistral
client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])
with client.beta.conversations.append_stream(
conversation_id="019b2bd7-96e7-7219-8c0b-45a73da50088",
inputs="Continue with more detail.",
) as events:
for event in events:
print(event)
import os
from mistralai import Mistral
client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])
with client.beta.conversations.append_stream(
conversation_id="019b2bd7-96e7-7219-8c0b-45a73da50088",
inputs="Continue with more detail.",
) as events:
for event in events:
print(event)
curl https://api.mistral.ai/v1/conversations/{conversation_id}#stream \
-X POST \
-H 'Authorization: Bearer YOUR_APIKEY_HERE' \
-H 'Content-Type: application/json' \
-d '{}'curl https://api.mistral.ai/v1/conversations/{conversation_id}#stream \
-X POST \
-H 'Authorization: Bearer YOUR_APIKEY_HERE' \
-H 'Content-Type: application/json' \
-d '{}'200
nullnullRestart a conversation starting from a given entry.
POST /v1/conversations/{conversation_id}/restart#stream
Given a conversation_id and an id, recreate a conversation from this point and run completion. A new conversation is returned with the new entries returned.
conversation_id
ID of the original conversation which is being restarted.
Request to restart a new conversation from a given entry in the conversation.
agent_version
Specific version of the agent to use when restarting. If not provided, uses the current version.
from_entry_id
guardrails
handoff_execution
Default Value: "server"
metadata
Custom metadata for the conversation.
store
Default Value: true
Whether to store the results into our servers or not.
stream
Default Value: true
200
Playground
Test the endpoints live
import { Mistral } from "@mistralai/mistralai";
const client = new Mistral({ apiKey: process.env.MISTRAL_API_KEY });
const events = await client.beta.conversations.restartStream({
conversationId: "019b2bd7-96e7-7219-8c0b-45a73da50088",
conversationRestartStreamRequest: {
inputs: "Restart and stream the answer.",
fromEntryId: "019b2bd7-96e7-7219-8c0b-45a73da50088",
},
});
for await (const event of events) {
console.log(event);
}
import { Mistral } from "@mistralai/mistralai";
const client = new Mistral({ apiKey: process.env.MISTRAL_API_KEY });
const events = await client.beta.conversations.restartStream({
conversationId: "019b2bd7-96e7-7219-8c0b-45a73da50088",
conversationRestartStreamRequest: {
inputs: "Restart and stream the answer.",
fromEntryId: "019b2bd7-96e7-7219-8c0b-45a73da50088",
},
});
for await (const event of events) {
console.log(event);
}
import os
from mistralai import Mistral
client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])
with client.beta.conversations.restart_stream(
conversation_id="019b2bd7-96e7-7219-8c0b-45a73da50088",
inputs="Restart and stream the answer.",
from_entry_id="019b2bd7-96e7-7219-8c0b-45a73da50088",
) as events:
for event in events:
print(event)
import os
from mistralai import Mistral
client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])
with client.beta.conversations.restart_stream(
conversation_id="019b2bd7-96e7-7219-8c0b-45a73da50088",
inputs="Restart and stream the answer.",
from_entry_id="019b2bd7-96e7-7219-8c0b-45a73da50088",
) as events:
for event in events:
print(event)
curl https://api.mistral.ai/v1/conversations/{conversation_id}/restart#stream \
-X POST \
-H 'Authorization: Bearer YOUR_APIKEY_HERE' \
-H 'Content-Type: application/json' \
-d '{
"from_entry_id": "019b2bd7-96e7-7219-8c0b-45a73da50088"
}'curl https://api.mistral.ai/v1/conversations/{conversation_id}/restart#stream \
-X POST \
-H 'Authorization: Bearer YOUR_APIKEY_HERE' \
-H 'Content-Type: application/json' \
-d '{
"from_entry_id": "019b2bd7-96e7-7219-8c0b-45a73da50088"
}'200
nullnull