API 레퍼런스 (OpenAPI 3.1)

AskAIs Customer Service 는 모든 공개 엔드포인트를 설명하는 완전한 OpenAPI 3.1 명세를 제공합니다. 자동 생성되는 SDK 의 기반이 되며, OpenAPI 생태계의 모든 도구 （Insomnia, Postman, Swagger UI, Hoppscotch 등）와 함께 사용할 수 있습니다.

명세 가져오기

# Live (cached 5 min, CORS open)
curl https://cs.askais.com/api/v1/openapi.json

# Save to disk
curl https://cs.askais.com/api/v1/openapi.json -o singlink-openapi.json

기본 URL

• 클라우드: https://cs.askais.com/api/v1
• 자체 호스팅: APP_URL 이 가리키는 주소에 /api/v1 을 붙인 것

인증

두 가지 방식이 있으며, 모두 Authorization: Bearer <value> 를 통합니다:

• 연락처 JWT — POST /auth/identify 로 발급됩니다. 단일 연락처로 범위가 제한됩니다. web / 모바일 SDK 에서 사용합니다.
• 워크스페이스 API key — sk_live_..., 설정 → API Keys 에서 생성합니다. 전체 워크스페이스를 대상으로 합니다. 서버 간 통신용입니다.

엔드포인트 한눈에 보기

• POST /auth/identify — 연락처 JWT 발급
• POST /conversations — 새 채팅 시작
• GET /conversations — 내 대화 목록
• GET /conversations/{id}
• GET /conversations/{id}/messages?before=&limit=
• POST /conversations/{id}/messages
• POST /upload — 사전 서명된 S3 POST URL 가져오기
• POST /upload/{id}/confirm

오류

2xx 가 아닌 모든 응답은 안정적인 공통 구조를 사용합니다:

{
  "error": {
    "code": "validation_error",
    "message": "content or attachments required",
    "field": "content"
  }
}

코드: validation_error, unauthorized, forbidden, not_found, conflict, unprocessable, rate_limit_exceeded, internal_error.

실시간 동반자

REST 는 일회성 호출에 적합합니다. 실시간 메시지의 경우 wss://<wsUrl>/v1/ws?token=<jwt> 에 연결하여 message:new, ai:stream:delta, ai:stream:end, typing, presence 이벤트를 수신합니다. 전체 이벤트 구조는 웹 위젯 을 참조하세요.