본문으로 건너뛰기

팀

워크스페이스의 팀과 팀에 속한 멤버를 읽는 조회 API입니다.

목록 조회​

GET /teams — 워크스페이스의 활성 팀 목록을 cursor pagination으로 조회합니다.

  • Scope: teams: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/teams?limit=50" \
  -H "Authorization: Bearer ztpat_..."

응답

{
  "success": true,
  "data": [
    {
      "id": "7a1b2c3d-...",
      "name": "고객지원팀",
      "description": "1차 인바운드 응대",
      "created_at": "2026-01-01T00:00:00Z",
      "updated_at": "2026-05-01T10:00:00Z"
    }
  ],
  "meta": { "has_more": true, "next_cursor": "eyJ..." }
}

필드​

필드타입설명
idstring팀 UUID
namestring팀 이름
descriptionstring팀 설명. 값이 없으면 null이 아니라 키가 생략됩니다
created_at·updated_atstringRFC 3339 시각

팀 멤버 목록​

GET /teams/{id}/members — 팀에 속한 멤버 목록을 cursor pagination으로 조회합니다. {id}는 팀 UUID입니다.

  • Scope: teams:read
  • 쿼리: limit(기본 50, 1~100), cursor(이전 응답의 meta.next_cursor 값)
  • 멤버의 created_at 내림차순으로 정렬됩니다.
  • 워크스페이스에 해당 팀이 없으면 404 NOT_FOUND입니다. 팀에 멤버가 없는 경우(빈 목록)와 구분됩니다.

limit과 cursor 규칙은 팀 목록과 같습니다.

아래 요청은 팀 7a1b2c3d-...의 멤버 50명을 조회합니다.

curl "https://api.talk.zeroworks.ai/api/public/v1/teams/7a1b2c3d-.../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:00:00Z",
      "created_at": "2026-01-01T00:00:00Z",
      "updated_at": "2026-05-01T10:00:00Z"
    }
  ],
  "meta": { "has_more": false }
}

멤버 항목은 GET /members와 같은 형태입니다. avatar_url·last_login_at은 값이 없으면 null이 아니라 키가 생략됩니다.