Skip to main content
vox.ai v3 API는 음성 AI 에이전트의 전체 라이프사이클을 코드로 제어할 수 있는 REST API입니다. v2 대비 일관된 컨벤션, 명시적인 에러 모델, 그리고 스키마 레지스트리와 OpenAPI를 통한 자기 기술적인 계약을 제공합니다.

​
Base URL

​
인증

모든 요청에는 Authorization: Bearer <token> 헤더가 필요합니다. 토큰은 대시보드 설정에서 발급한 조직 API 키를 사용합니다.

​
컨벤션

  • 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

단건 통화, 대량 캠페인과 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 설정은 기존 도구 객체에서 유지해야 합니다. 프롬프트만 바꿀 때는 builtInTools를 보내지 않거나, GET /agents/{agent_id}에서 받은 도구 객체를 그대로 유지한 뒤 필요한 필드만 바꾸세요. 정확한 필드 구조는 GET /schemas/tool-schema/{schema_type}로 확인하세요.
플로우 에이전트의 새 작성 계약은 flow 필드입니다. 저장 전 검증은 POST /agents/validate-flow를 사용합니다. 자세한 내용은 API로 플로우 작성 및 검증을 참고하세요.

​
관련 문서

  • 단건 발신 — API로 단건 아웃바운드 통화를 실행하는 방법을 설명합니다.
  • 대량 발신 — CSV/Excel로 대량 아웃바운드 캠페인을 실행하는 방법을 설명합니다.
v3 API, REST API, API 레퍼런스, API reference, 인증, authentication, API Key, endpoint, 스키마 레지스트리, schema registry, OpenAPI, flow API, validate-flow, flow_data deprecated, builtInTools, 기본 도구