> ## 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. # 소개 > vox.ai v3 API로 에이전트, 모델, 도구, 통화와 고객 데이터를 관리할 수 있습니다. vox.ai v3 API는 음성 AI 에이전트의 전체 라이프사이클을 코드로 제어할 수 있는 REST API입니다. v2 대비 일관된 컨벤션, 명시적인 에러 모델, 그리고 스키마 레지스트리와 OpenAPI를 통한 자기 기술적인 계약을 제공합니다. ## Base URL ``` https://client-api.tryvox.co/v3 ``` ## 인증 모든 요청에는 `Authorization: Bearer ` 헤더가 필요합니다. 토큰은 [대시보드 설정](https://www.tryvox.co/dashboard/)에서 발급한 조직 API 키를 사용합니다. ```bash theme={null} curl https://client-api.tryvox.co/v3/agents \ -H "Authorization: Bearer $VOX_API_KEY" ``` ## 컨벤션 * **snake\_case** — 요청·응답 필드는 기본적으로 snake\_case를 사용합니다. 예외적으로 `agent.data`와 `flow.nodes[].data` 하위는 에이전트 설정과 노드별 설정을 그대로 담기 위해 일부 camelCase를 유지합니다. * **플로우 작성 및 검증** — 플로우 에이전트 그래프는 `flow` 필드로 작성하고 `POST /agents/validate-flow`로 저장 전 검증할 수 있습니다. `flow_data`는 기존 빌더 호환용 필드이며 새 통합에서는 사용하지 않는 것을 권장합니다. * **밀리초 타임스탬프** — `_at` 으로 끝나는 타임스탬프 필드는 unix milliseconds입니다. * **커서 페이지네이션** — list 엔드포인트는 `cursor` / `limit`(1–100)을 사용합니다. 다음 페이지는 응답의 `next_cursor`를 그대로 다시 전달합니다. * **명시적 식별자** — 응답 객체 자신의 id는 `id`를 사용합니다. 다른 리소스 참조는 `agent_id`, `call_id`처럼 명시적인 이름을 사용합니다. * **에러 엔벨로프** — 모든 실패 응답은 `{ "error": { "code", "message", "details" } }` 형태입니다. 제어 흐름은 `code` 를 기준으로 분기합니다. * **Rate limit** — 모든 v3 엔드포인트는 조직 단위 rate limit(초당 5회, 분당 120회)을 공유합니다. 초과 시 `429`와 `RATE_LIMIT_EXCEEDED` 코드를 반환합니다. ## 주요 리소스 음성 에이전트(single prompt / flow)와 버전을 생성·수정·게시합니다. 에이전트에 사용할 수 있는 LLM과 음성 모델을 조회·관리합니다. 에이전트가 호출할 API 도구를 만들고 실행 설정을 관리합니다. 에이전트가 참조할 지식 베이스와 원본 문서를 관리합니다. `agent.data`, 플로우와 도구의 공개 JSON Schema를 조회합니다. 번호 구매·등록, 에이전트 매핑, SIP 트렁크를 관리합니다. 단건 통화, 대량 캠페인과 SMS 발송을 실행·조회합니다. 고객 식별자와 고객 속성, 대화에서 추출한 메모리를 관리합니다. 통화 지표를 감시할 알림 규칙과 인시던트를 관리합니다. ## 스키마 레지스트리 v3는 에이전트 작성에 필요한 JSON Schema를 API와 OpenAPI로 노출합니다. 클라이언트는 스키마를 하드코딩하지 않고 현재 계약을 확인해 사용할 수 있습니다. * `GET /schemas` — 사용 가능한 스키마 목록을 조회합니다(`agent-schema`, `flow-schema`, `tool-schema` 등). * `GET /schemas/{namespace}/{schema_type}` — 특정 스키마 본문을 조회합니다. * `GET /schemas?category=agent-authoring&include_schema=true` — 에이전트 작성에 필요한 레지스트리 스키마를 함께 조회합니다. ### 에이전트 data 수정 `PATCH /agents/{agent_id}`의 `data`는 에이전트 설정의 부분 수정 payload입니다. 생략한 하위 설정은 기존 값을 유지하고, `data.builtInTools`를 포함하면 기본 도구 배열을 전체 교체합니다. * `builtInTools` 생략 — 기존 기본 도구 유지 * `builtInTools: []` — 기본 도구 전체 제거 * `builtInTools: null` — 잘못된 요청 아래처럼 기본값이 아닌 tool-level 설정은 기존 도구 객체에서 유지해야 합니다. | 도구 | 유지할 대표 필드 | | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | | 공통 | `speakDuringExecution`, `allowInterruptionDuringExecution`, `responseMode` | | `transfer_call` | `transferConfigurations`, `transferType`, `displayedCallerId`, `transferMessageType`, `warmTransferPrompt`, `warmTransferStaticSentence`, `sipHeaders` | | `transfer_agent` | `agent`, `preserveChatContext` | | `send_sms` | `smsMessageType`, `smsMessagePrompt`, `smsMessageStaticSentence`, `smsMessageStaticTitle`, `smsMessageStaticImageFileKeys`, `smsFromNumber` | | `send_dtmf` | `speakDuringExecution`, `allowInterruption` 또는 `allowInterruptionDuringExecution`, `responseMode` | | `skill` | `skill.skills[]`, `skill.initSkillId`, `skill.initSkillName` | 프롬프트만 바꿀 때는 `builtInTools`를 보내지 않거나, `GET /agents/{agent_id}`에서 받은 도구 객체를 그대로 유지한 뒤 필요한 필드만 바꾸세요. 정확한 필드 구조는 `GET /schemas/tool-schema/{schema_type}`로 확인하세요. 플로우 에이전트의 새 작성 계약은 `flow` 필드입니다. 저장 전 검증은 `POST /agents/validate-flow`를 사용합니다. 자세한 내용은 [API로 플로우 작성 및 검증](/docs/build/flow/api-authoring)을 참고하세요. ## 관련 문서 * [단건 발신](/docs/operate/deploy/outbound-single) — API로 단건 아웃바운드 통화를 실행하는 방법을 설명합니다. * [대량 발신](/docs/operate/deploy/outbound-batch) — CSV/Excel로 대량 아웃바운드 캠페인을 실행하는 방법을 설명합니다. *** v3 API, REST API, API 레퍼런스, API reference, 인증, authentication, API Key, endpoint, 스키마 레지스트리, schema registry, OpenAPI, flow API, validate-flow, flow\_data deprecated, builtInTools, 기본 도구