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.client 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.client 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-12-17T10:25:07.818693Z",
    "deployment_chat": false,
    "id": "019b2bd7-96e7-7219-8c0b-45a73da50088",
    "model": "mistral-small-latest",
    "name": "My resource",
    "source": "upload",
    "updated_at": "2025-12-17T10:41:03.469341Z",
    "version": 87,
    "versions": [
      14
    ]
  }
]

[
  {
    "created_at": "2025-12-17T10:25:07.818693Z",
    "deployment_chat": false,
    "id": "019b2bd7-96e7-7219-8c0b-45a73da50088",
    "model": "mistral-small-latest",
    "name": "My resource",
    "source": "upload",
    "updated_at": "2025-12-17T10:41:03.469341Z",
    "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

guardrails

array<GuardrailConfig>|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

string

Default Value: "agent"

source

*string

tools

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

updated_at

*date-time

version

*integer

version_message

string|null

versions

*array<integer>

Playground

Test the endpoints live

import { Mistral } from "@mistralai/mistralai";

const client = new Mistral({ apiKey: process.env.MISTRAL_API_KEY });

const agent = await client.beta.agents.create({
  model: "mistral-small-latest",
  name: "Support assistant",
});

console.log(agent.id);

import { Mistral } from "@mistralai/mistralai";

const client = new Mistral({ apiKey: process.env.MISTRAL_API_KEY });

const agent = await client.beta.agents.create({
  model: "mistral-small-latest",
  name: "Support assistant",
});

console.log(agent.id);

import os
from mistralai import Mistral

client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])

agent = client.beta.agents.create(
    model="mistral-small-latest",
    name="Support assistant",
)

print(agent.id)

import os
from mistralai import Mistral

client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])

agent = client.beta.agents.create(
    model="mistral-small-latest",
    name="Support assistant",
)

print(agent.id)

curl https://api.mistral.ai/v1/agents \
 -X POST \
 -H 'Authorization: Bearer YOUR_APIKEY_HERE' \
 -H 'Content-Type: application/json' \
 -d '{
  "model": "mistral-small-latest",
  "name": "My Agent"
}'

curl https://api.mistral.ai/v1/agents \
 -X POST \
 -H 'Authorization: Bearer YOUR_APIKEY_HERE' \
 -H 'Content-Type: application/json' \
 -d '{
  "model": "mistral-small-latest",
  "name": "My Agent"
}'

200

{
  "created_at": "2025-12-17T10:25:07.818693Z",
  "deployment_chat": false,
  "id": "019b2bd7-96e7-7219-8c0b-45a73da50088",
  "model": "mistral-small-latest",
  "name": "My resource",
  "source": "upload",
  "updated_at": "2025-12-17T10:41:03.469341Z",
  "version": 87,
  "versions": [
    14
  ]
}

{
  "created_at": "2025-12-17T10:25:07.818693Z",
  "deployment_chat": false,
  "id": "019b2bd7-96e7-7219-8c0b-45a73da50088",
  "model": "mistral-small-latest",
  "name": "My resource",
  "source": "upload",
  "updated_at": "2025-12-17T10:41:03.469341Z",
  "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

guardrails

array<GuardrailConfig>|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

string

Default Value: "agent"

source

*string

tools

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

updated_at

*date-time

version

*integer

version_message

string|null

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.client 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.client 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-12-17T10:25:07.818693Z",
  "deployment_chat": false,
  "id": "019b2bd7-96e7-7219-8c0b-45a73da50088",
  "model": "mistral-small-latest",
  "name": "My resource",
  "source": "upload",
  "updated_at": "2025-12-17T10:41:03.469341Z",
  "version": 87,
  "versions": [
    14
  ]
}

{
  "created_at": "2025-12-17T10:25:07.818693Z",
  "deployment_chat": false,
  "id": "019b2bd7-96e7-7219-8c0b-45a73da50088",
  "model": "mistral-small-latest",
  "name": "My resource",
  "source": "upload",
  "updated_at": "2025-12-17T10:41:03.469341Z",
  "version": 87,
  "versions": [
    14
  ]
}

Delete an agent entity.

DELETE /v1/agents/{agent_id}

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.agents.delete(agent_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.agents.delete(agent_id="<id>")

    # Use the SDK ...

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

guardrails

array<GuardrailConfig>|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

string

Default Value: "agent"

source

*string

tools

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

updated_at

*date-time

version

*integer

version_message

string|null

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.client import Mistral
import os


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

    res = mistral.beta.agents.update(agent_id="<id>", 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.agents.update(agent_id="<id>", completion_args={
        "response_format": {
            "type": "text",
        },
    })

    # 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-12-17T10:25:07.818693Z",
  "deployment_chat": false,
  "id": "019b2bd7-96e7-7219-8c0b-45a73da50088",
  "model": "mistral-small-latest",
  "name": "My resource",
  "source": "upload",
  "updated_at": "2025-12-17T10:41:03.469341Z",
  "version": 87,
  "versions": [
    14
  ]
}

{
  "created_at": "2025-12-17T10:25:07.818693Z",
  "deployment_chat": false,
  "id": "019b2bd7-96e7-7219-8c0b-45a73da50088",
  "model": "mistral-small-latest",
  "name": "My resource",
  "source": "upload",
  "updated_at": "2025-12-17T10:41:03.469341Z",
  "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

guardrails

array<GuardrailConfig>|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

string

Default Value: "agent"

source

*string

tools

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

updated_at

*date-time

version

*integer

version_message

string|null

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.client 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.client 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-12-17T10:25:07.818693Z",
  "deployment_chat": false,
  "id": "019b2bd7-96e7-7219-8c0b-45a73da50088",
  "model": "mistral-small-latest",
  "name": "My resource",
  "source": "upload",
  "updated_at": "2025-12-17T10:41:03.469341Z",
  "version": 87,
  "versions": [
    14
  ]
}

{
  "created_at": "2025-12-17T10:25:07.818693Z",
  "deployment_chat": false,
  "id": "019b2bd7-96e7-7219-8c0b-45a73da50088",
  "model": "mistral-small-latest",
  "name": "My resource",
  "source": "upload",
  "updated_at": "2025-12-17T10:41:03.469341Z",
  "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

from mistralai.client import Mistral
import os


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

    res = mistral.beta.agents.list_versions(agent_id="<id>", page=0, page_size=20)

    # 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.agents.list_versions(agent_id="<id>", page=0, page_size=20)

    # Handle response
    print(res)

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-12-17T10:25:07.818693Z",
    "deployment_chat": false,
    "id": "019b2bd7-96e7-7219-8c0b-45a73da50088",
    "model": "mistral-small-latest",
    "name": "My resource",
    "source": "upload",
    "updated_at": "2025-12-17T10:41:03.469341Z",
    "version": 87,
    "versions": [
      14
    ]
  }
]

[
  {
    "created_at": "2025-12-17T10:25:07.818693Z",
    "deployment_chat": false,
    "id": "019b2bd7-96e7-7219-8c0b-45a73da50088",
    "model": "mistral-small-latest",
    "name": "My resource",
    "source": "upload",
    "updated_at": "2025-12-17T10:41:03.469341Z",
    "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

guardrails

array<GuardrailConfig>|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

string

Default Value: "agent"

source

*string

tools

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

updated_at

*date-time

version

*integer

version_message

string|null

versions

*array<integer>

Playground

Test the endpoints live

from mistralai.client import Mistral
import os


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

    res = mistral.beta.agents.get_version(agent_id="<id>", version="788393")

    # 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.agents.get_version(agent_id="<id>", version="788393")

    # Handle response
    print(res)

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-12-17T10:25:07.818693Z",
  "deployment_chat": false,
  "id": "019b2bd7-96e7-7219-8c0b-45a73da50088",
  "model": "mistral-small-latest",
  "name": "My resource",
  "source": "upload",
  "updated_at": "2025-12-17T10:41:03.469341Z",
  "version": 87,
  "versions": [
    14
  ]
}

{
  "created_at": "2025-12-17T10:25:07.818693Z",
  "deployment_chat": false,
  "id": "019b2bd7-96e7-7219-8c0b-45a73da50088",
  "model": "mistral-small-latest",
  "name": "My resource",
  "source": "upload",
  "updated_at": "2025-12-17T10:41:03.469341Z",
  "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

from mistralai.client import Mistral
import os


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

    res = mistral.beta.agents.list_version_aliases(agent_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.agents.list_version_aliases(agent_id="<id>")

    # Handle response
    print(res)

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": "production",
    "created_at": "2025-12-17T10:25:07.818693Z",
    "updated_at": "2025-12-17T10:41:03.469341Z",
    "version": 87
  }
]

[
  {
    "alias": "production",
    "created_at": "2025-12-17T10:25:07.818693Z",
    "updated_at": "2025-12-17T10:41:03.469341Z",
    "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

import os
from mistralai import Mistral

client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])

alias = client.beta.agents.create_version_alias(
    agent_id="019b2bd7-96e7-7219-8c0b-45a73da50088",
    alias="production",
    version=1,
)

print(alias)

import os
from mistralai import Mistral

client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])

alias = client.beta.agents.create_version_alias(
    agent_id="019b2bd7-96e7-7219-8c0b-45a73da50088",
    alias="production",
    version=1,
)

print(alias)

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": "production",
  "created_at": "2025-12-17T10:25:07.818693Z",
  "updated_at": "2025-12-17T10:41:03.469341Z",
  "version": 87
}

{
  "alias": "production",
  "created_at": "2025-12-17T10:25:07.818693Z",
  "updated_at": "2025-12-17T10:41:03.469341Z",
  "version": 87
}

Delete an agent version alias.

DELETE /v1/agents/{agent_id}/aliases

Delete an existing alias for an agent.

Playground

Test the endpoints live

import os
from mistralai import Mistral

client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])

client.beta.agents.delete_version_alias(
    agent_id="019b2bd7-96e7-7219-8c0b-45a73da50088",
    alias="production",
)

import os
from mistralai import Mistral

client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])

client.beta.agents.delete_version_alias(
    agent_id="019b2bd7-96e7-7219-8c0b-45a73da50088",
    alias="production",
)

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

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

Beta Agents Endpoints

Examples

GET /v1/agents

Agent

Playground

POST /v1/agents

Request Body

completion_args

description

guardrails

handoffs

instructions

metadata

model

name

tools

version_message

completion_args

created_at

deployment_chat

description

guardrails

handoffs

id

instructions

metadata

model

name

object

source

tools

updated_at

version

version_message

versions

Playground

GET /v1/agents/{agent_id}

Parameters

agent_id

agent_version

completion_args

created_at

deployment_chat

description

guardrails

handoffs

id

instructions

metadata

model

name

object

source

tools

updated_at

version

version_message

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

guardrails

handoffs

instructions

metadata

model

name

tools

version_message

completion_args

created_at