Skip to main content
vox.ai v3 API는 음성·채팅 AI 에이전트의 전체 라이프사이클을 코드로 다루는 REST API예요. v2보다 컨벤션이 일관되고 에러 모델이 명시적이며, 스키마 레지스트리와 OpenAPI로 지금 계약을 직접 확인할 수 있어요.

​
Base URL

​
인증

모든 요청에 Authorization: Bearer <token> 헤더가 필요해요. 토큰은 대시보드 설정에서 발급한 워크스페이스(organization_id) API 키를 쓰세요.

​
컨벤션

  • snake_case: 요청·응답 필드는 기본으로 snake_case를 써요. agent.data와 flow.nodes[].data 아래는 에이전트 설정과 노드별 설정을 그대로 담으려고 일부 camelCase를 유지해요.
  • 플로우 작성과 검증: 플로우 에이전트 그래프는 flow 필드로 작성하고, 저장하기 전에 POST /agents/validate-flow로 검증할 수 있어요. flow_data는 기존 빌더 호환용 필드라 새 통합에서는 쓰지 않는 편이 좋아요. 작성법은 API로 플로우 작성 및 검증에 있어요.
  • 밀리초 타임스탬프: _at으로 끝나는 타임스탬프 필드는 unix milliseconds예요.
  • 커서 페이지네이션: list 엔드포인트는 cursor와 limit(1~100)을 써요. 다음 페이지는 응답의 next_cursor를 그대로 다시 넘기세요.
  • 명시적 식별자: 응답 객체 자신의 ID는 id예요. 다른 리소스 참조는 agent_id, call_id처럼 이름을 밝혀 써요.
  • 에러 엔벨로프: 모든 실패 응답은 { "error": { "code", "message", "details" } } 꼴이에요. 제어 흐름은 code로 나누세요.
  • 요청 제한(Rate limit): API 키 요청은 기본적으로 워크스페이스 단위 한도(초당 5회, 분당 120회)를 함께 써요. 일부 엔드포인트는 따로 한도가 있어요. 한도를 넘으면 429와 RATE_LIMIT_EXCEEDED 코드를 돌려줘요. Retry-After 헤더가 있으면 그 시간만큼 기다린 뒤 다시 요청하세요.
  • 대시보드 용어 대응: 대시보드의 대량 발신은 API에서 campaign이고, 대량 문자 발신은 sms_batch예요. 경로·필드·이벤트 이름은 영문 그대로 써요.

​
주요 리소스

  • 에이전트: 음성 에이전트(single prompt, flow)와 버전을 만들고 수정하고 게시해요.
  • 모델: 에이전트에 쓸 수 있는 LLM과 음성 모델을 조회하고 관리해요.
  • 도구: 에이전트가 호출할 API 도구를 만들고 실행 설정을 관리해요.
  • 지식 베이스: 에이전트가 참조할 지식 베이스와 원본 문서를 관리해요.
  • 스키마: agent.data, 플로우와 도구의 공개 JSON Schema를 조회해요.
  • 전화번호: 번호 구매·등록, 에이전트 매핑, SIP 트렁크를 관리해요.
  • 통화·대량 발신·문자: 통화 한 건과 대량 발신(campaign)을 실행하고 조회해요. 문자는 한 건을 보내고, 대량 문자 발신(sms_batch)을 /sms-batches로 만들어 일시정지·재개·취소하며, 발신·수신 목록과 단건 상세를 조회해요.
  • 고객·메모리: 고객 식별자와 고객 속성, 대화에서 추출한 메모리를 관리해요.
  • 알림: 통화 지표를 감시할 알림 규칙과 인시던트를 관리해요.

​
스키마 레지스트리

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}에는 GET /agents/{agent_id}?version=current에서 확인한 head_revision을 expected_head_revision으로 넘기세요. 플로우 그래프를 바꿀 때는 같은 응답의 flow_revision도 expected_flow_revision으로 보내세요. 오래된 revision은 REVISION_CONFLICT로 거부되니, 클라이언트가 최신 상태를 자동으로 다시 읽어 그대로 재시도(blind retry)하지 않게 하세요. data는 부분 수정 payload예요. 생략한 하위 설정은 기존 값을 유지하고, 일반 객체는 한 단계 병합하며 배열은 통째로 바꿔요. data.manuals, data.presetDynamicVariables는 원자적으로 통째로 바꿔요. data.builtInTools를 넣으면 기본 도구 배열도 통째로 바꿔요.
  • builtInTools 생략: 기존 기본 도구 유지
  • builtInTools: []: 기본 도구 전체 제거
  • builtInTools: null: 잘못된 요청
  • manuals 전송: 에이전트 소유 메뉴얼 맵 전체 교체
전역 /manuals API는 없어요. 메뉴얼을 읽거나 고치려면 /agents/{agent_id}/manuals 하위 경로를 쓰세요. 아래처럼 기본값이 아닌 tool-level 설정은 기존 도구 객체에서 유지해야 해요. 프롬프트만 바꿀 때는 builtInTools를 보내지 않거나, GET /agents/{agent_id}에서 받은 도구 객체를 그대로 두고 필요한 필드만 바꾸세요. 정확한 필드 구조는 GET /schemas/tool-schema/{schema_type}로 확인하세요.

​
관련 문서