# Mistral AI GraphQL Schema

Conceptual GraphQL schema for the Mistral AI API. Mistral AI exposes a REST API (OpenAI-compatible) at `https://api.mistral.ai/v1`. This schema translates those REST resources into GraphQL types, queries, and mutations to illustrate a unified, type-safe interface over the full Mistral AI platform.

## Source

- API documentation: https://docs.mistral.ai/api/
- GitHub: https://github.com/mistralai
- Base URL: `https://api.mistral.ai/v1`

## Schema file

[mistral-schema.graphql](mistral-schema.graphql)

## Type inventory

### Message types (5)

| Type | Description |
|---|---|
| `ChatMessage` | Interface for all conversation turn messages |
| `UserMessage` | A message authored by the end user |
| `AssistantMessage` | A message generated by the model, including tool calls |
| `SystemMessage` | An instruction message that primes model behaviour |
| `ToolMessage` | The result of a tool invocation returned to the model |
| `FunctionMessage` | Legacy function call result message |

### Tool and function calling types (6)

| Type | Description |
|---|---|
| `Tool` | A tool the model can invoke during a conversation |
| `Function` | JSON-schema-based function definition exposed to the model |
| `ToolCall` | A tool call issued by the model in its response |
| `ToolCallFunction` | The specific function invocation within a tool call |
| `FunctionCall` | Legacy function call (pre-tool-use API) |
| `ToolChoice` | Configuration controlling which tool the model may invoke |
| `ToolChoiceFunction` | Specifies a particular function to force-invoke |

### Chat completion types (7)

| Type | Description |
|---|---|
| `ChatRequest` | Request payload for `/v1/chat/completions` |
| `ChatResponse` | Non-streaming chat completion response |
| `ChatCompletion` | Alias for `ChatResponse` matching the OpenAI shape |
| `Choice` | A single completion alternative in a non-streaming response |
| `CompletionChunk` | A chunk delivered during SSE streaming |
| `StreamChoice` | A streaming choice delta within a `CompletionChunk` |
| `Delta` | Partial content delivered in a streaming chunk |

### Embedding types (3)

| Type | Description |
|---|---|
| `EmbeddingRequest` | Request payload for `/v1/embeddings` |
| `EmbeddingResponse` | Response from the embeddings endpoint |
| `Embedding` | A single embedding vector for one input string |

### Text completion types (2)

| Type | Description |
|---|---|
| `CompletionRequest` | Request payload for the legacy `/v1/completions` endpoint |
| `CompletionResponse` | Response from the legacy completions endpoint |

### Model types (3)

| Type | Description |
|---|---|
| `ModelList` | A paginated list of available Mistral models |
| `ModelInfo` | Metadata describing a single Mistral model |
| `ModelCapability` | Flags indicating which capabilities a model supports |

### FIM / Codestral types (2)

| Type | Description |
|---|---|
| `FIMRequest` | Request payload for `/v1/fim/completions` |
| `FIMResponse` | Response from the FIM completions endpoint |

### OCR types (6)

| Type | Description |
|---|---|
| `OCRRequest` | Request payload for the `/v1/ocr` endpoint |
| `OCRDocument` | A document to be processed by OCR |
| `OCRResponse` | Structured result returned by the OCR endpoint |
| `OCRPage` | Text and image content extracted from a single page |
| `OCRImage` | An image extracted from an OCR page |
| `OCRDimensions` | Physical dimensions of an OCR-processed page |
| `OCRUsage` | Token/page usage statistics for an OCR request |

### Fine-tuning types (8)

| Type | Description |
|---|---|
| `FineTuningJob` | A fine-tuning job submitted to `/v1/fine_tuning/jobs` |
| `FineTuningHyperparameters` | Hyperparameter settings for a fine-tuning job |
| `FineTuningRepository` | A repository of training/validation files |
| `TrainingFile` | A file used for fine-tuning training or validation |
| `FineTuningEvent` | An event emitted during a fine-tuning job's lifecycle |
| `Checkpoint` | Metrics captured at a model checkpoint during training |
| `TrainingResult` | Loss and accuracy metrics at a training checkpoint |
| `FineTuningIntegration` | Third-party integration (e.g. WandB) for a fine-tuning job |

### File management types (1)

| Type | Description |
|---|---|
| `FileObject` | A file object managed by the `/v1/files` endpoint |

### Batch types (1)

| Type | Description |
|---|---|
| `BatchJob` | A batch inference job submitted to `/v1/batch/jobs` |

### Audio transcription types (3)

| Type | Description |
|---|---|
| `TranscriptionResponse` | Response from `/v1/audio/transcriptions` |
| `TranscriptionWord` | A word-level timestamp entry from a verbose transcription |
| `TranscriptionSegment` | A segment-level entry from a verbose transcription |

### Identity and access types (3)

| Type | Description |
|---|---|
| `APIKey` | An API key associated with a Mistral account |
| `User` | A Mistral platform user account |
| `Organization` | A Mistral AI organization (workspace) |

### Usage and billing types (7)

| Type | Description |
|---|---|
| `Usage` | Token usage counts attached to a completion response |
| `InputTokens` | Detailed breakdown of input tokens by category |
| `OutputTokens` | Detailed breakdown of output tokens |
| `TotalTokens` | Aggregate token counts for a billing period |
| `UsageSummary` | High-level usage summary for an account or workspace |
| `BillingData` | Billing data aggregated across an organization |
| `Invoice` | A billing invoice issued to a Mistral customer |
| `WaitlistEntry` | A waitlist entry for early access to Mistral features |

## Enums

| Enum | Values |
|---|---|
| `Role` | `USER`, `ASSISTANT`, `SYSTEM`, `TOOL`, `FUNCTION` |
| `FinishReason` | `STOP`, `LENGTH`, `TOOL_CALLS`, `ERROR`, `FUNCTION_CALL` |
| `ToolChoiceMode` | `AUTO`, `NONE`, `ANY`, `REQUIRED` |
| `ModelCapabilityType` | `CHAT`, `EMBEDDINGS`, `FIM`, `CLASSIFICATION`, `OCR`, `FINE_TUNE`, `VISION`, `AUDIO`, `BATCH` |
| `FineTuningJobStatus` | `QUEUED`, `STARTED`, `RUNNING`, `FAILED`, `SUCCESS`, `CANCELLED`, `CANCELLATION_REQUESTED` |
| `FineTuningJobType` | `TEXT`, `VISION`, `CLASSIFIER` |
| `BatchJobStatus` | `QUEUED`, `RUNNING`, `SUCCESS`, `FAILED`, `TIMEOUT_EXCEEDED`, `CANCELLATION_REQUESTED`, `CANCELLED` |
| `FileStatus` | `UPLOADED`, `PROCESSING`, `PROCESSED`, `ERROR` |
| `FilePurpose` | `FINE_TUNE`, `BATCH`, `OCR` |
| `OCRType` | `IMAGE_URL`, `DOCUMENT_URL` |
| `TranscriptionFormat` | `JSON`, `TEXT`, `VERBOSE_JSON`, `VTT`, `SRT` |

## Root operations

### Queries

- `models` — list all available models
- `model(id)` — retrieve a specific model
- `fineTuningJobs` — list fine-tuning jobs
- `fineTuningJob(id)` — retrieve a single fine-tuning job
- `files` — list uploaded files
- `file(id)` — retrieve a single file
- `batchJobs` — list batch jobs
- `batchJob(id)` — retrieve a single batch job
- `apiKeys` — list API keys
- `me` — get authenticated user profile
- `organization(id)` — get organization details
- `billingData(organizationId)` — get billing data
- `usageSummary(period)` — get usage summary

### Mutations

- `createChatCompletion` — chat completion (non-streaming)
- `createEmbeddings` — generate text embeddings
- `createFIMCompletion` — fill-in-the-middle code completion
- `processOCR` — process a document with OCR
- `createFineTuningJob` — submit a fine-tuning job
- `startFineTuningJob` — start a queued fine-tuning job
- `cancelFineTuningJob` — cancel a running fine-tuning job
- `archiveModel` / `unarchiveModel` — archive management
- `deleteModel` — delete a fine-tuned model
- `deleteFile` — delete a file
- `createBatchJob` — create a batch job
- `cancelBatchJob` — cancel a running batch job
- `transcribeAudio` — transcribe audio to text
- `createAPIKey` / `deleteAPIKey` — API key management