API 개요
제로톡 Public API는 서버에서 메시지·연락처·채널 같은 워크스페이스 데이터를 읽고 쓰는 HTTP API입니다. 읽기(GET) 엔드포인트로 데이터를 조회하고, 쓰기(POST·PATCH·PUT·DELETE) 엔드포인트로 답장 전송, 채널 조작, 연락처 관리, outbound 웹훅 관리를 할 수 있습니다. 전체 목록은 엔드포인트 카탈로그에 있습니다. 모든 요청은 Personal Access Token(PAT)으로 인증합니다.
Base URL
엔드포인트 문서의 경로(예: /contacts)는 아래 Base URL 뒤에 붙여서 호출합니다.
https://api.talk.zeroworks.ai/api/public/v1
인증
모든 요청의 Authorization 헤더에 PAT를 Bearer 토큰으로 전달합니다. 자세한 내용은 인증 문서를 참고하세요. 아래 명령은 워크스페이스 정보를 조회합니다.
curl https://api.talk.zeroworks.ai/api/public/v1/workspace \
-H "Authorization: Bearer ztpat_..."
응답 형식
모든 응답은 JSON이며, success 필드로 성공과 실패를 구분합니다.
성공 (단건)
{ "success": true, "data": {} }
성공 (리스트) — cursor 기반 pagination
{
"success": true,
"data": [],
"meta": { "has_more": true, "next_cursor": "eyJ..." }
}
meta는 한 방향으로만 넘어갑니다. 다음 페이지로 가는 next_cursor만 제공하고, 이전 페이지로 돌아가는 cursor는 없습니다. has_more가 false이면 마지막 페이지입니다. 자세한 규칙은 페이지네이션 문서를 참고하세요.
실패
{
"success": false,
"error": { "code": "INVALID_TOKEN", "message": "...", "details": {} }
}
error.code별 원인과 대응은 에러 문서에 있습니다.
요청 ID
모든 응답에는 X-Request-ID 헤더가 들어 있습니다. 요청에 X-Request-ID 헤더를 직접 보내면 서버가 같은 값을 돌려줍니다. 다만 값이 64자 이하이고 영숫자·하이픈(-)·밑줄(_)로만 이루어진 경우에 한합니다. 이 조건을 벗어나거나 헤더를 보내지 않으면 서버가 새 UUID를 만들어 응답에 넣습니다. UUID는 이 조건을 만족하므로, UUID를 보내는 일반적인 경우에는 값이 바뀌지 않습니다. 문제를 문의할 때 이 값을 함께 전달하면 요청을 추적하기 쉽습니다.
CORS
Public API는 CORS를 허용하지 않습니다. 브라우저에서 직접 호출할 수 없고, 토큰 노출을 막기 위해 서버 사이드에서만 호출해야 합니다.
범위
읽기는 메시지·연락처·채널 등 워크스페이스 데이터를 조회합니다.
쓰기는 답장 전송, 읽음·종료·재오픈·배정 같은 채널 조작, 연락처 생성·수정, outbound 웹훅 관리를 수행합니다.
토큰마다 호출할 수 있는 엔드포인트는 부여한 권한(scope)으로 정해집니다. 엔드포인트별로 필요한 scope는 스코프 문서에서 확인하세요. 호출 횟수에는 요청 한도가 적용됩니다.