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

{
  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

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

Stream workflow request body

{
  inputData?: unknown;
  initialState?: unknown;
  requestContext?: Record<string, unknown>;
  closeOnSuspend?: boolean;
}

Resume request body

{
  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

{
  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
GET	/api/memory/threads/:threadId/messages	Get thread messages
POST	/api/memory/threads/:threadId/messages	Add message

Create thread request body

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

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

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

Query request body

{
  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

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

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

Or offset-based:

{
  offset?: number; // Skip N items
  limit?: number;  // Max items (default: 50)
}

Filtering

Workflow runs support:

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

{
  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() - Creating custom routes
• Server Adapters - Using adapters