Beta Agents Endpoints

(beta) Agents API

List agent entities.

GET /v1/agents

Retrieve a list of agent entities sorted by creation time.

200

Response Type

array<Agent>

Successful Response

Agent

{object}

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.agents.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.agents.list({});

  console.log(result);
}

run();

from mistralai import Mistral
import os


with Mistral(
    api_key=os.getenv("MISTRAL_API_KEY", ""),
) as mistral:

    res = mistral.beta.agents.list(page=0, page_size=20)

    # Handle response
    print(res)

from mistralai import Mistral
import os


with Mistral(
    api_key=os.getenv("MISTRAL_API_KEY", ""),
) as mistral:

    res = mistral.beta.agents.list(page=0, page_size=20)

    # Handle response
    print(res)

curl https://api.mistral.ai/v1/agents \
 -X GET \
 -H 'Authorization: Bearer YOUR_APIKEY_HERE'

curl https://api.mistral.ai/v1/agents \
 -X GET \
 -H 'Authorization: Bearer YOUR_APIKEY_HERE'

200

[
  {
    "created_at": "2025-10-07T20:56:01.974Z",
    "deployment_chat": false,
    "id": "ipsum eiusmod",
    "model": "consequat do",
    "name": "reprehenderit ut dolore",
    "source": "occaecat dolor sit",
    "updated_at": "2025-10-07T20:56:01.974Z",
    "version": 87,
    "versions": [
      14
    ]
  }
]

[
  {
    "created_at": "2025-10-07T20:56:01.974Z",
    "deployment_chat": false,
    "id": "ipsum eiusmod",
    "model": "consequat do",
    "name": "reprehenderit ut dolore",
    "source": "occaecat dolor sit",
    "updated_at": "2025-10-07T20:56:01.974Z",
    "version": 87,
    "versions": [
      14
    ]
  }
]

Create a agent that can be used within a conversation.

POST /v1/agents

Create a new agent giving it instructions, tools, description. The agent is then available to be used as a regular assistant in a conversation or as part of an agent pool from which it can be used.

200

Successful Response

completion_args

CompletionArgs

White-listed arguments from the completion API

created_at

*date-time

deployment_chat

*boolean

description

string|null

handoffs

array<string>|null

id

*string

instructions

string|null

Instruction prompt the model will follow during the conversation.

metadata

map<any>|null

model

*string

name

*string

object

"agent"

Default Value: "agent"

source

*string

tools

List of tools which are available to the model during the conversation.

updated_at

*date-time

version

*integer

versions

*array<integer>

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.agents.create({
    model: "LeBaron",
    name: "<value>",
  });

  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.agents.create({
    model: "LeBaron",
    name: "<value>",
  });

  console.log(result);
}

run();

from mistralai import Mistral
import os


with Mistral(
    api_key=os.getenv("MISTRAL_API_KEY", ""),
) as mistral:

    res = mistral.beta.agents.create(model="LeBaron", name="<value>")

    # Handle response
    print(res)

from mistralai import Mistral
import os


with Mistral(
    api_key=os.getenv("MISTRAL_API_KEY", ""),
) as mistral:

    res = mistral.beta.agents.create(model="LeBaron", name="<value>")

    # Handle response
    print(res)

curl https://api.mistral.ai/v1/agents \
 -X POST \
 -H 'Authorization: Bearer YOUR_APIKEY_HERE' \
 -H 'Content-Type: application/json' \
 -d '{
  "model": "ipsum eiusmod",
  "name": "consequat do"
}'

curl https://api.mistral.ai/v1/agents \
 -X POST \
 -H 'Authorization: Bearer YOUR_APIKEY_HERE' \
 -H 'Content-Type: application/json' \
 -d '{
  "model": "ipsum eiusmod",
  "name": "consequat do"
}'

200

{
  "created_at": "2025-10-07T20:56:01.974Z",
  "deployment_chat": false,
  "id": "ipsum eiusmod",
  "model": "consequat do",
  "name": "reprehenderit ut dolore",
  "source": "occaecat dolor sit",
  "updated_at": "2025-10-07T20:56:01.974Z",
  "version": 87,
  "versions": [
    14
  ]
}

{
  "created_at": "2025-10-07T20:56:01.974Z",
  "deployment_chat": false,
  "id": "ipsum eiusmod",
  "model": "consequat do",
  "name": "reprehenderit ut dolore",
  "source": "occaecat dolor sit",
  "updated_at": "2025-10-07T20:56:01.974Z",
  "version": 87,
  "versions": [
    14
  ]
}

Retrieve an agent entity.

GET /v1/agents/{agent_id}

Given an agent, retrieve an agent entity with its attributes. The agent_version parameter can be an integer version number or a string alias.

200

Successful Response

completion_args

CompletionArgs

White-listed arguments from the completion API

created_at

*date-time

deployment_chat

*boolean

description

string|null

handoffs

array<string>|null

id

*string

instructions

string|null

Instruction prompt the model will follow during the conversation.

metadata

map<any>|null

model

*string

name

*string

object

"agent"

Default Value: "agent"

source

*string

tools

List of tools which are available to the model during the conversation.

updated_at

*date-time

version

*integer

versions

*array<integer>

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.agents.get({
    agentId: "<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.agents.get({
    agentId: "<id>",
  });

  console.log(result);
}

run();

from mistralai import Mistral
import os


with Mistral(
    api_key=os.getenv("MISTRAL_API_KEY", ""),
) as mistral:

    res = mistral.beta.agents.get(agent_id="<id>")

    # Handle response
    print(res)

from mistralai import Mistral
import os


with Mistral(
    api_key=os.getenv("MISTRAL_API_KEY", ""),
) as mistral:

    res = mistral.beta.agents.get(agent_id="<id>")

    # Handle response
    print(res)

curl https://api.mistral.ai/v1/agents/{agent_id} \
 -X GET \
 -H 'Authorization: Bearer YOUR_APIKEY_HERE'

curl https://api.mistral.ai/v1/agents/{agent_id} \
 -X GET \
 -H 'Authorization: Bearer YOUR_APIKEY_HERE'

200

{
  "created_at": "2025-10-07T20:56:01.974Z",
  "deployment_chat": false,
  "id": "ipsum eiusmod",
  "model": "consequat do",
  "name": "reprehenderit ut dolore",
  "source": "occaecat dolor sit",
  "updated_at": "2025-10-07T20:56:01.974Z",
  "version": 87,
  "versions": [
    14
  ]
}

{
  "created_at": "2025-10-07T20:56:01.974Z",
  "deployment_chat": false,
  "id": "ipsum eiusmod",
  "model": "consequat do",
  "name": "reprehenderit ut dolore",
  "source": "occaecat dolor sit",
  "updated_at": "2025-10-07T20:56:01.974Z",
  "version": 87,
  "versions": [
    14
  ]
}

Delete an agent entity.

DELETE /v1/agents/{agent_id}

Playground

Test the endpoints live

curl https://api.mistral.ai/v1/agents/{agent_id} \
 -X DELETE \
 -H 'Authorization: Bearer YOUR_APIKEY_HERE' \
 -H 'Content-Type: application/json'

curl https://api.mistral.ai/v1/agents/{agent_id} \
 -X DELETE \
 -H 'Authorization: Bearer YOUR_APIKEY_HERE' \
 -H 'Content-Type: application/json'

Update an agent entity.

PATCH /v1/agents/{agent_id}

Update an agent attributes and create a new version.

200

Successful Response

completion_args

CompletionArgs

White-listed arguments from the completion API

created_at

*date-time

deployment_chat

*boolean

description

string|null

handoffs

array<string>|null

id

*string

instructions

string|null

Instruction prompt the model will follow during the conversation.

metadata

map<any>|null

model

*string

name

*string

object

"agent"

Default Value: "agent"

source

*string

tools

List of tools which are available to the model during the conversation.

updated_at

*date-time

version

*integer

versions

*array<integer>

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.agents.update({
    agentId: "<id>",
    agentUpdateRequest: {},
  });

  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.agents.update({
    agentId: "<id>",
    agentUpdateRequest: {},
  });

  console.log(result);
}

run();

from mistralai import Mistral
import os


with Mistral(
    api_key=os.getenv("MISTRAL_API_KEY", ""),
) as mistral:

    res = mistral.beta.agents.update(agent_id="<id>")

    # Handle response
    print(res)

from mistralai import Mistral
import os


with Mistral(
    api_key=os.getenv("MISTRAL_API_KEY", ""),
) as mistral:

    res = mistral.beta.agents.update(agent_id="<id>")

    # Handle response
    print(res)

curl https://api.mistral.ai/v1/agents/{agent_id} \
 -X PATCH \
 -H 'Authorization: Bearer YOUR_APIKEY_HERE' \
 -H 'Content-Type: application/json' \
 -d '{}'

curl https://api.mistral.ai/v1/agents/{agent_id} \
 -X PATCH \
 -H 'Authorization: Bearer YOUR_APIKEY_HERE' \
 -H 'Content-Type: application/json' \
 -d '{}'

200

{
  "created_at": "2025-10-07T20:56:01.974Z",
  "deployment_chat": false,
  "id": "ipsum eiusmod",
  "model": "consequat do",
  "name": "reprehenderit ut dolore",
  "source": "occaecat dolor sit",
  "updated_at": "2025-10-07T20:56:01.974Z",
  "version": 87,
  "versions": [
    14
  ]
}

{
  "created_at": "2025-10-07T20:56:01.974Z",
  "deployment_chat": false,
  "id": "ipsum eiusmod",
  "model": "consequat do",
  "name": "reprehenderit ut dolore",
  "source": "occaecat dolor sit",
  "updated_at": "2025-10-07T20:56:01.974Z",
  "version": 87,
  "versions": [
    14
  ]
}

Update an agent version.

PATCH /v1/agents/{agent_id}/version

Switch the version of an agent.

200

Successful Response

completion_args

CompletionArgs

White-listed arguments from the completion API

created_at

*date-time

deployment_chat

*boolean

description

string|null

handoffs

array<string>|null

id

*string

instructions

string|null

Instruction prompt the model will follow during the conversation.

metadata

map<any>|null

model

*string

name

*string

object

"agent"

Default Value: "agent"

source

*string

tools

List of tools which are available to the model during the conversation.

updated_at

*date-time

version

*integer

versions

*array<integer>

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.agents.updateVersion({
    agentId: "<id>",
    version: 157995,
  });

  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.agents.updateVersion({
    agentId: "<id>",
    version: 157995,
  });

  console.log(result);
}

run();

from mistralai import Mistral
import os


with Mistral(
    api_key=os.getenv("MISTRAL_API_KEY", ""),
) as mistral:

    res = mistral.beta.agents.update_version(agent_id="<id>", version=157995)

    # Handle response
    print(res)

from mistralai import Mistral
import os


with Mistral(
    api_key=os.getenv("MISTRAL_API_KEY", ""),
) as mistral:

    res = mistral.beta.agents.update_version(agent_id="<id>", version=157995)

    # Handle response
    print(res)

curl https://api.mistral.ai/v1/agents/{agent_id}/version \
 -X PATCH \
 -H 'Authorization: Bearer YOUR_APIKEY_HERE' \
 -H 'Content-Type: application/json'

curl https://api.mistral.ai/v1/agents/{agent_id}/version \
 -X PATCH \
 -H 'Authorization: Bearer YOUR_APIKEY_HERE' \
 -H 'Content-Type: application/json'

200

{
  "created_at": "2025-10-07T20:56:01.974Z",
  "deployment_chat": false,
  "id": "ipsum eiusmod",
  "model": "consequat do",
  "name": "reprehenderit ut dolore",
  "source": "occaecat dolor sit",
  "updated_at": "2025-10-07T20:56:01.974Z",
  "version": 87,
  "versions": [
    14
  ]
}

{
  "created_at": "2025-10-07T20:56:01.974Z",
  "deployment_chat": false,
  "id": "ipsum eiusmod",
  "model": "consequat do",
  "name": "reprehenderit ut dolore",
  "source": "occaecat dolor sit",
  "updated_at": "2025-10-07T20:56:01.974Z",
  "version": 87,
  "versions": [
    14
  ]
}

List all versions of an agent.

GET /v1/agents/{agent_id}/versions

Retrieve all versions for a specific agent with full agent context. Supports pagination.

200

Response Type

array<Agent>

Successful Response

Agent

{object}

Playground

Test the endpoints live

curl https://api.mistral.ai/v1/agents/{agent_id}/versions \
 -X GET \
 -H 'Authorization: Bearer YOUR_APIKEY_HERE'

curl https://api.mistral.ai/v1/agents/{agent_id}/versions \
 -X GET \
 -H 'Authorization: Bearer YOUR_APIKEY_HERE'

200

[
  {
    "created_at": "2025-10-07T20:56:01.974Z",
    "deployment_chat": false,
    "id": "ipsum eiusmod",
    "model": "consequat do",
    "name": "reprehenderit ut dolore",
    "source": "occaecat dolor sit",
    "updated_at": "2025-10-07T20:56:01.974Z",
    "version": 87,
    "versions": [
      14
    ]
  }
]

[
  {
    "created_at": "2025-10-07T20:56:01.974Z",
    "deployment_chat": false,
    "id": "ipsum eiusmod",
    "model": "consequat do",
    "name": "reprehenderit ut dolore",
    "source": "occaecat dolor sit",
    "updated_at": "2025-10-07T20:56:01.974Z",
    "version": 87,
    "versions": [
      14
    ]
  }
]

Retrieve a specific version of an agent.

GET /v1/agents/{agent_id}/versions/{version}

Get a specific agent version by version number.

200

Successful Response

completion_args

CompletionArgs

White-listed arguments from the completion API

created_at

*date-time

deployment_chat

*boolean

description

string|null

handoffs

array<string>|null

id

*string

instructions

string|null

Instruction prompt the model will follow during the conversation.

metadata

map<any>|null

model

*string

name

*string

object

"agent"

Default Value: "agent"

source

*string

tools

List of tools which are available to the model during the conversation.

updated_at

*date-time

version

*integer

versions

*array<integer>

Playground

Test the endpoints live

curl https://api.mistral.ai/v1/agents/{agent_id}/versions/{version} \
 -X GET \
 -H 'Authorization: Bearer YOUR_APIKEY_HERE'

curl https://api.mistral.ai/v1/agents/{agent_id}/versions/{version} \
 -X GET \
 -H 'Authorization: Bearer YOUR_APIKEY_HERE'

200

{
  "created_at": "2025-10-07T20:56:01.974Z",
  "deployment_chat": false,
  "id": "ipsum eiusmod",
  "model": "consequat do",
  "name": "reprehenderit ut dolore",
  "source": "occaecat dolor sit",
  "updated_at": "2025-10-07T20:56:01.974Z",
  "version": 87,
  "versions": [
    14
  ]
}

{
  "created_at": "2025-10-07T20:56:01.974Z",
  "deployment_chat": false,
  "id": "ipsum eiusmod",
  "model": "consequat do",
  "name": "reprehenderit ut dolore",
  "source": "occaecat dolor sit",
  "updated_at": "2025-10-07T20:56:01.974Z",
  "version": 87,
  "versions": [
    14
  ]
}

List all aliases for an agent.

GET /v1/agents/{agent_id}/aliases

Retrieve all version aliases for a specific agent.

200

Response Type

array<AgentAliasResponse>

Successful Response

AgentAliasResponse

{object}

Playground

Test the endpoints live

curl https://api.mistral.ai/v1/agents/{agent_id}/aliases \
 -X GET \
 -H 'Authorization: Bearer YOUR_APIKEY_HERE'

curl https://api.mistral.ai/v1/agents/{agent_id}/aliases \
 -X GET \
 -H 'Authorization: Bearer YOUR_APIKEY_HERE'

200

[
  {
    "alias": "ipsum eiusmod",
    "created_at": "2025-10-07T20:56:01.974Z",
    "updated_at": "2025-10-07T20:56:01.974Z",
    "version": 87
  }
]

[
  {
    "alias": "ipsum eiusmod",
    "created_at": "2025-10-07T20:56:01.974Z",
    "updated_at": "2025-10-07T20:56:01.974Z",
    "version": 87
  }
]

Create or update an agent version alias.

PUT /v1/agents/{agent_id}/aliases

Create a new alias or update an existing alias to point to a specific version. Aliases are unique per agent and can be reassigned to different versions.

200

Successful Response

alias

*string

created_at

*date-time

updated_at

*date-time

version

*integer

Playground

Test the endpoints live

curl https://api.mistral.ai/v1/agents/{agent_id}/aliases \
 -X PUT \
 -H 'Authorization: Bearer YOUR_APIKEY_HERE' \
 -H 'Content-Type: application/json'

curl https://api.mistral.ai/v1/agents/{agent_id}/aliases \
 -X PUT \
 -H 'Authorization: Bearer YOUR_APIKEY_HERE' \
 -H 'Content-Type: application/json'

200

{
  "alias": "ipsum eiusmod",
  "created_at": "2025-10-07T20:56:01.974Z",
  "updated_at": "2025-10-07T20:56:01.974Z",
  "version": 87
}

{
  "alias": "ipsum eiusmod",
  "created_at": "2025-10-07T20:56:01.974Z",
  "updated_at": "2025-10-07T20:56:01.974Z",
  "version": 87
}

Beta Agents Endpoints

Examples

GET /v1/agents

Agent

Playground

POST /v1/agents

Request Body

completion_args

description

handoffs

instructions

metadata

model

name

tools

completion_args

created_at

deployment_chat

description

handoffs

id

instructions

metadata

model

name

object

source

tools

updated_at

version

versions

Playground

GET /v1/agents/{agent_id}

Parameters

agent_id

agent_version

completion_args

created_at

deployment_chat

description

handoffs

id

instructions

metadata

model

name

object

source

tools

updated_at

version

versions

Playground

DELETE /v1/agents/{agent_id}

Parameters

agent_id

Playground

PATCH /v1/agents/{agent_id}

Parameters

agent_id

Request Body

completion_args

deployment_chat

description

handoffs

instructions

metadata

model

name

tools

completion_args

created_at

deployment_chat

description

handoffs

id

instructions

metadata

model

name