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

# API 노드

> API 노드를 추가하고 설정하는 방법을 안내합니다.

API 노드는 외부 API를 호출하여 데이터를 가져오거나 전송합니다. 이 노드를 통해 에이전트는 외부 시스템과 통신할 수 있습니다.

## 언제 사용하나요

* 대화 중 **외부 서버에 데이터를 전송**해야 할 때 (예: SMS 발송, 주문 접수)
* 외부 시스템에서 **데이터를 조회**해야 할 때 (예: 주문 상태, 재고 확인)
* API 응답 결과에 따라 **대화 흐름을 분기**해야 할 때
* 대화에서 수집한 변수를 **외부 시스템에 동기화**해야 할 때

## API 구성

### HTTP 메서드

API 요청에 사용할 HTTP 메서드를 선택합니다:

* **GET** - 데이터 조회
* **POST** - 데이터 생성
* **PUT** - 데이터 수정
* **DELETE** - 데이터 삭제

### URL

API 엔드포인트 URL을 입력합니다. `{{variableName}}` 형식으로 동적 변수를 URL에 포함할 수 있습니다.

```
https://api.example.com/users/{{user_id}}/orders
```

### 요청 본문

GET이 아닌 메서드에서 요청 본문을 JSON 형식으로 작성합니다. 동적 변수를 사용하여 대화에서 수집한 데이터를 전달할 수 있습니다.

```json theme={null}
{
  "name": "{{customer_name}}",
  "phone": "{{phone_number}}"
}
```

### 응답 타임아웃

API 응답 대기 시간을 초 단위로 설정합니다. 설정한 시간 내에 응답이 없으면 요청이 실패로 처리됩니다.

### 응답 대기 방식

API 응답을 기다릴지 선택합니다 (노드 데이터 필드: `responseMode`). `요청만 보내고 계속 진행(fire_and_forget)`을 선택하면 응답을 기다리지 않고 성공 경로로 진행하며, **응답 변수·결과 기반 전환 조건과 함께 쓸 수 없습니다**. 자세한 동작은 [API 도구의 응답 대기 방식](/docs/build/tools/api#응답-대기-방식)을 참고하세요.

### 인증

API 호출에 필요한 인증 방식을 선택합니다:

| 방식         | 설명                                          |
| ---------- | ------------------------------------------- |
| **없음**     | 인증 없이 요청을 보냅니다.                             |
| **Basic**  | ID와 비밀번호로 인증합니다. Base64 인코딩 옵션을 선택할 수 있습니다. |
| **Bearer** | Bearer 토큰을 사용하여 인증합니다.                      |

### 헤더

헤더 섹션을 켜면 요청에 포함할 헤더를 key-value 쌍으로 추가할 수 있습니다. 헤더를 사용하지 않을 때는 헤더 섹션을 끄세요.

### 응답 변수 추출

API 응답에서 특정 값을 추출하여 변수로 저장합니다. 변수명과 JSONPath를 지정하여 응답 데이터에서 필요한 값을 가져올 수 있습니다.

| 설정           | 설명                                            |
| ------------ | --------------------------------------------- |
| **변수명**      | 추출한 값을 저장할 변수 이름                              |
| **JSONPath** | 응답 JSON에서 값을 추출하기 위한 경로 (예: `$.data.orderId`) |

## 전환 조건

API 노드는 다음과 같은 상황에서 전환이 발생할 수 있습니다:

* **성공적인 API 호출 이후**: 사용자가 정의한 조건에 따라 다음 노드로 전환합니다.

  * 예: `status == 200 그리고 product_type == 티셔츠 인 경우`
  * 예: `status == 200 그리고 product_type == 반바지 인 경우`

* **요청 실패 시**: API 호출중 오류가 발생한 경우 자동으로 "요청 실패 시" 전환 조건을 통해 지정된 노드로 이동합니다.

## 프롬프트 타입

API 호출을 진행하는 동안 에이전트가 어떤 말을 할 것인지 설정할 수 있습니다:

<CardGroup cols={3}>
  <Card title="동적 프롬프트" icon="pen">
    에이전트가 동적으로 대화 내용을 생성할 수 있도록 프롬프트를 작성합니다.
  </Card>

  <Card title="고정 발화" icon="comment">
    에이전트가 말할 고정된 문장을 설정합니다.
  </Card>

  <Card title="없음" icon="ban">
    API 호출 중에 에이전트가 아무 말도 하지 않습니다.
  </Card>
</CardGroup>

## 실제 사용 예시

### SMS 전송

대화에서 수집한 정보를 바탕으로 고객에게 SMS를 발송하는 패턴입니다.

**API 설정:**

| 항목           | 값                                  |
| ------------ | ---------------------------------- |
| **HTTP 메서드** | POST                               |
| **URL**      | `https://api.example.com/sms/send` |
| **인증**       | Bearer                             |

**요청 본문:**

```json theme={null}
{
  "to": "{{phone_number}}",
  "from": "{{agent_phone}}",
  "message": "{{sms_content}}"
}
```

**전환 조건:**

* **성공 (status == 200)**: "SMS 발송 완료" 안내 노드로 이동
* **요청 실패 시**: "발송 실패" 안내 노드로 이동

<Tip>
  SMS 발송처럼 고객 대기가 필요한 API 호출에서는 프롬프트 타입을 **고정 발화**로 설정하고 "잠시만 기다려 주세요" 같은 안내 문구를 넣으면 자연스럽습니다.
</Tip>

## 관련 문서

<CardGroup cols={3}>
  <Card title="노드 개요" icon="circle-nodes" href="/docs/build/flow/nodes/overview">
    플로우 에이전트의 노드 타입과 추가 방법을 확인하세요.
  </Card>

  <Card title="동적 변수" icon="brackets-curly" href="/docs/build/variables/dynamic-variables">
    API 요청에 활용할 동적 변수의 생성과 사용법을 알아보세요.
  </Card>

  <Card title="전환 조건" icon="arrow-right-arrow-left" href="/docs/build/flow/transitions">
    API 응답에 따른 전환 조건 설정 방법을 확인하세요.
  </Card>
</CardGroup>

***

<Accordion title="연관 검색어">
  API 노드, API node, 외부 API 호출, HTTP 요청, REST API, 응답 변수, JSONPath, API 연동
</Accordion>