멤버

워크스페이스에 속한 멤버(상담원·관리자) 정보를 읽는 조회 API입니다. id는 membership UUID입니다. 삭제되지 않은 멤버십과 계정만 노출하며, 온라인 상태(status)와는 무관하므로 휴가·근무 외 멤버도 포함됩니다.

email과 last_login_at은 의도적으로 포함합니다. is_super_admin, 로케일, 서명 같은 내부 필드는 노출하지 않습니다.

목록 조회

GET /members — 멤버 목록을 cursor pagination으로 조회합니다.

Scope: members:read
쿼리: limit(기본 50, 1~100), cursor(이전 응답의 meta.next_cursor 값)
created_at 내림차순으로 정렬됩니다.

범위를 벗어난 limit은 자동 보정 없이 400 INVALID_QUERY로 거부합니다. 발급 후 24시간이 지난 cursor도 같은 오류를 반환합니다. 자세한 규칙은 페이지네이션을 참고하세요.

아래 요청은 멤버 50명을 조회합니다.

curl "https://api.talk.zeroworks.ai/api/public/v1/members?limit=50" \
  -H "Authorization: Bearer ztpat_..."

응답

{
  "success": true,
  "data": [
    {
      "id": "9b1c2d3e-...",
      "email": "agent@example.com",
      "name": "김상담",
      "role": "agent",
      "status": "active",
      "last_login_at": "2026-05-01T09:30:00Z",
      "created_at": "2026-01-01T00:00:00Z",
      "updated_at": "2026-05-01T09:30:00Z"
    }
  ],
  "meta": { "has_more": true, "next_cursor": "eyJ..." }
}

필드

필드	타입	설명
`id`	string	membership UUID
`email`	string	계정 이메일
`name`	string	계정 이름
`avatar_url`	string	프로필 이미지 URL. 값이 없으면 키가 생략됩니다
`role`	string	멤버십 권한 (아래 값 집합 참조)
`status`	string	멤버의 온라인 접속 상태 (아래 값 집합 참조)
`last_login_at`	string	해당 계정의 인증 수단 중 가장 최근 로그인 시각. 값이 없으면 키가 생략됩니다
`created_at`·`updated_at`	string	RFC 3339 시각

avatar_url·last_login_at은 값이 없으면 null이 아니라 키가 생략됩니다 ("key" in obj로 판별).

값 집합

필드	값 집합
`role`	`owner` · `admin` · `agent` · `viewer` (`bot`은 멤버십 행이 아니므로 이 엔드포인트에서 반환되지 않습니다)
`status`	`active`(접속) · `away`(자리 비움) · `vacation`(휴가) · `off_duty`(근무 외). 멤버십의 활성 여부가 아니라 접속 상태입니다

단건 조회

GET /members/{id} — 단일 멤버를 조회합니다. {id}는 membership UUID입니다.

Scope: members:read

아래 요청은 멤버 한 명을 조회합니다.

curl "https://api.talk.zeroworks.ai/api/public/v1/members/9b1c2d3e-..." \
  -H "Authorization: Bearer ztpat_..."

응답 — 목록의 항목 하나와 같은 형태입니다.

{
  "success": true,
  "data": {
    "id": "9b1c2d3e-...",
    "email": "agent@example.com",
    "name": "김상담",
    "role": "agent",
    "status": "active",
    "last_login_at": "2026-05-01T09:30:00Z",
    "created_at": "2026-01-01T00:00:00Z",
    "updated_at": "2026-05-01T09:30:00Z"
  }
}

ID 형식이 올바르지 않으면 400 INVALID_INPUT, 워크스페이스에 해당 멤버가 없으면 404 NOT_FOUND를 반환합니다.

목록 조회​

필드​

값 집합​

단건 조회​

목록 조회

필드

값 집합

단건 조회