Several API examples are not reproducible or inconsistent across cURL and TypeScript

[fabroos]

While testing the documented API examples (cURL, TypeScript, and MDX references), I found multiple issues that make several endpoints confusing or non-runnable. Most problems fall into missing required parameters, inconsistent model usage between examples, or examples that depend on resources that are never created.

Below is a breakdown by category.

---

Chat Completions

cURL

{
  "message": "API error occurred: Status 422 Content-Type \"application/json\". Body: {\"detail\":[{\"type\":\"union_tag_not_found\",\"loc\":[\"body\",\"messages\",0],\"msg\":\"Unable to extract tag using discriminator 'role'\",\"input\":{\"content\":\"ipsum eiusmod\"},\"ctx\":{\"discriminator\":\"'role'\"}}]}"
}

Issue

• messages[0] is missing the required role field.

---

FIM Completions

TypeScript

{
  "message": "Unable to make request: TypeError: Failed to fetch",
  "stack": "ConnectionError: Unable to make request: TypeError: Failed to fetch",
  "name": "ConnectionError"
}

Issue

• The request includes a suffix field that should not be present.

cURL

Issue

• Missing required model parameter.

---

Agents

Issue

• It’s unclear how this endpoint should be used:
  • Is an agent_id required?
  • No agent creation or setup is shown, making the example hard to reproduce.

---

Embeddings

• ✅ Works as expected.

---

Classifiers

There are multiple inconsistencies between TypeScript and cURL examples:

• TS uses an incorrect model while cURL works
• TS references a non-existent model, while cURL uses a different incorrect model
• Model names differ between TS and cURL (model vs model-incorrect)
• The same issue is repeated across several examples

---

Files

• List: ✅ Works
• Upload: Works, but the example doesn’t clearly explain the intended use case
• Retrieve / Delete:
  • The referenced file does not exist (expected, but confusing)
  • cURL examples use placeholder-style values (e.g. {parameter})
• Download / Signed URL:
  • Same issue as above: references non-existent files or placeholders

---

Fine-tuning

• TypeScript: ✅
• cURL: ✅

However, examples require pre-existing uploaded files, which are not created or referenced in the docs, making them hard to reproduce.

---

Models

• List: ✅ Works
• Retrieve / other operations:
  • Fail because no fine-tuned models exist
  • This is expected behavior, but the lack of setup or context is confusing for users

---

Batch

• TypeScript: ✅
• cURL: ✅

Same limitation as other categories: most endpoints require valid uploaded files to already exist.

---

OCR

• Example does not provide a valid documentUrl, file, or image.

---

Audio Transcription

• Same issue as OCR: no valid audio file or URL is provided.

---

Summary

Most issues fall into one of these categories:

• Missing required parameters (role, model, etc.)
• Inconsistent or incorrect model names between TypeScript and cURL
• Examples depending on resources (files, agents, fine-tuned models) that are never created
• Placeholder values that prevent examples from being runnable

Providing consistent parameters, minimal setup steps, and runnable end-to-end examples would significantly improve the developer experience.

[nebrius]

Thanks for the detailed list of issues. I'll look into the first two items in the summary likely tomorrow.

Examples depending on resources (files, agents, fine-tuned models) that are never created

Solving this issue directly is outside the scope of docs-md, since docs-md doesn't have knowledge of databases. In other words, docs-md is aware of the API a server provides, but not the data it provides.

One approach you could take, perhaps, is to manually create these resources yourselves ahead of time and then reference them in custom examples (see next section below).

Placeholder values that prevent examples from being runnable

Placeholders are all that docs-md can do by itself when generating examples, since it doesn't know what specific data is available. You can get around this by defining an explicit example though that overrides the auto-generated examples, and hard-codes in actual values for these placeholder values.

[nebrius]

Chat Completions

This occurs because the payload is missing the role property. The role property is not included because the spec says it's not required:

https://github.com/mistralai/platform-docs/blob/2a7d138b2ce5b8b0fd6d4d2f1dd783c17ee9d433/openapi.yaml#L7420-L7438

Given that the server errors when this property is missing, I'd say this is a bug in the spec itself. To fix this issue, add role to the list of required properties.

[nebrius]

FIM Completions

TypeScript

This endpoint works fine for me. I suspect the "Failed to fetch" error indicates there was a temporary outage of some sort that caused the issue. Here's what I see:

cURL

This appears to be a bug in the Speakeasy Generator that docs md relies on. If we look at the spec, we can see that both prompt and model are required properties:

https://github.com/mistralai/platform-docs/blob/2a7d138b2ce5b8b0fd6d4d2f1dd783c17ee9d433/openapi.yaml#L7033-L7035

However, the data from the speakeasy generator says that only prompt is a required property:

@simplesagar can you get someone to take a look on the Go side of things to see why this required property isn't included?

[nebrius]

Agents

It’s unclear how this endpoint should be used:

• Is an agent_id required?

Looking at the docs, yes agent_id is required (see the asterisk)

• No agent creation or setup is shown, making the example hard to reproduce.

Agreed. I'd recommend talking to some Mistral folks who understand the context of this endpoint and getting instructions from them. Then, you can add it to the description for the endpoint. I could see doing something like:

agent_id:
    type: string
    description: The ID of the agent to use for this completion. You can get a list of agents by calling [/some/endpoint](/path/to/some/agent/docs)

Note that description is interpolated as Markdown, so you can add links and such to it.

[nebrius]

Classifiers

Regarding models: both the TypeScript and cURL versions use auto-generated placeholder names, but using different algorithms. As you can see in the example, cURL uses a lorem ipsum generator.

To get a valid model ID, you'll want to follow what I outlined in #200 (comment): generate real models for use specifically with docs, and then add explicit examples in the OpenAPI spec that reference these models.

[nebrius]

Files

cURL examples use placeholder-style values (e.g. {parameter})

Would you prefer to see placeholder example text instead? e.g.

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

It won't execute correctly regardless, because again this isn't something docs-md can do given it's not database data aware.

I'd say a better option is for you to create an example file in the DB for use with docs, and then drop in a custom example that references this file.

[nebrius]

OCR

Example does not provide a valid documentUrl, file, or image.

If we look at the spec for this at:

https://github.com/mistralai/platform-docs/blob/2a7d138b2ce5b8b0fd6d4d2f1dd783c17ee9d433/openapi.yaml#L7267-L7273

a request can contain a file or a document or an image. Due to the way docs-md pics an option when it encounters a union, it will pick file, defined at:

https://github.com/mistralai/platform-docs/blob/2a7d138b2ce5b8b0fd6d4d2f1dd783c17ee9d433/openapi.yaml#L7037-L7052

If we look at this example, we can see that file_id is the only required property. I'm guessing this is another mismatch between the spec and the server implementation, and that type should also be required.

If I'm correct (and you should double check with Mistral), then the fix is to add type to the list of required properties.

[nebrius]

Audio transcription

This also appears to be a mismatch between the server implementation and the spec. If we look at:

https://github.com/mistralai/platform-docs/blob/2a7d138b2ce5b8b0fd6d4d2f1dd783c17ee9d433/openapi.yaml#L7684-L7685

we can see that only model is a required property, but I bet that file, file_url, or file_id should be required. This is tricky to represent in OpenAPI though so you might want to consider implementing an explicit example, especially since any automated value would just be a non-functional placeholder anyways.

[jaccolor2]

In the case of audio transcription, a solution would be to generate 3 code snippets: one with file, one with file_url and one with file_id. In the UI, they could somehow (maybe with a tabItem component or something similar) choose between these 3 options? For the values, we could simply have a "paceholder_value" field, and it would be replaced at build time with a value that points to a content we already created (whether be it a file, file_url, file_id, agent_id...). For incorrect models, we could simply use this approach. this way we avoid hallucinated model names.

I will take care of adding the missing required parameters to the openapi specs

[nebrius]

For the drop-down, there's a more general approach we can take, and is much easier to implement too: define multiple examples.

In your spec, you can define multiple named examples like this:

/endpoint/url
  post:
    requestBody:
      content:
        application/json
          schema: ...
          examples:
            myFirstExample: {
                ...JSON example here
              {
            mySecondExample: {
                ...JSON example here
              {

Then, in the UI I can make the name of the example the value in the dropdown. How does that sound?