API 개요

ZeroTalk Public API는 메시지·연락처·채널 등 워크스페이스 데이터를 서버에서 직접 다루는 HTTP API입니다. 데이터 조회(읽기)와 답장 전송·채널 조작·outbound-webhook 관리(쓰기) 엔드포인트를 제공합니다(범위 참고). 모든 요청은 Personal Access Token(PAT)으로 인증합니다.

토큰은 대시보드에서 직접 발급합니다

워크스페이스 Owner·Admin은 대시보드의 설정 → 개발자에서 PAT를 직접 발급·회전·폐기할 수 있습니다. 자세한 절차는 인증 문서를 참고하세요.

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는 forward-only입니다 — next_cursor만 제공하며 이전 페이지로 돌아가는 cursor는 없습니다. has_more가 false이면 마지막 페이지입니다.

실패

{
  "success": false,
  "error": { "code": "INVALID_TOKEN", "message": "...", "details": {} }
}

요청 ID

모든 응답에 X-Request-ID 헤더가 echo됩니다. 요청 시 직접 보낸 값이 64자 이하이고 영숫자·하이픈(-)·언더스코어(_)로만 구성되면 그대로 반환되고, 그 외(너무 길거나 특수문자 포함)에는 서버가 새 UUID로 대체합니다. 헤더를 보내지 않아도 서버가 UUID를 생성합니다. UUID는 이 조건을 만족하므로 일반적인 경우에는 영향이 없습니다. 문제를 보고할 때 이 값을 함께 전달하면 추적이 빠릅니다.

CORS

Public API는 CORS를 허용하지 않습니다. 브라우저에서 직접 호출할 수 없으며, 토큰 노출을 막기 위해 서버 사이드에서만 사용하세요.

범위

읽기는 메시지·연락처·채널 등 워크스페이스 데이터를 조회합니다.

쓰기는 답장 전송·읽음/종료/재오픈/배정 등 채널 조작과 outbound-webhook 관리를 수행합니다. 전체 엔드포인트 목록은 엔드포인트 카탈로그를 참고하세요.