Beta Agents Endpoints

(beta) Agents API

List agent entities.

GET /v1/agents#

Retrieve a list of agent entities sorted by creation time. Deprecated: some features such as agent sharing are not supported by this endpoint. Use the cursor-paginated GET /v1/agents/pages instead.

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
  ]
}

List agent entities, cursor-paginated.

GET /v1/agents/pages#

Retrieve a page of agent entities. Unlike the deprecated GET /v1/agents, this endpoint paginates by opaque cursor and honors per-agent sharing, returning only agents the caller is authorized to see.

200

Successful Response

data#

*array<Agent>

Successful Response

next_page_token#

string|null

object#

string

Default Value: "list"

Playground

Test the endpoints live

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

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

200

{
  "data": [
    {
      "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
      ]
    }
  ]
}

{
  "data": [
    {
      "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}#

Delete an agent entity.

Playground

Test the endpoints live

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

const mistral = new Mistral({
  apiKey: "MISTRAL_API_KEY",
});

async function run() {
  await mistral.beta.agents.delete({
    agentId: "<id>",
  });


}

run();

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

const mistral = new Mistral({
  apiKey: "MISTRAL_API_KEY",
});

async function run() {
  await mistral.beta.agents.delete({
    agentId: "<id>",
  });


}

run();

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>",
    updateAgentRequest: {
      completionArgs: {
        responseFormat: {
          type: "text",
        },
      },
    },
  });

  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>",
    updateAgentRequest: {
      completionArgs: {
        responseFormat: {
          type: "text",
        },
      },
    },
  });

  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

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

const mistral = new Mistral({
  apiKey: "MISTRAL_API_KEY",
});

async function run() {
  const result = await mistral.beta.agents.listVersions({
    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.listVersions({
    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.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

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

const mistral = new Mistral({
  apiKey: "MISTRAL_API_KEY",
});

async function run() {
  const result = await mistral.beta.agents.getVersion({
    agentId: "<id>",
    version: "<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.getVersion({
    agentId: "<id>",
    version: "<value>",
  });

  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_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

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

const mistral = new Mistral({
  apiKey: "MISTRAL_API_KEY",
});

async function run() {
  const result = await mistral.beta.agents.listVersionAliases({
    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.listVersionAliases({
    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.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 { Mistral } from "@mistralai/mistralai";

const mistral = new Mistral({
  apiKey: "MISTRAL_API_KEY",
});

async function run() {
  const result = await mistral.beta.agents.createVersionAlias({
    agentId: "<id>",
    alias: "<value>",
    version: 595141,
  });

  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.createVersionAlias({
    agentId: "<id>",
    alias: "<value>",
    version: 595141,
  });

  console.log(result);
}

run();

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 { Mistral } from "@mistralai/mistralai";

const mistral = new Mistral({
  apiKey: "MISTRAL_API_KEY",
});

async function run() {
  await mistral.beta.agents.deleteVersionAlias({
    agentId: "<id>",
    alias: "<value>",
  });


}

run();

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

const mistral = new Mistral({
  apiKey: "MISTRAL_API_KEY",
});

async function run() {
  await mistral.beta.agents.deleteVersionAlias({
    agentId: "<id>",
    alias: "<value>",
  });


}

run();

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/pages#

data#

next_page_token#

object#

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#