@mastra/server 1.6.0 → 1.7.0

package/dist/docs/references/reference-server-routes.md

@@ -1,306 +0,0 @@
-# Server Routes
-
-Server adapters register these routes when you call `server.init()`. All routes are prefixed with the `prefix` option if configured.
-
-## Agents
-
-| Method | Path                                         | Description             |
-| ------ | -------------------------------------------- | ----------------------- |
-| `GET`  | `/api/agents`                                | List all agents         |
-| `GET`  | `/api/agents/:agentId`                       | Get agent by ID         |
-| `POST` | `/api/agents/:agentId/generate`              | Generate agent response |
-| `POST` | `/api/agents/:agentId/stream`                | Stream agent response   |
-| `GET`  | `/api/agents/:agentId/tools`                 | List agent tools        |
-| `POST` | `/api/agents/:agentId/tools/:toolId/execute` | Execute agent tool      |
-
-### Generate request body
-
-```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
-}
-```
-
-### Generate response
-
-```typescript
-{
-  text: string;
-  toolCalls?: ToolCall[];
-  finishReason: string;
-  usage?: {
-    promptTokens: number;
-    completionTokens: number;
-  };
-}
-```
-
-## Workflows
-
-| Method | Path                                      | Description                     |
-| ------ | ----------------------------------------- | ------------------------------- |
-| `GET`  | `/api/workflows`                          | List all workflows              |
-| `GET`  | `/api/workflows/:workflowId`              | Get workflow by ID              |
-| `POST` | `/api/workflows/:workflowId/create-run`   | Create a new workflow run       |
-| `POST` | `/api/workflows/:workflowId/start-async`  | Start workflow and await result |
-| `POST` | `/api/workflows/:workflowId/stream`       | Stream workflow execution       |
-| `POST` | `/api/workflows/:workflowId/resume`       | Resume suspended workflow       |
-| `POST` | `/api/workflows/:workflowId/resume-async` | Resume asynchronously           |
-| `GET`  | `/api/workflows/:workflowId/runs`         | List workflow runs              |
-| `GET`  | `/api/workflows/:workflowId/runs/:runId`  | Get specific run                |
-
-### Create run request body
-
-```typescript
-{
-  resourceId?: string;     // Associate run with a resource (e.g., user ID)
-  disableScorers?: boolean; // Disable scorers for this run
-}
-```
-
-### Start-async request body
-
-```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>;
-  };
-}
-```
-
-### Stream workflow request body
-
-```typescript
-{
-  resourceId?: string;     // Associate run with a resource (e.g., user ID)
-  inputData?: unknown;
-  initialState?: unknown;
-  requestContext?: Record<string, unknown>;
-  closeOnSuspend?: boolean;
-}
-```
-
-### Resume request body
-
-```typescript
-{
-  step?: string | string[];
-  resumeData?: unknown;
-  requestContext?: Record<string, unknown>;
-}
-```
-
-## Tools
-
-| Method | Path                         | Description    |
-| ------ | ---------------------------- | -------------- |
-| `GET`  | `/api/tools`                 | List all tools |
-| `GET`  | `/api/tools/:toolId`         | Get tool by ID |
-| `POST` | `/api/tools/:toolId/execute` | Execute tool   |
-
-### Execute tool request body
-
-```typescript
-{
-  data: unknown;  // Tool input data
-  requestContext?: Record<string, unknown>;
-}
-```
-
-## Memory
-
-| Method   | Path                                     | Description         |
-| -------- | ---------------------------------------- | ------------------- |
-| `GET`    | `/api/memory/threads`                    | List threads        |
-| `GET`    | `/api/memory/threads/:threadId`          | Get thread          |
-| `POST`   | `/api/memory/threads`                    | Create thread       |
-| `DELETE` | `/api/memory/threads/:threadId`          | Delete thread       |
-| `POST`   | `/api/memory/threads/:threadId/clone`    | Clone thread        |
-| `GET`    | `/api/memory/threads/:threadId/messages` | Get thread messages |
-| `POST`   | `/api/memory/threads/:threadId/messages` | Add message         |
-
-### Create thread request body
-
-```typescript
-{
-  resourceId: string;
-  title?: string;
-  metadata?: Record<string, unknown>;
-}
-```
-
-### Clone thread request body
-
-```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
-    };
-  };
-}
-```
-
-### Clone thread response
-
-```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
-
-| Method | Path                              | Description    |
-| ------ | --------------------------------- | -------------- |
-| `POST` | `/api/vectors/:vectorName/upsert` | Upsert vectors |
-| `POST` | `/api/vectors/:vectorName/query`  | Query vectors  |
-| `POST` | `/api/vectors/:vectorName/delete` | Delete vectors |
-
-### Upsert request body
-
-```typescript
-{
-  vectors: Array<{
-    id: string;
-    values: number[];
-    metadata?: Record<string, unknown>;
-  }>;
-}
-```
-
-### Query request body
-
-```typescript
-{
-  vector: number[];
-  topK?: number;
-  filter?: Record<string, unknown>;
-  includeMetadata?: boolean;
-}
-```
-
-## MCP
-
-| Method | Path                               | Description        |
-| ------ | ---------------------------------- | ------------------ |
-| `GET`  | `/api/mcp/servers`                 | List MCP servers   |
-| `GET`  | `/api/mcp/servers/:serverId/tools` | List server tools  |
-| `POST` | `/api/mcp/:serverId`               | MCP HTTP transport |
-| `GET`  | `/api/mcp/:serverId/sse`           | MCP SSE transport  |
-
-## Logs
-
-| Method | Path               | Description        |
-| ------ | ------------------ | ------------------ |
-| `GET`  | `/api/logs`        | List logs          |
-| `GET`  | `/api/logs/:runId` | Get logs by run ID |
-
-### Query parameters
-
-```typescript
-{
-  page?: number;
-  perPage?: number;
-  transportId?: string;
-}
-```
-
-## Telemetry
-
-| Method | Path                                   | Description     |
-| ------ | -------------------------------------- | --------------- |
-| `GET`  | `/api/telemetry/traces`                | List traces     |
-| `GET`  | `/api/telemetry/traces/:traceId`       | Get trace       |
-| `GET`  | `/api/telemetry/traces/:traceId/spans` | Get trace spans |
-
-## Common query parameters
-
-### Pagination
-
-Most list endpoints support:
-
-```typescript
-{
-  page?: number;   // Page number (0-indexed)
-  perPage?: number; // Items per page (default: 10)
-}
-```
-
-### Filtering
-
-Workflow runs support:
-
-```typescript
-{
-  fromDate?: string;  // ISO date string
-  toDate?: string;    // ISO date string
-  status?: string;    // Run status filter
-  resourceId?: string; // Filter by resource
-}
-```
-
-## Error responses
-
-All routes return errors in this format:
-
-```typescript
-{
-  error: string;      // Error message
-  details?: unknown;  // Additional details
-}
-```
-
-Common status codes:
-
-| Code | Meaning                              |
-| ---- | ------------------------------------ |
-| 400  | Bad Request - Invalid parameters     |
-| 401  | Unauthorized - Missing/invalid auth  |
-| 403  | Forbidden - Insufficient permissions |
-| 404  | Not Found - Resource doesn't exist   |
-| 500  | Internal Server Error                |
-
-## Related
-
-- [createRoute()](https://mastra.ai/reference/server/create-route) - Creating custom routes
-- [Server Adapters](https://mastra.ai/docs/server/server-adapters) - Using adapters