# Mistral (La Plateforme) — API Research (Phase 0)

Researched 2026-07-30 against official docs (docs.mistral.ai, mistral.ai/pricing) and a live /v1/models probe with a real key (/tmp/zyquo-probe/mistral.json). The live list is authoritative for model existence, aliases, context lengths, capability flags, and deprecation dates.

# 1. Base URL & Endpoints

Base: https://api.mistral.ai

Docs: https://docs.mistral.ai/api/

# 2. Authentication

Authorization: Bearer $MISTRAL_API_KEY. Keys created in the La Plateforme console.

# 3. Chat Model Catalog

From the live probe (capability flags completion_chat, function_calling, reasoning, vision, max_context_length, deprecation are all per-model in the /v1/models response) + https://docs.mistral.ai/getting-started/models/models_overview/ + https://mistral.ai/pricing/api. Max output tokens: Mistral does not publish a separate max-output limit — output is bounded by the shared context window (max_tokens ≤ context minus prompt). All chat models support streaming, function calling, and JSON mode. Pricing in USD per 1M tokens (input/output); cached input tokens get a 90% discount.

# Recommended (current, non-deprecated)

Note: mistral-large-latest (Large 3, open-weight) is now priced below mistral-medium-latest (Medium 3.5, frontier) — Medium 3.5 is the flagship despite the name.

# Legacy / deprecated (still live in the API — mark "legacy" in ModelCatalog, hide by default)

Notable: the standalone Magistral reasoning line is deprecated — reasoning moved into mistral-medium-latest / mistral-small-latest (docs: "Native reasoning models (magistral-small/medium-latest) have been deprecated"; magistral-small-latest is literally an alias of mistral-small-2603 in the live list). Pixtral is gone from the live list (absorbed into vision-capable mainline models). Excluded from catalog: voxtral-* (audio), mistral-embed*, codestral-embed*, mistral-moderation-*, mistral-ocr-*, labs-leanstral-* (Lean theorem-proving lab model), mistral-vibe-cli-* (product aliases of medium/small).

# 4. Request / Response Format

OpenAI-compatible with minor Mistral extensions. Full parameter list (https://docs.mistral.ai/api/):

model (required), messages (required; roles system/user/assistant/tool), temperature (recommend 0.0–0.7; default varies per model — live probe exposes default_model_temperature, e.g. 0.3 for most, 1.0 for medium-3.5), top_p, max_tokens, stream (default false), stop (string or array), random_seed, response_format ({"type": "text" | "json_object" | "json_schema"}), tools, tool_choice (auto/none/any/required), parallel_tool_calls (default true), presence_penalty, frequency_penalty, n, prompt_cache_key, and Mistral-specific safe_prompt (default false) and prompt_mode / reasoning_effort (see §6).

POST /v1/chat/completions
{
  "model": "mistral-medium-latest",
  "messages": [
    { "role": "system", "content": "You are a helpful assistant." },
    { "role": "user", "content": "Reply with exactly: OK" }
  ],
  "temperature": 0.3,
  "max_tokens": 128,
  "stream": false
}

Response is standard OpenAI shape: id, object: "chat.completion", created, model, choices[].message, choices[].finish_reason, usage: {prompt_tokens, completion_tokens, total_tokens}.

Deviation to handle in the client: for reasoning-capable models with reasoning_effort: "high", message.content is not a string but an array of chunks: {"type": "thinking", "thinking": [{"type":"text","text":"..."}]} followed by {"type": "text", "text": "..."}. The Swift Codable model must accept content as string OR chunk array.

Vision: OpenAI style content parts — {"type": "image_url", "image_url": "<https url or data:image/jpeg;base64,...>"} (both URL and base64 data URI supported; https://docs.mistral.ai/capabilities/vision/). Vision models: mistral-medium, mistral-large-3, mistral-small-4, ministral-3 family (per live capability flags).

# 5. Streaming

Standard OpenAI SSE: data: {chat.completion.chunk} events with choices[0].delta.content, terminated by data: [DONE]. Usage arrives on the final chunk. Reasoning wrinkle: during the thinking phase, delta.content is a list containing thinking chunks, then transitions to plain strings for the answer phase — the SSE parser must handle both shapes for the same field.

# 6. Special Parameters

• safe_prompt (bool, default false): injects Mistral's safety guardrail system prompt before the conversation.
• Reasoning (https://docs.mistral.ai/capabilities/reasoning/): on mistral-medium-latest / mistral-small-latest, use reasoning_effort: "high" → full thinking chunks in output (recommended for agentic/code with medium-3.5); "none" → plain string output, no thinking. (prompt_mode: "reasoning" also exists in the API reference as a reasoning switch — appears to be the older Magistral-era mechanism; exact interaction with reasoning_effort unverified.)
• Multi-turn with reasoning: replay the full assistant message including the thinking chunk back into history — stripping reasoning traces degrades quality (official guidance).
• random_seed for reproducibility; prompt_cache_key for prompt caching (cached input: 90% discount).
• Temperature guidance: 0.0–0.7 recommended; per-model defaults exposed in /v1/models (default_model_temperature).

# 7. Rate Limits & Errors

(https://docs.mistral.ai/admin/user-management-finops/tier + help.mistral.ai) Two plans: Free (Experiment) and Scale (pay-as-you-go, higher limits). Limits are per model along two independent axes: requests per second and tokens per minute (plus tokens/month on free tier; ~1B tokens/month on the free Experiment tier — semi-verified, third-party). Mistral no longer publishes exact numbers — live values are in Admin Console → Limits. Org- and workspace-level monthly spending caps can suspend API access when reached. Higher limits: contact support with model/RPS/token-volume details.

Errors: OpenAI-style JSON. 401 invalid key, 422 invalid request/params (Mistral is stricter than OpenAI here — validation errors come back as 422 with detail), 429 rate limit, 5xx server. Exact error body shape varies ({"object":"error","message",...} vs FastAPI-style {"detail":[...]} on 422) — confirm both in Phase 7. Backoff on 429/5xx.

# 8. /models Listing

Yes — the richest of all providers. GET /v1/models → {"object":"list","data":[...]} where every entry includes: id, name (canonical), description, max_context_length, aliases[], deprecation (ISO date or null), deprecation_replacement_model, default_model_temperature, type, and a full capabilities object (completion_chat, completion_fim, function_calling, reasoning, vision, ocr, classification, moderation, audio, audio_transcription, audio_speech, fine_tuning, …). Zyquo Cloud's dynamic refresh can build the entire Mistral catalog from this endpoint alone: filter completion_chat == true && ocr == false && moderation == false && audio* == false, dedupe by name (aliases each appear as separate entries), and flag deprecation != null as legacy.