멤버 그룹 관리 API

마인드로직 운영 멤버 그룹을 프로그램적으로 관리하기 위한 어드민 REST API입니다.

기존에는 어드민 웹에서만 가능했던 그룹 생성·수정·삭제, 멤버 배정, 그룹 관리자 지정, 크레딧/모델 권한 설정을 API로 수행할 수 있어, 학사·인사(SIS·HR) 시스템 연동이나 스크립트 대량 처리에 활용할 수 있습니다.

이 API는 모델 추론용 API Gateway와 다른 API입니다.

Base Path: /v1/admin/member-groups
Host: 테넌트 서비스 도메인 (예: https://{subdomain}.factchat.bot) — factchat-cloud.mindlogic.ai가 아닙니다.
인증: API Gateway 키(Authorization: Bearer YOUR_API_KEY)가 아니라 관리자 세션/토큰이 필요합니다. (아래 인증 참고)

인증

관리자 세션 인증이 필요하며, 두 가지 방식을 지원합니다.

sessionId

어드민 로그인 시 발급되는 세션 쿠키. 브라우저/동일 오리진 호출용이며 CSRF(Origin 헤더) 검증이 적용됩니다.

x-access-token

Header

로그인 API로 발급받은 JWT 액세스 토큰. 서버-서버 프로그램 연동 시 이 방식을 권장합니다.

추가 조건:

호출 계정은 활성(active) 상태여야 하며 관리자 권한이 있어야 합니다.
마스터 관리자는 테넌트 내 모든 그룹을, 그룹 관리자는 위임받은 그룹만 관리할 수 있습니다. 하위 트리 포함(include_descendants) 지정은 마스터 관리자만 가능합니다.
모든 작업은 호출자 소속 테넌트로 스코프됩니다.

응답은 공통적으로 { "success": true, "data": { ... } } 형태이며, 반환 데이터가 없는 경우 { "success": true }만 반환됩니다.

엔드포인트 요약

Method	Path	설명
POST	`/v1/admin/member-groups/`	그룹 생성
GET	`/v1/admin/member-groups/{id}/`	그룹 단건 조회
PATCH	`/v1/admin/member-groups/{id}/`	그룹 수정
DELETE	`/v1/admin/member-groups/{id}/`	그룹 삭제
PATCH	`/v1/admin/member-groups/{id}/parent/`	그룹 부모 변경(트리 이동)
POST	`/v1/admin/member-groups/{id}/members/`	멤버 추가
DELETE	`/v1/admin/member-groups/{id}/members/{member_id}/`	멤버 1명 제거
POST	`/v1/admin/member-groups/{id}/members/remove-bulk/`	멤버 대량 제거
POST	`/v1/admin/member-groups/{id}/members/move/`	멤버 이동
GET	`/v1/admin/member-groups/{id}/addable-members/`	추가 가능한 멤버 검색
GET	`/v1/admin/member-groups/{id}/admins/`	그룹 관리자 목록
POST	`/v1/admin/member-groups/{id}/admins/`	그룹 관리자 지정
DELETE	`/v1/admin/member-groups/{id}/admins/{member_id}/`	그룹 관리자 해제
PATCH	`/v1/admin/member-groups/bulk/credit-limit/`	그룹 크레딧 한도 대량 설정
PATCH	`/v1/admin/member-groups/bulk/model-permissions/`	그룹 모델 권한 대량 설정
GET	`/v1/admin/member-groups/usage-overview/`	그룹 사용량 개요
GET \| PATCH	`/v1/admin/member-groups/{id}/agents/`	그룹 에이전트(기능) 설정
GET \| PATCH	`/v1/admin/member-groups/{id}/permission-set/`	그룹 권한 토글 (마스터 전용)

그룹 생성

POST/v1/admin/member-groups/

요청 파라미터

ko_name

string

required

그룹 한글명. 예: "대학물리학 학생".

en_name

string

required

그룹 영문명. 예: "university-physics student".

member_group_type_id

integer | null

그룹 유형 ID.

member_credit_quota

float | null

멤버 1인당 크레딧 한도.

group_credit_quota

float | null

그룹 전체 크레딧 한도.

is_visible_to_admin_only

boolean

일반 사용자에게 숨김 (기본 false).

parent_id

integer | null

상위 그룹 ID (계층형 유형에서 사용).

응답 예시

상태 코드: 200 성공 · 400 트리 제약 위반 · 409 이름 중복 · 401 / 403 인증·권한 실패

그룹 조회

GET/v1/admin/member-groups/{id}/

쿼리 파라미터 member_group_type_id(선택)로 미분류 그룹(id=0) 필터링을 지정할 수 있습니다.

응답 data의 주요 필드:

quota_source

object

group_credit_quota, member_credit_quota 등 크레딧 한도 정보.

group_member_stats

object

최근 30일/당월 크레딧 사용량, 총 멤버 수 등 통계.

그 외 id, ko_name, en_name, name_i18n, is_default, member_count, is_visible_to_admin_only, sso_origin_value, member_group_type_id, parent_id, depth를 포함합니다.

상태 코드: 200 / 401 / 403 / 404

그룹 수정

PATCH/v1/admin/member-groups/{id}/

바디에 포함한 필드만 부분 수정됩니다.

ko_name / en_name

string | null

그룹명.

credit_quota

integer | null

그룹 크레딧 한도. null 전송 시 해제.

member_credit_quota

integer | null

멤버 1인당 크레딧 한도.

member_group_type_id

integer

그룹 유형.

is_visible_to_admin_only

boolean | null

관리자 전용 노출 여부.

응답은 생성과 동일한 형태입니다. 상태 코드: 200 / 400 / 401 / 403 / 404 / 409

그룹 삭제

DELETE/v1/admin/member-groups/{id}/

응답: { "success": true }. 상태 코드: 200 / 400 / 401 / 403 / 404

다음 그룹은 삭제할 수 없습니다(400): SSO 연동 그룹, 필수(required) 유형 그룹, 하위 그룹이 있는 그룹(먼저 하위를 재배치해야 함).

그룹 트리 이동 (부모 변경)

PATCH/v1/admin/member-groups/{id}/parent/

parent_id

integer | null

required

새 상위 그룹 ID. null이면 루트로 이동.

순환 참조·유형 불일치·테넌트 불일치·최대 깊이·계층형 유형 필수 조건을 검증합니다. 상태 코드: 200 / 400 / 401 / 403 / 404

멤버 추가

POST/v1/admin/member-groups/{id}/members/

member_ids

array[integer]

required

추가할 멤버 ID 목록 (최소 1개).

append 방식이라 다른 그룹에서 자동 제거되지 않습니다. 단일 소속(single-membership) 유형 충돌 시 실패합니다.

상태 코드: 200 / 400 / 401 / 403 / 404

멤버 제거 / 이동

멤버 1명 제거

DELETE/v1/admin/member-groups/{id}/members/{member_id}/

마지막 남은 필수 유형 그룹은 제거할 수 없습니다(400).

멤버 대량 제거

POST/v1/admin/member-groups/{id}/members/remove-bulk/

member_ids

array[integer]

required

제거할 멤버 ID 목록 (최소 1개).

멤버 이동

POST/v1/admin/member-groups/{id}/members/move/

member_ids

array[integer]

required

이동할 멤버 ID 목록 (최소 1개).

target_member_group_id

integer

required

대상 그룹 ID.

apply_quota

boolean

대상 그룹의 quota_source를 즉시 적용 (기본 false).

추가 가능한 멤버 검색

GET/v1/admin/member-groups/{id}/addable-members/

쿼리 파라미터 search(선택)로 이름/이메일 부분 검색이 가능합니다. 응답 data[] 각 항목:

addable

boolean

추가 가능 여부.

reason_code

string | null

추가 불가 사유. single_membership_conflict 또는 already_member.

conflict_type

object | null

충돌 유형 그룹 정보.

그 외 id, name, email을 포함합니다.

그룹 관리자 관리

GET/v1/admin/member-groups/{id}/admins/

응답 data.admins[]: id, name, email, created_at(ISO 8601), include_descendants.

지정

POST/v1/admin/member-groups/{id}/admins/

member_id

integer

required

관리자로 지정할 멤버 ID (> 0).

include_descendants

boolean | null

하위 트리 포함 여부 (마스터 관리자만 변경 가능).

그룹 관리자는 자신이 관리하는 그룹에만 지정할 수 있으며, 대상 멤버는 이미 해당 그룹 소속이어야 합니다.

해제

DELETE/v1/admin/member-groups/{id}/admins/{member_id}/

응답: { "success": true }.

대량(Bulk) 작업

두 엔드포인트 모두 최대 500개 그룹/요청, 부분 성공을 지원합니다. 공통 응답:

크레딧 한도 대량 설정

PATCH/v1/admin/member-groups/bulk/credit-limit/

member_group_ids

array[integer]

required

대상 그룹 ID 목록 (1~500).

group_credit_quota

integer | null

그룹 크레딧 한도. null이면 무제한/해제.

멤버 1인 한도가 먼저 설정돼 있어야 하며(member_quota_required), 엔터프라이즈 플랜 전용입니다(그 외 전부 not_enterprise로 실패).

모델 권한 대량 설정

PATCH/v1/admin/member-groups/bulk/model-permissions/

member_group_ids

array[integer]

required

대상 그룹 ID 목록 (1~500).

model_permissions

array[object]

required

{ "llm_model_id": int, "is_available": bool } 항목 목록 (최소 1개).

테넌트에 노출/사용 가능한 모델만 허용되며, 지정한 모델만 부분 변경됩니다.

사용량 개요

GET/v1/admin/member-groups/usage-overview/

그룹별 사용량·한도·모델 허용 수를 목록으로 조회합니다(페이지네이션).

쿼리 파라미터: member_group_type_id, parent_id(직속 자식만), search_term, order_by(field.direction — 지원 필드 credit_used_month / name / utilization), page(기본 1), size(기본 100).

응답 data.results[] 주요 필드: member_count, group_credit_quota, member_credit_quota, credit_used_month, credit_used_30d, credit_projected_month, credit_used_weekly(array[int]), ancestors[], allowed_model_count, total_model_count. data.pagination은 page, total_pages, total_items를 포함합니다.

기능/권한 제어 (고급)

에이전트 설정

GET · PATCH

/v1/admin/member-groups/{id}/agents/

그룹별로 특정 에이전트/기능(예: law_in_data, korea_in_data, univ_in_data 등 AgentKey)의 활성 여부를 제어합니다.

GET 응답 data[]: { agent_type, is_enabled, tenant_default }
PATCH 바디: { "agent_type": <AgentKey>, "is_enabled": true | false | null } — true/false는 그룹 오버라이드 upsert, null은 오버라이드 삭제(테넌트 기본값 상속).

권한 세트 토글

GET · PATCH

/v1/admin/member-groups/{id}/permission-set/

마스터 관리자 전용입니다.

그룹 레벨 기능 권한을 3-state(true=허용 / false=차단 / null=상속)로 토글합니다. 여러 그룹에 속한 멤버는 그룹 토글이 OR로 결합되며, 그룹은 테넌트와 멤버 사이의 우선순위 단계에 위치합니다.

에러 코드

코드	의미
`400`	요청/트리/제약 위반
`401`	인증 실패 (세션/토큰 없음·만료)
`403`	권한 부족 (비활성·비관리자·범위 밖 그룹)
`404`	그룹/멤버 없음
`409`	이름 중복 등 충돌

참고: 멤버(비관리자)용 조회

관리자 API와 별개로, 로그인 세션 기반의 조회 엔드포인트가 있습니다(어드민 권한 불필요).

GET /v1/member-groups/ — 전체 그룹 목록 (페이지네이션·검색·정렬)
GET /v1/member-groups/managed/ — 현재 사용자가 관리하는 그룹 목록 (대시보드 그룹 스위처용)

마지막 수정 날짜: Jul 22, 2026

/credits

에러

Docs

/

멤버 그룹 관리 API

인증

엔드포인트 요약

그룹 생성

요청 파라미터

요청 예시

응답 예시

그룹 조회

그룹 수정

그룹 삭제

그룹 트리 이동 (부모 변경)

멤버 추가

멤버 제거 / 이동

멤버 1명 제거

멤버 대량 제거

멤버 이동

추가 가능한 멤버 검색

그룹 관리자 관리

목록

지정

해제

대량(Bulk) 작업

크레딧 한도 대량 설정

모델 권한 대량 설정

사용량 개요

기능/권한 제어 (고급)

에이전트 설정

권한 세트 토글

에러 코드

참고: 멤버(비관리자)용 조회