> Discover all available pages from the documentation index: https://mastra.zisheng.pro/fr/llms.txt

# Routes du serveur

Les Adapters de serveur enregistrent ces routes lorsque vous appelez `server.init()`. Toutes les routes sont précédées de l’option `prefix` si celle-ci est configurée.

## Agents

| Méthode | Chemin                                       | Description                                                                    |
| ------- | -------------------------------------------- | ------------------------------------------------------------------------------ |
| `GET`   | `/api/agents`                                | Répertorier tous les Agents                                                    |
| `GET`   | `/api/agents/:agentId`                       | Obtenir un Agent par ID (prend en charge les paramètres de requête de version) |
| `POST`  | `/api/agents/:agentId/generate`              | Générer une réponse de l’Agent                                                 |
| `POST`  | `/api/agents/:agentId/stream`                | Diffuser la réponse de l’Agent                                                 |
| `POST`  | `/api/agents/:agentId/send-message`          | Envoyer un message utilisateur à un fil actif ou inactif                       |
| `POST`  | `/api/agents/:agentId/queue-message`         | Mettre en file d’attente un message utilisateur pour le prochain tour du fil   |
| `POST`  | `/api/agents/:agentId/signals`               | Envoyer un signal de bas niveau à un fil actif ou inactif                      |
| `POST`  | `/api/agents/:agentId/threads/subscribe`     | S’abonner au flux d’un fil                                                     |
| `POST`  | `/api/agents/:agentId/send-tool-approval`    | Approuver ou refuser un appel de Tool et reprendre via un abonnement au fil    |
| `POST`  | `/api/agents/:agentId/resume-stream`         | Reprendre un flux d’Agent suspendu avec des données personnalisées             |
| `GET`   | `/api/agents/:agentId/tools`                 | Répertorier les Tools de l’Agent                                               |
| `POST`  | `/api/agents/:agentId/tools/:toolId/execute` | Exécuter un Tool de l’Agent                                                    |

### Paramètres de requête pour obtenir un Agent

`GET /api/agents/:agentId` accepte des paramètres de requête facultatifs permettant de choisir la version de configuration stockée appliquée en remplacement aux Agents définis dans le code :

| Paramètre   | Type                     | Valeur par défaut | Description                                                                                       |
| ----------- | ------------------------ | ----------------- | ------------------------------------------------------------------------------------------------- |
| `status`    | `'draft' \| 'published'` | `'published'`     | Version stockée à résoudre. `draft` renvoie la dernière version et `published` la version active. |
| `versionId` | `string`                 | Aucune            | ID de version précis à résoudre. Prioritaire sur `status`.                                        |

```bash
# Get agent with active published overrides (default)
GET /api/agents/my-agent

# Get agent with latest draft overrides
GET /api/agents/my-agent?status=draft

# Get agent with a specific version's overrides
GET /api/agents/my-agent?versionId=abc123
```

### Corps de la requête de génération

```typescript
{
  messages: CoreMessage[] | string;       // Required
  instructions?: string;                   // System instructions
  system?: string;                         // System prompt
  context?: CoreMessage[];                 // Additional context
  memory?: { key: string } | boolean;      // Memory config
  resourceId?: string;                     // Resource identifier
  threadId?: string;                       // Thread identifier
  runId?: string;                          // Run identifier
  maxSteps?: number;                       // Max tool steps
  activeTools?: string[];                  // Tools to enable
  toolChoice?: ToolChoice;                 // Tool selection mode
  requestContext?: Record<string, unknown>; // Request context
  output?: ZodSchema;                      // Structured output schema
}
```

### Réponse de génération

```typescript
{
  text: string;
  toolCalls?: ToolCall[];
  finishReason: string;
  usage?: {
    promptTokens: number;
    completionTokens: number;
  };
}
```

### Routes de messages des Agents

Utilisez `POST /api/agents/:agentId/send-message` pour envoyer un message utilisateur à la boucle active de l’Agent ou réveiller un fil inactif. Utilisez `POST /api/agents/:agentId/queue-message` lorsque l’exécution active doit se terminer avant que Mastra ne lance l’exécution suivante.

Les deux routes acceptent le même corps de requête :

```typescript
{
  message: string | Array<TextPart | FilePart> | {
    contents: string | Array<TextPart | FilePart>;
    attributes?: Record<string, JSONValue>;
    metadata?: Record<string, unknown>;
    providerOptions?: ProviderMetadata;
  };
  runId?: string;
  resourceId?: string;
  threadId?: string;
  ifActive?: {
    behavior?: 'deliver' | 'persist' | 'discard';
    attributes?: Record<string, string | number | boolean>;
  };
  ifIdle?: {
    behavior?: 'wake' | 'persist' | 'discard';
    streamOptions?: Omit<AgentExecutionOptions, 'messages'>;
    attributes?: Record<string, string | number | boolean>;
  };
}
```

Lorsque `runId` est omis, `resourceId` et `threadId` sont requis. `ifIdle` s’applique uniquement aux requêtes ciblant un fil, et non à celles qui ciblent une exécution.

#### Envoyer un message

```bash
curl -X POST http://localhost:4111/api/agents/supportAgent/send-message \
  -H 'Content-Type: application/json' \
  -d '{
    "message": {
      "contents": "Show the shorter version.",
      "attributes": { "sentFrom": "web" }
    },
    "resourceId": "user_123",
    "threadId": "thread_456"
  }'
```

#### Mettre un message en file d’attente

```bash
curl -X POST http://localhost:4111/api/agents/supportAgent/queue-message \
  -H 'Content-Type: application/json' \
  -d '{
    "message": "Also check whether the tests need updates.",
    "resourceId": "user_123",
    "threadId": "thread_456"
  }'
```

Les deux routes renvoient :

```typescript
{
  accepted: true;
  runId: string;
  signal?: CreatedAgentSignal;
}
```

### Routes d’approbation des Tools par abonnement

Utilisez `POST /api/agents/:agentId/send-tool-approval` lorsque le client dispose déjà d’un abonnement actif au fil. La route reprend l’exécution et renvoie un accusé de réception JSON. Les fragments du flux repris sont remis via `POST /api/agents/:agentId/threads/subscribe`.

La route accepte ce corps de requête :

```typescript
{
  resourceId: string;
  threadId: string;
  toolCallId: string;
  approved: boolean;
  requestContext?: Record<string, unknown>;
}
```

La route renvoie :

```typescript
{
  accepted: true;
  runId: string;
  toolCallId?: string;
}
```

## Workflows

| Méthode | Chemin                                    | Description                                                        |
| ------- | ----------------------------------------- | ------------------------------------------------------------------ |
| `GET`   | `/api/workflows`                          | Répertorier tous les Workflows                                     |
| `GET`   | `/api/workflows/run-counts`               | Obtenir le nombre d’exécutions en cours et suspendues par Workflow |
| `GET`   | `/api/workflows/:workflowId`              | Obtenir un Workflow par ID                                         |
| `POST`  | `/api/workflows/:workflowId/create-run`   | Créer une nouvelle exécution de Workflow                           |
| `POST`  | `/api/workflows/:workflowId/start-async`  | Démarrer un Workflow et attendre le résultat                       |
| `POST`  | `/api/workflows/:workflowId/stream`       | Diffuser l’exécution d’un Workflow                                 |
| `POST`  | `/api/workflows/:workflowId/resume`       | Reprendre un Workflow suspendu                                     |
| `POST`  | `/api/workflows/:workflowId/resume-async` | Reprendre de manière asynchrone                                    |
| `GET`   | `/api/workflows/:workflowId/runs`         | Répertorier les exécutions de Workflow                             |
| `GET`   | `/api/workflows/:workflowId/runs/:runId`  | Obtenir une exécution précise                                      |

### Réponse du nombre d’exécutions

Le point de terminaison `/api/workflows/run-counts` renvoie le nombre d’exécutions `running` et [`suspended`](https://mastra.zisheng.pro/fr/docs/workflows/suspend-and-resume) de chaque Workflow enregistré. L’enregistrement est indexé par la clé de registre du Workflow issue de la configuration Mastra, et le serveur peut mettre la réponse en cache pendant quelques secondes :

```typescript
{
  [workflowRegistryKey: string]: {
    running: number;
    suspended: number;
  };
}
```

### Workflows dynamiques

Les définitions de Workflows dynamiques (bêta) sont des Workflows exprimés en JSON, conservés par le domaine de stockage `workflowDefinitions` et enregistrés à chaud dans l’instance en cours. Consultez les [Workflows dynamiques](https://mastra.zisheng.pro/fr/docs/workflows/dynamic-workflows).

| Méthode  | Chemin                                     | Description                                                                                         |
| -------- | ------------------------------------------ | --------------------------------------------------------------------------------------------------- |
| `GET`    | `/api/stored/workflows`                    | Répertorier les définitions de Workflows dynamiques, filtrables par `status` et `authorId`          |
| `GET`    | `/api/stored/workflows/:dynamicWorkflowId` | Obtenir une définition de Workflow dynamique par ID                                                 |
| `POST`   | `/api/stored/workflows`                    | Upserter une définition (avec des `dependencies` auxiliaires facultatives) et l’enregistrer à chaud |
| `DELETE` | `/api/stored/workflows/:dynamicWorkflowId` | Supprimer une définition de Workflow dynamique et désenregistrer le Workflow actif                  |

Sur les serveurs authentifiés, les routes de lecture nécessitent l’autorisation `stored-workflows:read` et les routes d’écriture `stored-workflows:write`. Les Workflows dynamiques enregistrés sont exécutés via les routes ordinaires `/api/workflows/:workflowId` ci-dessus.

### Corps de la requête de création d’une exécution

```typescript
{
  resourceId?: string;     // Associate run with a resource (e.g., user ID)
  disableScorers?: boolean; // Disable scorers for this run
}
```

### Corps de la requête pour `/start-async`

```typescript
{
  resourceId?: string;     // Associate run with a resource (e.g., user ID)
  inputData?: unknown;
  initialState?: unknown;
  requestContext?: Record<string, unknown>;
  tracingOptions?: {
    spanName?: string;
    attributes?: Record<string, unknown>;
  };
}
```

### Corps de la requête de streaming d’un Workflow

```typescript
{
  resourceId?: string;     // Associate run with a resource (e.g., user ID)
  inputData?: unknown;
  initialState?: unknown;
  requestContext?: Record<string, unknown>;
  closeOnSuspend?: boolean;
}
```

### Corps de la requête de reprise

```typescript
{
  step?: string | string[];
  resumeData?: unknown;
  requestContext?: Record<string, unknown>;
}
```

## Tools

| Méthode | Chemin                       | Description                |
| ------- | ---------------------------- | -------------------------- |
| `GET`   | `/api/tools`                 | Répertorier tous les Tools |
| `GET`   | `/api/tools/:toolId`         | Obtenir un Tool par ID     |
| `POST`  | `/api/tools/:toolId/execute` | Exécuter un Tool           |

### Corps de la requête d’exécution d’un Tool

```typescript
{
  data: unknown;  // Tool input data
  requestContext?: Record<string, unknown>;
}
```

## Memory

| Méthode  | Chemin                                   | Description                   |
| -------- | ---------------------------------------- | ----------------------------- |
| `GET`    | `/api/memory/threads`                    | Répertorier les fils          |
| `GET`    | `/api/memory/threads/:threadId`          | Obtenir un fil                |
| `POST`   | `/api/memory/threads`                    | Créer un fil                  |
| `DELETE` | `/api/memory/threads/:threadId`          | Supprimer un fil              |
| `POST`   | `/api/memory/threads/:threadId/clone`    | Cloner un fil                 |
| `GET`    | `/api/memory/threads/:threadId/messages` | Obtenir les messages d’un fil |
| `POST`   | `/api/memory/threads/:threadId/messages` | Ajouter un message            |

### Corps de la requête de création d’un fil

```typescript
{
  resourceId: string;
  title?: string;
  metadata?: Record<string, unknown>;
}
```

### Corps de la requête de clonage d’un fil

```typescript
{
  newThreadId?: string;           // Custom ID for cloned thread
  resourceId?: string;            // Override resource ID
  title?: string;                 // Custom title for clone
  metadata?: Record<string, unknown>;  // Additional metadata
  options?: {
    messageLimit?: number;        // Max messages to clone
    messageFilter?: {
      startDate?: Date;           // Clone messages after this date
      endDate?: Date;             // Clone messages before this date
      messageIds?: string[];      // Clone specific messages
    };
  };
}
```

### Réponse de clonage d’un fil

```typescript
{
  thread: {
    id: string;
    resourceId: string;
    title: string;
    createdAt: Date;
    updatedAt: Date;
    metadata: {
      clone: {
        sourceThreadId: string;
        clonedAt: Date;
        lastMessageId?: string;
      };
      // ... other metadata
    };
  };
  clonedMessages: MastraDBMessage[];
}
```

## Vectors

| Méthode | Chemin                            | Description             |
| ------- | --------------------------------- | ----------------------- |
| `POST`  | `/api/vectors/:vectorName/upsert` | Upserter des vecteurs   |
| `POST`  | `/api/vectors/:vectorName/query`  | Interroger les vecteurs |
| `POST`  | `/api/vectors/:vectorName/delete` | Supprimer des vecteurs  |

### Corps de la requête d’upsert

```typescript
{
  vectors: Array<{
    id: string
    values: number[]
    metadata?: Record<string, unknown>
  }>
}
```

### Corps de la requête d’interrogation

```typescript
{
  vector: number[];
  topK?: number;
  filter?: Record<string, unknown>;
  includeMetadata?: boolean;
}
```

## MCP

| Méthode | Chemin                             | Description                      |
| ------- | ---------------------------------- | -------------------------------- |
| `GET`   | `/api/mcp/servers`                 | Répertorier les serveurs MCP     |
| `GET`   | `/api/mcp/servers/:serverId/tools` | Répertorier les Tools du serveur |
| `POST`  | `/api/mcp/:serverId`               | Transport HTTP MCP               |
| `GET`   | `/api/mcp/:serverId/sse`           | Transport SSE MCP                |

## Responses API

| Méthode  | Chemin                          | Description                                                              |
| -------- | ------------------------------- | ------------------------------------------------------------------------ |
| `POST`   | `/api/v1/responses`             | Créer une réponse via la route de l’API Responses compatible avec OpenAI |
| `GET`    | `/api/v1/responses/:responseId` | Récupérer une réponse stockée                                            |
| `DELETE` | `/api/v1/responses/:responseId` | Supprimer une réponse stockée                                            |

Pour connaître le contrat complet de requête et de réponse, consultez la [référence de l’API Responses](https://mastra.zisheng.pro/fr/reference/client-js/responses).

## Conversations API

| Méthode  | Chemin                                        | Description                                         |
| -------- | --------------------------------------------- | --------------------------------------------------- |
| `POST`   | `/api/v1/conversations`                       | Créer une conversation                              |
| `GET`    | `/api/v1/conversations/:conversationId`       | Récupérer une conversation                          |
| `DELETE` | `/api/v1/conversations/:conversationId`       | Supprimer une conversation                          |
| `GET`    | `/api/v1/conversations/:conversationId/items` | Répertorier les éléments stockés d’une conversation |

Pour connaître le contrat complet de requête et de réponse, consultez la [référence de l’API Conversations](https://mastra.zisheng.pro/fr/reference/client-js/conversations).

## Logs

| Méthode | Chemin             | Description                         |
| ------- | ------------------ | ----------------------------------- |
| `GET`   | `/api/logs`        | Répertorier les logs                |
| `GET`   | `/api/logs/:runId` | Obtenir les logs par ID d’exécution |

### Paramètres de requête

```typescript
{
  page?: number;
  perPage?: number;
  transportId?: string;
}
```

## Telemetry

| Méthode | Chemin                                 | Description                   |
| ------- | -------------------------------------- | ----------------------------- |
| `GET`   | `/api/telemetry/traces`                | Répertorier les traces        |
| `GET`   | `/api/telemetry/traces/:traceId`       | Obtenir une trace             |
| `GET`   | `/api/telemetry/traces/:traceId/spans` | Obtenir les spans d’une trace |

## Paramètres de requête communs

### Pagination

La plupart des points de terminaison de liste prennent en charge :

```typescript
{
  page?: number;   // Page number (0-indexed)
  perPage?: number; // Items per page (default: 10)
}
```

### Filtrage

Les exécutions de Workflows prennent en charge :

```typescript
{
  fromDate?: string;  // ISO date string
  toDate?: string;    // ISO date string
  status?: string;    // Run status filter
  resourceId?: string; // Filter by resource
}
```

## Réponses d’erreur

Toutes les routes renvoient les erreurs dans ce format :

```typescript
{
  error: string;      // Error message
  details?: unknown;  // Additional details
}
```

Codes d’état courants :

| Code | Signification                                      |
| ---- | -------------------------------------------------- |
| 400  | Requête incorrecte - Paramètres non valides        |
| 401  | Non autorisé - Authentification absente/non valide |
| 403  | Interdit - Autorisations insuffisantes             |
| 404  | Introuvable - La ressource n’existe pas            |
| 500  | Erreur interne du serveur                          |

## Ressources associées

- [createRoute()](https://mastra.zisheng.pro/fr/reference/server/create-route) : créer des routes personnalisées
- [Adapters de serveur](https://mastra.zisheng.pro/fr/docs/server/server-adapters) : utiliser les Adapters