> ## Documentation Index > Fetch the complete documentation index at: https://docs.tryvox.co/llms.txt > Use this file to discover all available pages before exploring further. # 플로우 검증 > `flow`(`{nodes, edges}`)를 저장하지 않고 검증합니다. `valid`는 저장 가능 여부를 나타내며, 저장을 막는 치명적 오류가 없으면 `true`입니다. 런타임 주의 항목은 `valid`에 영향을 주지 않습니다. `?agent_id`를 주면 해당 에이전트의 현재 `flow`를 기준으로 수정(PATCH) 시 적용되는 참조 검사(orphan·dangling·multifanout)까지 포함합니다. `?level`로 응답에 포함할 항목 범주(`critical`/`runtime`/`all`)를 정합니다. 런타임 주의 항목(저장은 가능하지만 실행 중 동작이 달라질 수 있음): - `unconnected_skip_user_response_transition`: skip/wakeup 전환 행에 나가는 전환이 없습니다. - `unconnected_fallback_transition`: fallback 전환 행에 나가는 전환이 없습니다. - `no_terminal_reachable`: begin 노드에서 도달 가능한 종료 노드(endCall / transferCall / transferAgent)가 없습니다. ## OpenAPI ````yaml /api-reference/v3/openapi.json post /agents/validate-flow openapi: 3.1.0 info: title: vox.ai API description: > vox.ai API v3 ### v3 공개 계약 규칙 - 인증은 `Authorization: Bearer ` 헤더를 사용합니다. 조직 API 키를 Bearer 토큰으로 전달합니다. - 요청과 응답 필드는 기본적으로 `snake_case`를 사용합니다. - `agent.data`는 에이전트 레지스트리와 호환되어야 하므로 `callSettings`, `toolIds`, `builtInTools`, `presetDynamicVariables` 같은 camelCase 필드를 유지합니다. - `_at`으로 끝나는 타임스탬프는 unix milliseconds입니다. 일부 입력값은 호환성을 위해 10~11자리 unix seconds도 허용하고 milliseconds로 정규화합니다. - 캠페인 통화 가능 시간은 분 단위 정수(`start_min` / `end_min`)를 사용합니다. 알림 스케줄은 `HH:MM` 문자열(`start_time` / `end_time`)을 사용합니다. - 응답 객체 자신의 식별자는 `id`입니다. 다른 리소스를 참조하는 필드와 path parameter는 `agent_id`, `call_id`, `telephone_line_id`처럼 명시적인 이름을 사용합니다. - 실패 응답은 `{ "error": { "code", "message", "details" } }` 형태입니다. 가능한 경우 `details.field`, `details.reason`, `details.allowed_values`를 함께 제공합니다. version: 3.0.0 servers: - url: https://client-api.tryvox.co/v3 description: 운영 security: [] paths: /agents/validate-flow: post: tags: - Agents summary: 플로우 검증 description: >- `flow`(`{nodes, edges}`)를 저장하지 않고 검증합니다. `valid`는 저장 가능 여부를 나타내며, 저장을 막는 치명적 오류가 없으면 `true`입니다. 런타임 주의 항목은 `valid`에 영향을 주지 않습니다. `?agent_id`를 주면 해당 에이전트의 현재 `flow`를 기준으로 수정(PATCH) 시 적용되는 참조 검사(orphan·dangling·multifanout)까지 포함합니다. `?level`로 응답에 포함할 항목 범주(`critical`/`runtime`/`all`)를 정합니다. 런타임 주의 항목(저장은 가능하지만 실행 중 동작이 달라질 수 있음): - `unconnected_skip_user_response_transition`: skip/wakeup 전환 행에 나가는 전환이 없습니다. - `unconnected_fallback_transition`: fallback 전환 행에 나가는 전환이 없습니다. - `no_terminal_reachable`: begin 노드에서 도달 가능한 종료 노드(endCall / transferCall / transferAgent)가 없습니다. operationId: validateFlow parameters: - name: level in: query required: false schema: enum: - critical - runtime - all type: string description: >- 항목 레벨 필터입니다. `critical`(기본값)은 저장 차단 오류만, `runtime`은 주의 항목만, `all`은 둘 다 반환합니다. default: critical title: Level description: >- 항목 레벨 필터입니다. `critical`(기본값)은 저장 차단 오류만, `runtime`은 주의 항목만, `all`은 둘 다 반환합니다. - name: agent_id in: query required: false schema: anyOf: - type: string format: uuid - type: 'null' description: >- 수정(PATCH) 검증 대상 에이전트 UUID입니다. 설정하면 해당 에이전트의 현재 `flow`를 기준으로 참조 검사(orphan·dangling·multifanout)를 함께 수행합니다. 생략하면 생성 기준으로 검증합니다. title: Agent Id description: >- 수정(PATCH) 검증 대상 에이전트 UUID입니다. 설정하면 해당 에이전트의 현재 `flow`를 기준으로 참조 검사(orphan·dangling·multifanout)를 함께 수행합니다. 생략하면 생성 기준으로 검증합니다. requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ValidateFlowRequest' description: '검증할 `flow` 그래프입니다(`{flow: {nodes, edges}}`).' responses: '200': description: 성공 응답 content: application/json: schema: $ref: '#/components/schemas/ValidateFlowResponse' '400': description: 요청 검증 오류 content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: validationError: summary: 요청 검증 오류 value: error: code: VALIDATION_ERROR message: Request validation failed. details: field: name reason: must not be blank '401': description: 인증이 필요합니다. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: unauthorized: summary: Bearer 토큰 누락 또는 오류 value: error: code: UNAUTHORIZED message: Authentication is required. details: {} '403': description: 권한이 없습니다. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: forbidden: summary: 권한이 없습니다. value: error: code: FORBIDDEN message: Permission denied. details: {} '404': description: 리소스를 찾을 수 없습니다. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: notFound: summary: 리소스를 찾을 수 없습니다. value: error: code: RESOURCE_NOT_FOUND message: Resource not found. details: resource: agent '409': description: 충돌이 발생했습니다. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: conflict: summary: 상태 충돌이 발생했습니다. value: error: code: CONFLICT message: The requested operation conflicts with current state. details: current_status: draft '429': description: 요청 한도를 초과했습니다. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: rateLimited: summary: 요청 한도를 초과했습니다. value: error: code: RATE_LIMIT_EXCEEDED message: Too many requests. details: limit: 5 window_seconds: 1 '500': description: 서버 내부 오류가 발생했습니다. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: internalError: summary: 서버 내부 오류가 발생했습니다. value: error: code: INTERNAL_ERROR message: Internal server error. details: {} '503': description: 서비스를 일시적으로 사용할 수 없습니다. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: serviceUnavailable: summary: 서비스를 일시적으로 사용할 수 없습니다. value: error: code: SERVICE_UNAVAILABLE message: Service temporarily unavailable. details: {} security: - BearerAuth: [] components: schemas: ValidateFlowRequest: properties: flow: allOf: - $ref: '#/components/schemas/FlowInput' description: 저장하지 않고 검증할 `flow` graph({nodes, edges})입니다. type: object required: - flow title: ValidateFlowRequest description: POST /v3/agents/validate-flow 요청 body입니다. ValidateFlowResponse: properties: valid: type: boolean title: Valid description: >- `flow`에 critical blocking issue가 없어 create/update로 안전하게 저장할 수 있으면 true입니다. runtime-level advisory는 이 값에 영향을 주지 않습니다. errors: items: $ref: '#/components/schemas/FlowValidationErrorItem' type: array title: Errors description: 저장을 막는 critical issue 목록입니다. advisories: items: $ref: '#/components/schemas/FlowValidationAdvisoryItem' type: array title: Advisories description: >- `?level=runtime` 또는 `?level=all` 요청에서 반환되는 runtime-level issue입니다. 저장을 막지는 않습니다. 예: 연결되지 않은 skip/fallback wakeup transition, 도달 가능한 terminal node 없음. type: object required: - valid title: ValidateFlowResponse description: POST /v3/agents/validate-flow 응답입니다. ErrorResponse: type: object required: - error title: ErrorResponse description: 모든 실패 응답에서 사용하는 v3 error envelope입니다. examples: - error: code: VALIDATION_ERROR message: Request validation failed. details: field: name reason: must not be blank properties: error: $ref: '#/components/schemas/ErrorDetail' description: 오류 payload입니다. FlowInput: properties: nodes: items: $ref: '#/components/schemas/FlowNode' type: array title: Nodes description: >- Flow builder node 목록입니다. 각 node는 `id`, `type`, 필수 `position`(`{x, y}` 캔버스 좌표), camelCase `data`를 가집니다. edges: items: $ref: '#/components/schemas/FlowEdgeInput' type: array title: Edges description: source와 target 노드 ID를 연결하는 flow builder edge 목록입니다. additionalProperties: false type: object required: - nodes - edges title: Flow description: '`flow` 문서입니다: `{nodes, edges}`.' FlowValidationErrorItem: properties: field: anyOf: - type: string - type: 'null' title: Field description: 유효하지 않은 필드의 dotted path입니다. message: type: string title: Message description: 수정 방법을 설명하는 실행 가능한 메시지입니다. code: anyOf: - type: string - type: 'null' title: Code description: 기계가 읽을 수 있는 안정적인 코드입니다. rule: anyOf: - type: string - type: 'null' title: Rule description: 이전 클라이언트 호환을 위한 선택적 validator rule ID입니다. node_id: anyOf: - type: string - type: 'null' title: Node Id description: 오류가 특정 플로우 노드에 적용될 때의 노드 ID입니다. suggestion: anyOf: - additionalProperties: true type: object - type: 'null' title: Suggestion description: 기계가 읽을 수 있는 선택적 수정 힌트입니다. doc: anyOf: - type: string - type: 'null' title: Doc description: 이 검증 이슈와 관련된 선택적 문서 포인터입니다. details: anyOf: - additionalProperties: true type: object - type: 'null' title: Details description: >- 기계가 읽을 수 있는 선택적 상세 payload입니다. reference validation issue는 문제가 된 값(예: SMS attachment 실패의 `file_key` / `purpose` / `storage_provider`, transferAgent lookup의 `agent_id`, `tool_id` / `knowledge_id`)을 이 필드로 전달하므로, MCP/flow-builder 클라이언트가 여러 `static_image_file_keys` 중 어떤 항목이 거부됐는지 추측하지 않고 per-item error를 표시할 수 있습니다. type: object required: - message title: FlowValidationErrorItem FlowValidationAdvisoryItem: properties: field: anyOf: - type: string - type: 'null' title: Field description: 관련 필드의 dotted path입니다. message: type: string title: Message description: advisory를 설명하는 안내 메시지입니다. code: anyOf: - type: string - type: 'null' title: Code description: 기계가 읽을 수 있는 안정적인 코드입니다. rule: anyOf: - type: string - type: 'null' title: Rule description: 검증 rule ID입니다. node_id: anyOf: - type: string - type: 'null' title: Node Id description: 이슈가 특정 노드에 적용될 때의 노드 ID입니다. level: type: string title: Level description: 심각도 레벨입니다. advisory item에서는 항상 `runtime`입니다. default: runtime type: object required: - message title: FlowValidationAdvisoryItem description: 저장을 막지 않는 advisory issue입니다(`level == "runtime"`). ErrorDetail: type: object required: - code - message - details title: ErrorDetail description: 기계가 읽을 수 있는 v3 오류 상세 정보입니다. examples: - code: VALIDATION_ERROR message: Request validation failed. details: field: name reason: must not be blank properties: code: type: string title: Code description: 기계가 읽을 수 있는 오류 code입니다. message parsing 대신 이 값을 사용합니다. examples: - VALIDATION_ERROR message: type: string title: Message description: 사용자에게 표시할 수 있는 오류 메시지입니다. 프로그램 처리는 `code`를 사용합니다. examples: - Request validation failed. details: type: object title: Details additionalProperties: true description: 구조화된 context입니다. 주로 `field`, `reason`, `allowed_values`를 포함합니다. FlowNode: title: FlowNode description: >- public `flow` graph node입니다. `type`이 discriminator이며 `data` schema를 결정합니다. oneOf: - $ref: '#/components/schemas/BeginFlowNode' - $ref: '#/components/schemas/ConversationFlowNode' - $ref: '#/components/schemas/ToolFlowNode' - $ref: '#/components/schemas/ConditionFlowNode' - $ref: '#/components/schemas/ExtractionFlowNode' - $ref: '#/components/schemas/ApiFlowNode' - $ref: '#/components/schemas/SendSmsFlowNode' - $ref: '#/components/schemas/TransferCallFlowNode' - $ref: '#/components/schemas/TransferAgentFlowNode' - $ref: '#/components/schemas/EndCallFlowNode' - $ref: '#/components/schemas/NoteFlowNode' discriminator: propertyName: type mapping: begin: $ref: '#/components/schemas/BeginFlowNode' conversation: $ref: '#/components/schemas/ConversationFlowNode' tool: $ref: '#/components/schemas/ToolFlowNode' condition: $ref: '#/components/schemas/ConditionFlowNode' extraction: $ref: '#/components/schemas/ExtractionFlowNode' api: $ref: '#/components/schemas/ApiFlowNode' sendSms: $ref: '#/components/schemas/SendSmsFlowNode' transferCall: $ref: '#/components/schemas/TransferCallFlowNode' transferAgent: $ref: '#/components/schemas/TransferAgentFlowNode' endCall: $ref: '#/components/schemas/EndCallFlowNode' note: $ref: '#/components/schemas/NoteFlowNode' FlowEdgeInput: properties: id: anyOf: - type: string minLength: 1 - type: 'null' title: Id description: 선택 사항입니다. 생략하면 서버가 생성하고, 제공하면 그대로 재사용합니다. 빈 문자열은 거부됩니다. source: type: string title: Source description: 출발 flow node ID입니다. target: type: string title: Target description: 도착 flow node ID입니다. condition: oneOf: - $ref: '#/components/schemas/AiCondition' - $ref: '#/components/schemas/LogicCondition' - $ref: '#/components/schemas/FallbackCondition' title: Condition discriminator: propertyName: type mapping: ai: $ref: '#/components/schemas/AiCondition' fallback: $ref: '#/components/schemas/FallbackCondition' logic: $ref: '#/components/schemas/LogicCondition' skip_user_response: type: boolean title: Skip User Response description: v1 `is_skip_user_response`에 해당합니다. 이 hop에서 사용자 응답을 기다리지 않고 이동합니다. default: false additionalProperties: false type: object required: - source - target - condition title: FlowEdge description: 'flow edge입니다: `{id?, source, target, condition, skip_user_response}`.' BeginFlowNode: type: object title: BeginFlowNode description: '`type=begin`인 public `flow` node입니다.' additionalProperties: false required: - id - type - position properties: id: type: string title: Id description: 응답 객체 자체의 ID 또는 중첩 설정 객체 안의 로컬 ID입니다. type: type: string const: begin description: flow node type `begin`의 discriminator 값입니다. position: $ref: '#/components/schemas/Position' description: >- node canvas 좌표 `{x, y}`입니다. 필수입니다. builder는 position 없이 node를 렌더링할 수 없고, 서버는 position을 새로 만들지 않습니다. data: $ref: '#/components/schemas/BeginFlowNodeData' description: '`begin` 노드의 타입별 data payload입니다.' ConversationFlowNode: type: object title: ConversationFlowNode description: '`type=conversation`인 public `flow` node입니다.' additionalProperties: false required: - id - type - position properties: id: type: string title: Id description: 응답 객체 자체의 ID 또는 중첩 설정 객체 안의 로컬 ID입니다. type: type: string const: conversation description: flow node type `conversation`의 discriminator 값입니다. position: $ref: '#/components/schemas/Position' description: >- node canvas 좌표 `{x, y}`입니다. 필수입니다. builder는 position 없이 node를 렌더링할 수 없고, 서버는 position을 새로 만들지 않습니다. data: $ref: '#/components/schemas/ConversationFlowNodeData' description: '`conversation` 노드의 타입별 data payload입니다.' ToolFlowNode: type: object title: ToolFlowNode description: '`type=tool`인 public `flow` node입니다.' additionalProperties: false required: - id - type - position properties: id: type: string title: Id description: 응답 객체 자체의 ID 또는 중첩 설정 객체 안의 로컬 ID입니다. type: type: string const: tool description: flow node type `tool`의 discriminator 값입니다. position: $ref: '#/components/schemas/Position' description: >- node canvas 좌표 `{x, y}`입니다. 필수입니다. builder는 position 없이 node를 렌더링할 수 없고, 서버는 position을 새로 만들지 않습니다. data: $ref: '#/components/schemas/ToolFlowNodeData' description: '`tool` 노드의 타입별 data payload입니다.' ConditionFlowNode: type: object title: ConditionFlowNode description: '`type=condition`인 public `flow` node입니다.' additionalProperties: false required: - id - type - position properties: id: type: string title: Id description: 응답 객체 자체의 ID 또는 중첩 설정 객체 안의 로컬 ID입니다. type: type: string const: condition description: flow node type `condition`의 discriminator 값입니다. position: $ref: '#/components/schemas/Position' description: >- node canvas 좌표 `{x, y}`입니다. 필수입니다. builder는 position 없이 node를 렌더링할 수 없고, 서버는 position을 새로 만들지 않습니다. data: $ref: '#/components/schemas/ConditionFlowNodeData' description: '`condition` 노드의 타입별 data payload입니다.' ExtractionFlowNode: type: object title: ExtractionFlowNode description: '`type=extraction`인 public `flow` node입니다.' additionalProperties: false required: - id - type - position properties: id: type: string title: Id description: 응답 객체 자체의 ID 또는 중첩 설정 객체 안의 로컬 ID입니다. type: type: string const: extraction description: flow node type `extraction`의 discriminator 값입니다. position: $ref: '#/components/schemas/Position' description: >- node canvas 좌표 `{x, y}`입니다. 필수입니다. builder는 position 없이 node를 렌더링할 수 없고, 서버는 position을 새로 만들지 않습니다. data: $ref: '#/components/schemas/ExtractionFlowNodeData' description: '`extraction` 노드의 타입별 data payload입니다.' ApiFlowNode: type: object title: ApiFlowNode description: '`type=api`인 public `flow` node입니다.' additionalProperties: false required: - id - type - position properties: id: type: string title: Id description: 응답 객체 자체의 ID 또는 중첩 설정 객체 안의 로컬 ID입니다. type: type: string const: api description: flow node type `api`의 discriminator 값입니다. position: $ref: '#/components/schemas/Position' description: >- node canvas 좌표 `{x, y}`입니다. 필수입니다. builder는 position 없이 node를 렌더링할 수 없고, 서버는 position을 새로 만들지 않습니다. data: $ref: '#/components/schemas/ApiFlowNodeData' description: '`api` 노드의 타입별 data payload입니다.' SendSmsFlowNode: type: object title: SendSmsFlowNode description: '`type=sendSms`인 public `flow` node입니다.' additionalProperties: false required: - id - type - position properties: id: type: string title: Id description: 응답 객체 자체의 ID 또는 중첩 설정 객체 안의 로컬 ID입니다. type: type: string const: sendSms description: flow node type `sendSms`의 discriminator 값입니다. position: $ref: '#/components/schemas/Position' description: >- node canvas 좌표 `{x, y}`입니다. 필수입니다. builder는 position 없이 node를 렌더링할 수 없고, 서버는 position을 새로 만들지 않습니다. data: $ref: '#/components/schemas/SendSmsFlowNodeData' description: '`sendSms` 노드의 타입별 data payload입니다.' TransferCallFlowNode: type: object title: TransferCallFlowNode description: '`type=transferCall`인 public `flow` node입니다.' additionalProperties: false required: - id - type - position properties: id: type: string title: Id description: 응답 객체 자체의 ID 또는 중첩 설정 객체 안의 로컬 ID입니다. type: type: string const: transferCall description: flow node type `transferCall`의 discriminator 값입니다. position: $ref: '#/components/schemas/Position' description: >- node canvas 좌표 `{x, y}`입니다. 필수입니다. builder는 position 없이 node를 렌더링할 수 없고, 서버는 position을 새로 만들지 않습니다. data: $ref: '#/components/schemas/TransferCallFlowNodeData' description: '`transferCall` 노드의 타입별 data payload입니다.' TransferAgentFlowNode: type: object title: TransferAgentFlowNode description: '`type=transferAgent`인 public `flow` node입니다.' additionalProperties: false required: - id - type - position properties: id: type: string title: Id description: 응답 객체 자체의 ID 또는 중첩 설정 객체 안의 로컬 ID입니다. type: type: string const: transferAgent description: flow node type `transferAgent`의 discriminator 값입니다. position: $ref: '#/components/schemas/Position' description: >- node canvas 좌표 `{x, y}`입니다. 필수입니다. builder는 position 없이 node를 렌더링할 수 없고, 서버는 position을 새로 만들지 않습니다. data: $ref: '#/components/schemas/TransferAgentFlowNodeData' description: '`transferAgent` 노드의 타입별 data payload입니다.' EndCallFlowNode: type: object title: EndCallFlowNode description: '`type=endCall`인 public `flow` node입니다.' additionalProperties: false required: - id - type - position properties: id: type: string title: Id description: 응답 객체 자체의 ID 또는 중첩 설정 객체 안의 로컬 ID입니다. type: type: string const: endCall description: flow node type `endCall`의 discriminator 값입니다. position: $ref: '#/components/schemas/Position' description: >- node canvas 좌표 `{x, y}`입니다. 필수입니다. builder는 position 없이 node를 렌더링할 수 없고, 서버는 position을 새로 만들지 않습니다. data: $ref: '#/components/schemas/EndCallFlowNodeData' description: '`endCall` 노드의 타입별 data payload입니다.' NoteFlowNode: type: object title: NoteFlowNode description: '`type=note`인 public `flow` node입니다.' additionalProperties: false required: - id - type - position properties: id: type: string title: Id description: 응답 객체 자체의 ID 또는 중첩 설정 객체 안의 로컬 ID입니다. type: type: string const: note description: flow node type `note`의 discriminator 값입니다. position: $ref: '#/components/schemas/Position' description: >- node canvas 좌표 `{x, y}`입니다. 필수입니다. builder는 position 없이 node를 렌더링할 수 없고, 서버는 position을 새로 만들지 않습니다. data: $ref: '#/components/schemas/NoteFlowNodeData' description: '`note` 노드의 타입별 data payload입니다.' AiCondition: additionalProperties: false description: runtime에서 LLM이 평가하는 자연어 edge condition입니다. properties: type: const: ai title: Type type: string description: 리소스 또는 설정 유형입니다. prompt: default: '' description: 자연어 transition condition입니다. title: Prompt type: string required: - type title: AiCondition type: object LogicCondition: properties: type: type: string const: logic title: Type description: 리소스 또는 설정 유형입니다. equations: items: $ref: '#/components/schemas/LogicEquation' type: array title: Equations operator: type: string enum: - '&&' - '||' title: Operator description: equation을 결합하는 방식입니다. `&&`는 AND, `||`는 OR입니다. default: '&&' additionalProperties: false type: object required: - type title: LogicCondition description: |- Retell과 정렬된 `equations` 형태를 사용하는 deterministic edge condition입니다. source node는 `condition` node여야 합니다(logic-source 제약은 별도 검증에서 강제됩니다). FallbackCondition: properties: type: type: string const: fallback title: Type description: 리소스 또는 설정 유형입니다. additionalProperties: false type: object required: - type title: FallbackCondition description: source node의 다른 condition이 맞지 않을 때 선택되는 기본 edge입니다. Position: properties: x: anyOf: - type: integer - type: number title: X 'y': anyOf: - type: integer - type: number title: 'Y' additionalProperties: false type: object required: - x - 'y' title: Position description: >- node canvas 좌표 `{x, y}`입니다. v2 surface에서 필수입니다. builder는 position 없이 node를 렌더링할 수 없고 서버는 position을 새로 만들지 않습니다. read -> edit -> write 흐름에서 layout을 보존하도록 그대로 전달됩니다. `int | float`는 builder의 integer 좌표를 integer로 유지해 lossless round-trip을 보장합니다. BeginFlowNodeData: additionalProperties: false properties: name: anyOf: - type: string - type: 'null' default: null description: >- 사람이 읽을 수 있는 node label입니다. 입력 시 선택 항목이며, 생략하면 서버가 node id에서 안정적인 label을 채워 저장하므로 저장된 그래프에는 항상 존재합니다. title: Name first_line_type: enum: - aiFirst - userFirst type: string description: flow begin node의 첫 발화 모드입니다. `aiFirst` 또는 `userFirst`를 사용합니다. title: First Line Type pause_before_speaking_seconds: anyOf: - maximum: 5 minimum: 0 type: number - type: 'null' default: null title: Pause Before Speaking Seconds description: 에이전트가 먼저 말하기 전 대기 시간(초)입니다. title: BeginFlowNodeData type: object description: >- public `flow` graph에서 node type `begin`의 타입별 `data` payload입니다. `transitions`, `logical_transitions`, `global_node_settings`는 `flow.edges`와 `data.global_node_setting`으로 표현되므로, 해당 builder routing key를 여기로 보내지 마세요. v2 surface는 strict합니다. write에서는 문서화된 node별 field와 `global_node_setting`만 허용하며, 다른 top-level key는 `FLOW_V2_INVALID`로 거부됩니다. required: - first_line_type ConversationFlowNodeData: additionalProperties: false properties: name: anyOf: - type: string - type: 'null' default: null description: >- 사람이 읽을 수 있는 node label입니다. 입력 시 선택 항목이며, 생략하면 서버가 node id에서 안정적인 label을 채워 저장하므로 저장된 그래프에는 항상 존재합니다. title: Name prompt_type: anyOf: - enum: - static - dynamic type: string - type: 'null' default: null title: Prompt Type prompt: anyOf: - type: string - type: 'null' default: null title: Prompt description: Agent prompt 설정입니다. static_sentence: anyOf: - type: string - type: 'null' default: null title: Static Sentence first_message: anyOf: - type: string - type: 'null' default: null title: First Message description: 이 conversation node에서 사용할 선택적 첫 메시지 override입니다. loop_condition: anyOf: - type: string - type: 'null' default: null title: Loop Condition description: conversation node의 반복 조건을 제어하는 조건문입니다. is_allow_interruption: anyOf: - type: boolean - type: 'null' default: null title: Is Allow Interruption description: 사용자가 이 node의 발화를 끊을 수 있는지 여부입니다. is_skip_user_response: anyOf: - type: boolean - type: 'null' default: null description: 이 conversation node가 말한 뒤 사용자 응답을 기다리지 않을지 여부입니다. title: Is Skip User Response llm: anyOf: - additionalProperties: true type: object - type: 'null' default: null title: Llm description: 대형 언어 모델 설정입니다. knowledge: anyOf: - $ref: '#/components/schemas/NodeKnowledgeConfig' - type: 'null' default: null description: Agent knowledge base 설정입니다. global_node_setting: $ref: '#/components/schemas/GlobalNodeSetting' description: >- node-level global marker입니다. 이 값이 있으면 해당 node는 global node로 처리됩니다. 일반 node에서는 생략하세요. 이 key를 사용해야 하며, legacy camelCase `globalNodeSettings`는 write 시 거부됩니다. title: ConversationFlowNodeData type: object description: >- public `flow` graph에서 node type `conversation`의 타입별 `data` payload입니다. `transitions`, `logical_transitions`, `global_node_settings`는 `flow.edges`와 `data.global_node_setting`으로 표현되므로, 해당 builder routing key를 여기로 보내지 마세요. v2 surface는 strict합니다. write에서는 문서화된 node별 field와 `global_node_setting`만 허용하며, 다른 top-level key는 `FLOW_V2_INVALID`로 거부됩니다. ToolFlowNodeData: additionalProperties: false properties: name: anyOf: - type: string - type: 'null' default: null description: >- 사람이 읽을 수 있는 node label입니다. 입력 시 선택 항목이며, 생략하면 서버가 node id에서 안정적인 label을 채워 저장하므로 저장된 그래프에는 항상 존재합니다. title: Name tool_id: anyOf: - type: string - type: 'null' default: null title: Tool Id description: Custom tool UUID입니다. `GET /v3/tools`에서 반환한 `id`를 사용하세요. prompt_type: anyOf: - enum: - none - static - dynamic type: string - type: 'null' default: null title: Prompt Type prompt: anyOf: - type: string - type: 'null' default: null title: Prompt description: Agent prompt 설정입니다. static_sentence: anyOf: - type: string - type: 'null' default: null title: Static Sentence title: ToolFlowNodeData type: object description: >- public `flow` graph에서 node type `tool`의 타입별 `data` payload입니다. `transitions`, `logical_transitions`, `global_node_settings`는 `flow.edges`와 `data.global_node_setting`으로 표현되므로, 해당 builder routing key를 여기로 보내지 마세요. v2 surface는 strict합니다. write에서는 문서화된 node별 field와 `global_node_setting`만 허용하며, 다른 top-level key는 `FLOW_V2_INVALID`로 거부됩니다. ConditionFlowNodeData: additionalProperties: false properties: name: anyOf: - type: string - type: 'null' default: null description: >- 사람이 읽을 수 있는 node label입니다. 입력 시 선택 항목이며, 생략하면 서버가 node id에서 안정적인 label을 채워 저장하므로 저장된 그래프에는 항상 존재합니다. title: Name title: ConditionFlowNodeData type: object description: >- public `flow` graph에서 node type `condition`의 타입별 `data` payload입니다. `transitions`, `logical_transitions`, `global_node_settings`는 `flow.edges`와 `data.global_node_setting`으로 표현되므로, 해당 builder routing key를 여기로 보내지 마세요. v2 surface는 strict합니다. write에서는 문서화된 node별 field와 `global_node_setting`만 허용하며, 다른 top-level key는 `FLOW_V2_INVALID`로 거부됩니다. ExtractionFlowNodeData: additionalProperties: false properties: name: anyOf: - type: string - type: 'null' default: null description: >- 사람이 읽을 수 있는 node label입니다. 입력 시 선택 항목이며, 생략하면 서버가 node id에서 안정적인 label을 채워 저장하므로 저장된 그래프에는 항상 존재합니다. title: Name extraction_configuration: $ref: '#/components/schemas/ExtractionConfiguration' is_skip_user_response: anyOf: - type: boolean - type: 'null' default: true title: Is Skip User Response description: 사용자 응답을 기다리지 않고 이 node를 실행할지 여부입니다. llm: anyOf: - additionalProperties: true type: object - type: 'null' default: null title: Llm description: 대형 언어 모델 설정입니다. title: ExtractionFlowNodeData type: object description: >- public `flow` graph에서 node type `extraction`의 타입별 `data` payload입니다. `transitions`, `logical_transitions`, `global_node_settings`는 `flow.edges`와 `data.global_node_setting`으로 표현되므로, 해당 builder routing key를 여기로 보내지 마세요. v2 surface는 strict합니다. write에서는 문서화된 node별 field와 `global_node_setting`만 허용하며, 다른 top-level key는 `FLOW_V2_INVALID`로 거부됩니다. ApiFlowNodeData: additionalProperties: false properties: name: anyOf: - type: string - type: 'null' default: null description: >- 사람이 읽을 수 있는 node label입니다. 입력 시 선택 항목이며, 생략하면 서버가 node id에서 안정적인 label을 채워 저장하므로 저장된 그래프에는 항상 존재합니다. title: Name response_mode: default: wait enum: - wait - fire_and_forget title: Response Mode type: string api_configuration: $ref: '#/components/schemas/ApiConfiguration' response_variables: items: $ref: '#/components/schemas/ApiResponseVariable' title: Response Variables type: array description: 이 API node 응답에서 추출한 변수 목록입니다. prompt_type: anyOf: - enum: - none - static - dynamic type: string - type: 'null' default: null title: Prompt Type prompt: anyOf: - type: string - type: 'null' default: null title: Prompt description: Agent prompt 설정입니다. static_sentence: anyOf: - type: string - type: 'null' default: null title: Static Sentence required: - api_configuration title: ApiFlowNodeData type: object description: >- public `flow` graph에서 node type `api`의 타입별 `data` payload입니다. `transitions`, `logical_transitions`, `global_node_settings`는 `flow.edges`와 `data.global_node_setting`으로 표현되므로, 해당 builder routing key를 여기로 보내지 마세요. v2 surface는 strict합니다. write에서는 문서화된 node별 field와 `global_node_setting`만 허용하며, 다른 top-level key는 `FLOW_V2_INVALID`로 거부됩니다. SendSmsFlowNodeData: additionalProperties: false properties: name: anyOf: - type: string - type: 'null' default: null description: >- 사람이 읽을 수 있는 node label입니다. 입력 시 선택 항목이며, 생략하면 서버가 node id에서 안정적인 label을 채워 저장하므로 저장된 그래프에는 항상 존재합니다. title: Name response_mode: default: wait enum: - wait - fire_and_forget title: Response Mode type: string prompt_type: anyOf: - enum: - static - dynamic type: string - type: 'null' default: static title: Prompt Type prompt: anyOf: - type: string - type: 'null' default: null title: Prompt description: Agent prompt 설정입니다. static_title: anyOf: - type: string - type: 'null' default: null title: Static Title static_sentence: anyOf: - type: string - type: 'null' default: null title: Static Sentence static_image_file_keys: anyOf: - items: type: string type: array maxItems: 3 - type: 'null' default: null description: >- Static MMS 이미지 첨부 file key 목록입니다. 값은 file upload endpoint가 반환하는 opaque file_key 문자열입니다. title: Static Image File Keys sms_from_number: anyOf: - type: string - type: 'null' default: null title: Sms From Number global_node_setting: $ref: '#/components/schemas/GlobalNodeSetting' description: >- node-level global marker입니다. 이 값이 있으면 해당 node는 global node로 처리됩니다. 일반 node에서는 생략하세요. 이 key를 사용해야 하며, legacy camelCase `globalNodeSettings`는 write 시 거부됩니다. title: SendSmsFlowNodeData type: object description: >- public `flow` graph에서 node type `sendSms`의 타입별 `data` payload입니다. `transitions`, `logical_transitions`, `global_node_settings`는 `flow.edges`와 `data.global_node_setting`으로 표현되므로, 해당 builder routing key를 여기로 보내지 마세요. v2 surface는 strict합니다. write에서는 문서화된 node별 field와 `global_node_setting`만 허용하며, 다른 top-level key는 `FLOW_V2_INVALID`로 거부됩니다. TransferCallFlowNodeData: additionalProperties: false properties: name: anyOf: - type: string - type: 'null' default: null description: >- 사람이 읽을 수 있는 node label입니다. 입력 시 선택 항목이며, 생략하면 서버가 node id에서 안정적인 label을 채워 저장하므로 저장된 그래프에는 항상 존재합니다. title: Name transfer_configuration: $ref: '#/components/schemas/TransferConfiguration' transfer_type: anyOf: - enum: - cold - warm type: string - type: 'null' default: cold title: Transfer Type description: 이 flow node에서 사용할 transfer mode입니다. transfer_message_type: anyOf: - enum: - static - dynamic type: string - type: 'null' default: static title: Transfer Message Type warm_transfer_prompt: anyOf: - type: string - type: 'null' default: null title: Warm Transfer Prompt description: warm transfer 메시지를 생성할 때 쓰는 prompt입니다. warm_transfer_static_sentence: anyOf: - type: string - type: 'null' default: null title: Warm Transfer Static Sentence description: 정적 warm transfer 메시지입니다. displayed_caller_id: anyOf: - enum: - agent - user type: string - type: 'null' default: agent title: Displayed Caller Id description: call transfer 중 표시할 caller ID source입니다. sip_headers: anyOf: - items: $ref: '#/components/schemas/SipHeader' type: array - type: 'null' default: null title: Sip Headers description: transfer call에 첨부할 SIP header입니다. prompt_type: anyOf: - enum: - none - static - dynamic type: string - type: 'null' default: null title: Prompt Type prompt: anyOf: - type: string - type: 'null' default: null title: Prompt description: Agent prompt 설정입니다. static_sentence: anyOf: - type: string - type: 'null' default: null title: Static Sentence required: - transfer_configuration title: TransferCallFlowNodeData type: object description: >- public `flow` graph에서 node type `transferCall`의 타입별 `data` payload입니다. `transitions`, `logical_transitions`, `global_node_settings`는 `flow.edges`와 `data.global_node_setting`으로 표현되므로, 해당 builder routing key를 여기로 보내지 마세요. v2 surface는 strict합니다. write에서는 문서화된 node별 field와 `global_node_setting`만 허용하며, 다른 top-level key는 `FLOW_V2_INVALID`로 거부됩니다. TransferAgentFlowNodeData: additionalProperties: false properties: name: anyOf: - type: string - type: 'null' default: null description: >- 사람이 읽을 수 있는 node label입니다. 입력 시 선택 항목이며, 생략하면 서버가 node id에서 안정적인 label을 채워 저장하므로 저장된 그래프에는 항상 존재합니다. title: Name agent: $ref: '#/components/schemas/AgentMapping' description: >- `agent_id`와 `agent_version`을 가진 agent mapping 객체입니다. call, campaign, telephone number 등 cross-resource reference에서 사용합니다. preserve_chat_context: anyOf: - type: boolean - type: 'null' default: null title: Preserve Chat Context description: 대상 agent가 이전 대화 context를 받을지 여부입니다. required: - agent title: TransferAgentFlowNodeData type: object description: >- public `flow` graph에서 node type `transferAgent`의 타입별 `data` payload입니다. `transitions`, `logical_transitions`, `global_node_settings`는 `flow.edges`와 `data.global_node_setting`으로 표현되므로, 해당 builder routing key를 여기로 보내지 마세요. v2 surface는 strict합니다. write에서는 문서화된 node별 field와 `global_node_setting`만 허용하며, 다른 top-level key는 `FLOW_V2_INVALID`로 거부됩니다. EndCallFlowNodeData: additionalProperties: false properties: name: anyOf: - type: string - type: 'null' default: null description: >- 사람이 읽을 수 있는 node label입니다. 입력 시 선택 항목이며, 생략하면 서버가 node id에서 안정적인 label을 채워 저장하므로 저장된 그래프에는 항상 존재합니다. title: Name prompt_type: anyOf: - enum: - none - static - dynamic type: string - type: 'null' default: null title: Prompt Type prompt: anyOf: - type: string - type: 'null' default: null title: Prompt description: Agent prompt 설정입니다. static_sentence: anyOf: - type: string - type: 'null' default: null title: Static Sentence global_node_setting: $ref: '#/components/schemas/GlobalNodeSetting' description: >- node-level global marker입니다. 이 값이 있으면 해당 node는 global node로 처리됩니다. 일반 node에서는 생략하세요. 이 key를 사용해야 하며, legacy camelCase `globalNodeSettings`는 write 시 거부됩니다. title: EndCallFlowNodeData type: object description: >- public `flow` graph에서 node type `endCall`의 타입별 `data` payload입니다. `transitions`, `logical_transitions`, `global_node_settings`는 `flow.edges`와 `data.global_node_setting`으로 표현되므로, 해당 builder routing key를 여기로 보내지 마세요. v2 surface는 strict합니다. write에서는 문서화된 node별 field와 `global_node_setting`만 허용하며, 다른 top-level key는 `FLOW_V2_INVALID`로 거부됩니다. NoteFlowNodeData: additionalProperties: false properties: content: anyOf: - type: string - type: 'null' default: null title: Content description: 이 flow node 또는 message object의 text content입니다. width: anyOf: - type: number - type: 'null' default: null title: Width height: anyOf: - type: number - type: 'null' default: null title: Height title: NoteFlowNodeData type: object description: >- public `flow` graph에서 node type `note`의 타입별 `data` payload입니다. `transitions`, `logical_transitions`, `global_node_settings`는 `flow.edges`와 `data.global_node_setting`으로 표현되므로, 해당 builder routing key를 여기로 보내지 마세요. v2 surface는 strict합니다. write에서는 문서화된 node별 field와 `global_node_setting`만 허용하며, 다른 top-level key는 `FLOW_V2_INVALID`로 거부됩니다. LogicEquation: properties: left: type: string title: Left description: 왼쪽 operand입니다. 보통 추출 변수 이름입니다. operator: type: string enum: - equals - not_equals - contains - does_not_contain - greater_than - greater_than_or_equal - less_than - less_than_or_equal - exists - does_not_exist title: Operator description: >- 비교 operator입니다. builder/runtime snake_case를 사용합니다. 예: `greater_than`, `does_not_exist`. right: anyOf: - {} - type: 'null' title: Right description: >- 오른쪽 operand입니다. string/number/bool이 될 수 있고, `exists` / `does_not_exist`에서는 null일 수 있습니다. additionalProperties: false type: object required: - left - operator title: LogicEquation description: >- `logic` condition 안의 단일 deterministic comparison입니다(Retell과 정렬된 equations 형태). Retell과 맞춘 naming에서 `left`는 추출 변수이고, `right`는 비교 값입니다. `exists` / `does_not_exist`에서는 생략할 수 있습니다. NodeKnowledgeConfig: additionalProperties: true properties: rag_enabled: default: false title: Rag Enabled type: boolean description: 이 에이전트에서 검색 기반 생성을 사용할지 여부입니다. knowledge_ids: anyOf: - items: type: integer type: array - type: 'null' default: null title: Knowledge Ids description: >- 이 에이전트에 연결할 숫자형 public knowledge ID 목록입니다. 값은 `GET /v3/knowledges`에서 확인합니다. title: NodeKnowledgeConfig type: object description: flow 노드에서 사용할 knowledge 설정입니다. GlobalNodeSetting: additionalProperties: false description: >- node-level global marker입니다. 이 객체가 있으면 global node로 처리됩니다. runtime은 진입 edge를 eligible node로 자동 확장하므로, public v2 graph는 global node의 entry edge를 담지 않습니다. 이 marker와 진입 `condition`만 담습니다. 진입 condition은 `ai` variant만 지원합니다. builder는 global node 진입 조건을 `transition_condition: str`로만 저장하므로, `logic` / `fallback` 진입 condition은 builder 표현이 없고 v2 write validator가 `global_node_condition_unsupported`로 거부합니다. OpenAPI는 runtime이 실제로 받는 형태만 노출하도록 `AiCondition`으로 좁혀져 있습니다. properties: condition: $ref: '#/components/schemas/AiCondition' description: >- runtime이 이 global node로 점프할 수 있는 조건입니다. `ai` variant만 지원합니다(builder는 entry를 `transition_condition` 문자열로 저장합니다). required: - condition title: GlobalNodeSetting type: object ExtractionConfiguration: additionalProperties: true properties: extraction_prompt: default: '' title: Extraction Prompt type: string description: 추출 작업에 사용할 지시문입니다. variables: items: $ref: '#/components/schemas/VariableDefinition' title: Variables type: array description: 이 추출 설정이 생성하는 변수 목록입니다. title: ExtractionConfiguration type: object description: 추출 노드가 사용할 structured extraction 설정입니다. ApiConfiguration: additionalProperties: true properties: method: default: GET enum: - GET - POST - PUT - DELETE title: Method type: string description: API 노드에서 사용할 HTTP method입니다. url: title: Url type: string description: 외부 API endpoint URL입니다. authorization_enabled: default: false title: Authorization Enabled type: boolean description: 외부 API 호출에 인증을 사용할지 여부입니다. auth_type: default: None enum: - None - Basic - Bearer title: Auth Type type: string description: 외부 API 호출 인증 방식입니다. auth_credentials: anyOf: - type: string - type: 'null' default: null title: Auth Credentials description: 외부 API 호출 인증 자격증명입니다. auth_encode_required: default: false title: Auth Encode Required type: boolean description: 인증 자격증명을 인코딩해야 하는지 여부입니다. headers_enabled: default: false title: Headers Enabled type: boolean description: 추가 HTTP header를 전송할지 여부입니다. headers: additionalProperties: type: string title: Headers type: object description: API 노드에서 보낼 custom HTTP header입니다. body_enabled: default: false title: Body Enabled type: boolean description: 요청 body를 전송할지 여부입니다. body: anyOf: - type: string - type: 'null' default: null title: Body description: API 노드에서 보낼 요청 body 또는 template입니다. timeout_seconds: default: 10 exclusiveMinimum: 0 title: Timeout Seconds type: integer description: 외부 API 호출 타임아웃입니다. 단위는 초입니다. required: - url title: ApiConfiguration type: object description: API flow 노드에서 호출할 외부 HTTP 요청 설정입니다. ApiResponseVariable: additionalProperties: true properties: variable_name: title: Variable Name type: string description: API 응답 값을 저장할 변수 이름입니다. json_path: title: Json Path type: string description: API 응답에서 값을 추출할 JSONPath입니다. required: - variable_name - json_path title: ApiResponseVariable type: object description: API 응답에서 변수로 저장할 값의 추출 규칙입니다. TransferConfiguration: additionalProperties: true properties: transfer_to: title: Transfer To type: string description: 전환 대상 전화번호 또는 SIP 주소입니다. transfer_type: default: phone enum: - phone - sip title: Transfer Type type: string description: 전환 대상 유형입니다. transfer_condition: anyOf: - type: string - type: 'null' default: null title: Transfer Condition description: 이 전환 설정을 선택할 조건입니다. required: - transfer_to title: TransferConfiguration type: object description: 통화 전환 대상과 조건 설정입니다. SipHeader: additionalProperties: true properties: name: type: string title: Name description: 사람이 읽을 수 있는 리소스 이름입니다. value: title: Value type: string description: 이 조건에서 비교할 값입니다. required: - name - value title: SipHeader type: object description: SIP transfer에 함께 보낼 header 항목입니다. AgentMapping: additionalProperties: false description: >- `agent_id`와 `agent_version` 매핑입니다. 요청·응답 모두에서 에이전트 매핑이 필요한 경우 이 타입을 사용합니다. version 지정이 필요 없는 엔드포인트는 flat `agent_id: UUID`를 직접 받고 `AgentMapping`을 사용하지 않습니다. properties: agent_id: description: 에이전트 UUID입니다. format: uuid title: Agent Id type: string agent_version: default: current description: >- 에이전트 버전입니다. 허용값은 "current", "production", "v{n}"(n≥1)입니다. 보내지 않으면 "current"로 처리합니다. null 전송은 거부합니다. title: Agent Version type: string pattern: ^(current|production|v[1-9][0-9]*)$ examples: - current - production - v1 required: - agent_id title: AgentMapping type: object VariableDefinition: additionalProperties: true properties: variable_name: pattern: ^[a-zA-Z][a-zA-Z0-9_]{0,39}$ title: Variable Name type: string description: 추출 결과를 저장할 변수 이름입니다. variable_type: default: string enum: - string - number - boolean title: Variable Type type: string description: 추출 변수의 값 타입입니다. variable_description: default: '' title: Variable Description type: string description: 추출 변수의 의미와 작성 기준입니다. required: - variable_name title: VariableDefinition type: object description: 추출 결과로 생성할 변수 정의입니다. securitySchemes: BearerAuth: type: http scheme: bearer bearerFormat: Organization API key description: '조직 API 키를 `Authorization: Bearer ` 형식으로 보냅니다.' ````