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.

# 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

{
  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

{
  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 :

{
  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

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

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 :

{
  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 :

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

La route renvoie :

{
  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 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 :

{
  [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.

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

{
  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

{
  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

{
  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

{
  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

{
  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

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

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

{
  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

{
  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

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

Corps de la requête d’interrogation

{
  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.

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.

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

{
  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 :

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

Filtrage

Les exécutions de Workflows prennent en charge :

{
  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 :

{
  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() : créer des routes personnalisées
• Adapters de serveur : utiliser les Adapters