서버 경로

서버 어댑터는 호출할 때 이러한 경로를 등록합니다.server.init(). 모든 경로에는prefix옵션이 구성된 경우.

Agent

방법	경로	설명
GET	/api/agents	List all agents
GET	/api/agents/:agentId	ID로 Agent 가져오기(버전 쿼리 매개변수 지원)
POST	/api/agents/:agentId/generate	Agent 응답 생성
POST	/api/agents/:agentId/stream	스트림 Agent 응답
POST	/api/agents/:agentId/send-message	활성 또는 유휴 스레드에 사용자 메시지 보내기
POST	/api/agents/:agentId/queue-message	다음 스레드 차례를 위해 사용자 메시지 대기열에 넣기
POST	/api/agents/:agentId/signals	활성 스레드나 유휴 스레드에 하위 수준 신호 보내기
POST	/api/agents/:agentId/threads/subscribe	스레드 스트림 구독
POST	/api/agents/:agentId/send-tool-approval	Tool 호출을 승인 또는 거부하고 스레드 구독을 통해 재개
POST	/api/agents/:agentId/resume-stream	사용자 정의 데이터를 사용하여 일시중단된 Agent 스트림 재개
GET	/api/agents/:agentId/tools	Agent Tool 나열
POST	/api/agents/:agentId/tools/:toolId/execute	Agent Tool 실행

Agent 쿼리 매개변수 가져오기

GET /api/agents/:agentId코드 정의 Agent에 대한 재정의로 적용되는 저장된 구성 버전을 제어하기 위해 선택적 쿼리 매개 변수를 허용합니다.

매개변수	유형	기본값	설명
status	'draft' | 'published'	'published'	확인할 저장 버전입니다. draft는 최신 버전을 반환하고 published는 활성 버전을 반환합니다.
versionId	string	없음	확인할 특정 버전 ID입니다. 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

요청 본문 생성

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

응답 생성

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

Agent 메시지 경로

활성 Agent 루프에 사용자 메시지를 보내거나 유휴 스레드를 깨우려면 POST /api/agents/:agentId/send-message를 사용하세요. Mastra가 후속 실행을 시작하기 전에 활성 실행이 완료되어야 한다면 POST /api/agents/:agentId/queue-message를 사용하세요. 두 경로 모두 동일한 요청 본문을 허용합니다.

{
  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>;
  };
}

runId를 생략하면 resourceId와 threadId가 필요합니다. ifIdle은 실행 대상 요청이 아니라 스레드 대상 요청에만 적용됩니다.

메시지 보내기

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"
  }'

메시지 대기열에 넣기

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"
  }'

두 경로 모두 다음을 반환합니다.

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

구독 Tool 승인 경로

클라이언트에 이미 활성 스레드 구독이 있다면 POST /api/agents/:agentId/send-tool-approval을 사용하세요. 이 경로는 실행을 재개하고 JSON 확인 응답을 반환합니다. 재개된 스트림 청크는 POST /api/agents/:agentId/threads/subscribe를 통해 전달됩니다. 경로는 다음 요청 본문을 수락합니다.

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

경로는 다음을 반환합니다.

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

Workflow

메서드	경로	설명
GET	/api/workflows	모든 Workflow 나열
GET	/api/workflows/run-counts	Workflow별 실행 중이거나 일시 중단된 실행 수 가져오기
GET	/api/workflows/:workflowId	ID로 Workflow 가져오기
POST	/api/workflows/:workflowId/create-run	새 Workflow 실행 생성
POST	/api/workflows/:workflowId/start-async	Workflow를 시작하고 결과 대기
POST	/api/workflows/:workflowId/stream	Workflow 실행 스트리밍
POST	/api/workflows/:workflowId/resume	일시 중단된 Workflow 재개
POST	/api/workflows/:workflowId/resume-async	비동기식으로 재개
GET	/api/workflows/:workflowId/runs	Workflow 실행 나열
GET	/api/workflows/:workflowId/runs/:runId	특정 실행 가져오기

실행 횟수 응답

/api/workflows/run-counts 엔드포인트는 등록된 모든 Workflow의 running 및 suspended 실행 수를 반환합니다. 레코드의 키는 Mastra 구성에 있는 Workflow의 레지스트리 키이며, 서버는 응답을 몇 초 동안 캐시할 수 있습니다.

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

동적 Workflow

동적 Workflow 정의(베타)는 JSON으로 표현되고 workflowDefinitions 저장소 도메인에 저장되며 실행 중인 인스턴스에 실시간으로 등록됩니다. 동적 Workflow를 참조하세요.

메서드	경로	설명
GET	/api/stored/workflows	status와 authorId로 필터링할 수 있는 동적 Workflow 정의 나열
GET	/api/stored/workflows/:dynamicWorkflowId	ID로 동적 Workflow 정의 가져오기
POST	/api/stored/workflows	정의를 업서트하고(선택적 도우미 dependencies 포함) 실시간으로 등록
DELETE	/api/stored/workflows/:dynamicWorkflowId	동적 Workflow 정의를 삭제하고 실시간 Workflow 등록 해제
인증된 서버에서 읽기 경로에는 stored-workflows:read 권한이 필요하고 쓰기 경로에는 stored-workflows:write 권한이 필요합니다. 등록된 동적 Workflow는 위의 일반 /api/workflows/:workflowId 경로를 통해 실행됩니다.

실행 요청 본문 만들기

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

요청 본문/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>;
  };
}

스트림 Workflow 요청 본문

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

이력서 요청 본문

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

Tool

메서드	경로	설명
GET	/api/tools	모든 Tool 나열
GET	/api/tools/:toolId	ID로 Tool 가져오기
POST	/api/tools/:toolId/execute	Tool 실행

Tool 요청 본문 실행

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

Memory

메서드	경로	설명
GET	/api/memory/threads	스레드 나열
GET	/api/memory/threads/:threadId	스레드 가져오기
POST	/api/memory/threads	스레드 생성
DELETE	/api/memory/threads/:threadId	스레드 삭제
POST	/api/memory/threads/:threadId/clone	스레드 복제
GET	/api/memory/threads/:threadId/messages	스레드 메시지 가져오기
POST	/api/memory/threads/:threadId/messages	메시지 추가

스레드 요청 본문 만들기

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

복제 스레드 요청 본문

{
  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
    };
  };
}

클론 스레드 응답

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

벡터

방법	경로	설명
POST	/api/vectors/:vectorName/upsert	Upsert vectors
POST	/api/vectors/:vectorName/query	Query vectors
POST	/api/vectors/:vectorName/delete	Delete vectors

요청 본문 업데이트

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

쿼리 요청 본문

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

MCP

방법	경로	설명
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

응답 API

메서드	경로	설명
POST	/api/v1/responses	OpenAI 호환 Responses API 경로를 통해 응답 생성
GET	/api/v1/responses/:responseId	저장된 응답 조회
DELETE	/api/v1/responses/:responseId	저장된 응답 삭제
전체 요청 및 응답 계약은 다음을 참조하세요.Responses API reference.

대화 API

메서드	경로	설명
POST	/api/v1/conversations	대화 생성
GET	/api/v1/conversations/:conversationId	대화 조회
DELETE	/api/v1/conversations/:conversationId	대화 삭제
GET	/api/v1/conversations/:conversationId/items	대화에 저장된 항목 나열
전체 요청 및 응답 계약은 다음을 참조하세요.Conversations API reference.

로그

메서드	경로	설명
GET	/api/logs	로그 나열
GET	/api/logs/:runId	실행 ID로 로그 가져오기

쿼리 매개변수

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

원격 측정

방법	경로	설명
GET	/api/telemetry/traces	List traces
GET	/api/telemetry/traces/:traceId	Get trace
GET	/api/telemetry/traces/:traceId/spans	Get trace spans

일반적인 쿼리 매개변수

쪽수 매기기

대부분의 목록 끝점은 다음을 지원합니다.

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

필터링

Workflow 실행 지원:

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

오류 응답

모든 경로는 다음 형식으로 오류를 반환합니다.

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

일반적인 상태 코드:

코드	의미
400	잘못된 요청 - 잘못된 매개변수
401	승인되지 않음 - 인증 누락/잘못
403	금지됨 - 권한 부족
404	찾을 수 없음 - 리소스가 존재하지 않습니다
500	내부 서버 오류

관련된

• 경로 생성(): 커스텀 경로 생성
• 서버 어댑터: 어댑터 사용