The /v1/chat/completions Endpoint

Update November 2, 2026 — Models. Mistral Large 3 (mistral-large-2512) and Mistral Medium 3.5 were deprecated on October 31, 2026, and will be retired on April 30, 2027. Their designated successor, Mistral Large 4 (mistral-large-4), has been in public preview since October 6. The examples in this course use the alias mistral-large-latest, which currently points to Mistral Large 3 according to its official specification (verified November 3, 2026). Similarly, mistral-medium-latest points to Mistral Medium 3.5. These aliases will remain valid until April 30, 2027. For new projects, test mistral-large-4, their designated successor.

Your Gateway to Mistral Models

Everything you do with the Mistral API goes through a single path: /v1/chat/completions. This is the central hub of the platform, handling all your conversational interactions with language models. Whether you are building an internal support chatbot, an extractor that turns PDF invoices into database rows, or a writing assistant integrated into your CMS, these three seemingly different applications call the exact same endpoint with different messages and parameters. You do not need to learn three separate integrations; you only need to master one.

As of April 2026, this endpoint handles billions of requests daily worldwide. Understanding its structure is the first step to leveraging Mistral models in production.

The Base URL

All requests to the Mistral API start from the same base:

https://api.mistral.ai/v1/chat/completions

You send a POST request with a JSON body containing your messages and parameters, and the API returns a structured JSON response. There are no sessions to open and no server-side state to maintain: every call is self-contained.

Anatomy of a Request

The fastest way to verify that your key works is to send a minimal request using curl directly from your terminal:

curl https://api.mistral.ai/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $MISTRAL_API_KEY" \
  -d '{
    "model": "mistral-large-latest",
    "messages": [
      {"role": "user", "content": "Hello, how does your API work?"}
    ]
  }'

Two headers are mandatory: Content-Type: application/json describes the request body format, and Authorization: Bearer <your-key> carries your authentication. The body itself must contain at least two fields: model, the identifier of the model to use, and messages, the array carrying the conversation.

Python Equivalent with the SDK

Once you move past the testing phase, no one writes raw curl commands in production. The official SDK makes the same call in just a few lines:

from mistralai.client import Mistral
import os

client = Mistral(api_key=os.getenv("MISTRAL_API_KEY"))

response = client.chat.complete(
    model="mistral-large-latest",
    messages=[
        {"role": "user", "content": "Hello, how does your API work?"}
    ]
)

print(response.choices[0].message.content)

The SDK handles headers, JSON serialization, and response parsing for you. It also manages automatic retries for temporary errors, saving you from writing your own retry logic when a traffic spike causes a transient failure.

Response Structure

No matter how you call the API, it always returns the same JSON object:

{
  "id": "cmpl-abc123",
  "object": "chat.completion",
  "created": 1712150400,
  "model": "mistral-large-latest",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Hello! The Mistral API works..."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 15,
    "completion_tokens": 87,
    "total_tokens": 102
  }
}

Three fields deserve your immediate attention. choices is an array containing the generated response(s); this is where you find the text to display to the user. usage provides the token count for input, output, and the total, allowing you to track the real cost of each feature rather than discovering the bill at the end of the month. Finally, finish_reason explains why the model stopped: stop for a natural end, length when the token limit cut off the response, or tool_calls when the model requests tool execution. A summary that ends mid-sentence is almost never a model problem; it is a finish_reason of length that nobody read.

Common Error Codes

When something goes wrong, the API returns standard HTTP codes:

• 400 — Malformed request (invalid JSON, missing parameter)
• 401 — Invalid or missing API key
• 429 — Rate limit reached (too many requests)
• 500 — Server error (retry after a few seconds)

In Python, the SDK raises typed exceptions that you can catch, allowing you to distinguish between an expired key and temporary saturation, and react differently in each case:

from mistralai.client import Mistral
from mistralai.client.errors import SDKError

client = Mistral(api_key=os.getenv("MISTRAL_API_KEY"))

try:
    response = client.chat.complete(
        model="mistral-large-latest",
        messages=[{"role": "user", "content": "Test"}]
    )
except SDKError as e:
    print(f"API Error: {e.status_code} — {e.message}")

Make it a habit to wrap every call in this block from your very first script. The day your application runs unattended, it will tell you what failed instead of stopping silently.

Key Takeaways

• The /v1/chat/completions endpoint is the only one needed for conversational interactions
• Every request requires a model and a messages array
• The response always contains choices, usage, and finish_reason
• The Python SDK significantly simplifies calls compared to curl
• Usage tokens allow you to calculate your costs precisely