워크스페이스 그룹 목록 조회

플랜: Business 이상

스코프: workspaces:read

워크스페이스의 그룹을 이름순으로 반환합니다. 프로젝트를 custom audience로 게시할 때 POST 또는 PATCH /v1/projects/{project_id}/publish의 audience_targets 항목에서 type: "group"의 id로 그룹 ID를 사용합니다.

OpenAPI

항목	값
Method	`GET`
Path	`/v1/workspaces/{workspace_id}/groups`
Operation ID	`listWorkspaceGroups`
Source spec	`https://api.lovable.dev/v1/openapi.yaml`
Local snapshot	YAML 스냅샷 (SHA-256: `0087e31932ee5bbe50b225ede3b219b49e5a0a9db01205c120d4755011e98daf`)

GET /v1/workspaces/{workspace_id}/groups

인증

Lovable-API-Key: lov_your-api-key 또는 Authorization: Bearer <key>를 보냅니다. 이 엔드포인트는 workspaces:read 스코프가 필요합니다.

매개변수

이름	위치	필수	타입	설명
`workspace_id`	path	예	`string`	워크스페이스 ID입니다.
`limit`	query	아니요	`integer`, `int64`	페이지당 반환할 최대 항목 수입니다. 기본값은 `50`, 최솟값은 `1`, 최댓값은 `100`입니다.
`cursor`	query	아니요	`string`	이전 응답의 `pagination.next_cursor`를 전달해 다음 페이지를 가져옵니다. 첫 페이지에서는 생략합니다. 페이지를 따라갈 때 같은 필터와 정렬 순서를 유지하세요.
`Lovable-Version`	header	아니요	`string`	제공받을 안정 API 버전입니다. `YYYY-MM-DD` 날짜 형식으로 보냅니다. 생략하면 현재 가장 오래된 지원 안정 버전인 `2026-09-11`이 사용됩니다.
`Lovable-Beta`	header	아니요	`string`	안정 버전 위에 활성화할 베타 리비전 문자열입니다. 여러 개는 쉼표로 구분합니다.

예시

curl --request GET \
  --url 'https://api.lovable.dev/v1/workspaces/workspace-id/groups' \
  --header 'Lovable-API-Key: lov_your-api-key' \
  --header 'Lovable-Version: 2026-09-11'

const response = await fetch("https://api.lovable.dev/v1/workspaces/workspace-id/groups", {
  method: "GET",
  headers: {
    "Lovable-API-Key": process.env.LOVABLE_API_KEY ?? "lov_your-api-key",
    "Lovable-Version": "2026-09-11",
  },
});
if (!response.ok) {
  throw new Error(`Lovable API ${response.status}: ${await response.text()}`);
}
console.log(await response.json());

응답

상태	본문	설명
`200`	`WorkspaceGroupPage`	이름순으로 정렬된 페이지네이션된 워크스페이스 그룹입니다.
`400`	`ErrorResponse`	요청 본문 또는 매개변수 형식이 잘못되었거나 검증에 실패했습니다.
`401`	`ErrorResponse`	API 키, 세션 토큰 또는 OAuth access token이 없거나 유효하지 않습니다.
`402`	`ErrorResponse`	Public API 접근에는 Business 이상 플랜이 필요합니다.
`403`	`ErrorResponse`	키 또는 호출자에게 필요한 스코프나 권한이 없습니다.
`404`	`ErrorResponse`	워크스페이스가 존재하지 않거나 삭제되었거나 자격 증명의 워크스페이스 스코프 밖에 있습니다.
`406`	`ErrorResponse`	`Accept` 헤더가 이 엔드포인트가 생성하는 모든 미디어 타입을 제외합니다.
`429`	`ErrorResponse`	요청이 너무 많습니다. `Retry-After`가 있으면 해당 간격 뒤에 재시도합니다.
`503`	`ErrorResponse`	서비스를 일시적으로 사용할 수 없거나 처리 기한이 만료되었습니다.
`default`	`ErrorResponse`	오류입니다. 응답 본문은 표준 오류 envelope을 사용하며 `status`는 HTTP 상태 코드와 같고 `type`은 machine-readable 오류 코드입니다.

모든 응답에는 상황에 따라 다음 공통 헤더가 포함될 수 있습니다: Lovable-Version, Lovable-Beta, X-Request-Id, X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset, X-Lovable-Unknown-Query-Params, X-Lovable-Unknown-Query-Params-Omitted. X-Lovable-Unknown-Query-Params는 이 작업이 선언하지 않은 query parameter가 있을 때 URL escape된 이름을 최대 20개까지 쉼표로 제공하며, 20개를 넘으면 X-Lovable-Unknown-Query-Params-Omitted가 누락된 개수(minimum: 1)를 제공합니다. 401 응답은 string인 WWW-Authenticate를, 429 응답은 integer인 Retry-After를 포함합니다. Retry-After는 minimum: 1입니다. X-RateLimit-Reset은 지연 시간이 아니라 Unix timestamp 초 단위입니다.

스키마

`WorkspaceGroupPage`

필드	타입	필수	설명
`data`	`WorkspaceGroup[]`	예	이 페이지의 항목입니다. 항목이 없으면 빈 배열입니다.
`pagination`	`Pagination`	예	결과가 더 있는지와 다음 페이지를 가져올 커서를 나타냅니다.

`WorkspaceGroup`

필드	타입	필수	설명
`id`	`string`	예	그룹 ID입니다. `audience: "custom"`으로 게시할 때 `type: "group"` audience target의 `id`로 사용합니다.
`workspace_id`	`string`	예	그룹이 속한 워크스페이스입니다.
`name`	`string`	예	그룹 표시 이름입니다. 워크스페이스 안에서 고유합니다.
`description`	`string` 또는 `null`	예	그룹 설명입니다. 설정되지 않았으면 `null`입니다.
`scim_external_id`	`string` 또는 `null`	예	SCIM identity provider가 부여한 외부 ID입니다. SCIM으로 프로비저닝되지 않은 그룹에서는 `null`입니다.
`member_count`	`integer`, `int64`	예	그룹 멤버 수입니다. 활성 멤버, 대기 중인 멤버, 아직 가입하지 않은 초대 사용자를 포함합니다.
`created_at`	`string`, `date-time`	예	그룹이 생성된 시각입니다.
`updated_at`	`string`, `date-time`	예	그룹이 마지막으로 업데이트된 시각입니다.

`Pagination`

필드	타입	필수	설명
`has_more`	`boolean`	예	이 페이지 뒤에 결과가 더 있으면 `true`입니다.
`next_cursor`	`string` 또는 `null`	예	다음 페이지를 가져올 때 `cursor` 쿼리 매개변수로 전달할 값입니다. 불투명 문자열로 취급하세요. 결과가 더 없으면 `null`입니다.

`ErrorResponse`

공통 오류 응답입니다.

필드	타입	필수	설명
`detail`	`string \	null`	예
`errors`	`array \	null`	예
`props`	`object \	null`	예
`request_id`	`string`	예	`X-Request-Id` 응답 헤더에서 반복되는 이 요청의 식별자입니다.
`status`	`integer`	예	본문에 반복되는 HTTP 상태 코드입니다.
`title`	`string`	예	사람이 읽을 수 있는 오류 요약입니다.
`type`	`string`	예	안정적인 machine-readable 오류 유형입니다.

원본에 포함된 이 작업의 OpenAPI 스냅샷은 YAML 스냅샷 (SHA-256: 0087e31932ee5bbe50b225ede3b219b49e5a0a9db01205c120d4755011e98daf)로 보존했습니다. 최신 전체 OpenAPI 계약은 https://api.lovable.dev/v1/openapi.yaml에서 확인할 수 있습니다.

On this page