도구 레퍼런스

서버는 아래의 도구들을 제공합니다. 각 도구는 명시된 OAuth 권한 스코프를 요구하며, scorecards:read 권한만 가진 연결은 scorecards:write가 필요한 도구를 실행할 수 없습니다.

파괴적(Destructive) 으로 표기된 도구는 기존 데이터를 덮어쓰거나 영구 삭제합니다. 대다수 클라이언트는 실행 전 사용자 확인을 요청합니다.

scorecard_design_guide

스코어카드를 신규 제작하거나 대대적으로 수정하기 전에 확인하세요. 사전 인터뷰 질문, 왜곡 없는 문항 작성법, 인사이트 도출법, 테마 선택 기준을 다룹니다.

스코프: scorecards:read · 멱등성(Idempotent)

인자	타입	필수 여부	설명
topics	문자열 배열	아니오	조회할 특정 주제 목록 (예: “themes”, “questions”). 생략 시 전체 반환.

list_scorecards

계정 내 스코어카드 목록(슬러그, 발행 상태, 제출 건수, 임베드 허용 도메인 등)을 조회합니다.

스코프: scorecards:read · 멱등성(Idempotent)

인자	타입	필수 여부	설명
status	all | published | draft	아니오	발행 상태 필터링. 기본값은 all.

get_scorecard

스코어카드의 전체 구성을 조회합니다: 레이아웃, 영역, 문항, 선택지, 등급 기준.

스코프: scorecards:read · 멱등성(Idempotent)

인자	타입	필수 여부	설명
slug	문자열	예	스코어카드 고유 슬러그.

create_scorecard

표현 설정, 브랜딩, 종합 평가 방식, 임베드 및 이메일 수집 옵션을 지정하여 새로운 초안을 생성합니다.

스코프: scorecards:write

인자	타입	필수 여부	설명
title	문자열	예	응답자에게 표시될 스코어카드 제목.
subtitle	문자열	아니오	대상과 소요 시간을 설명하는 부제목.
slug	문자열	아니오	고유 URL 슬러그. 생략 시 제목에서 자동 생성.
idempotencyKey	문자열	아니오	네트워크 재시도 시 중복 생성을 방지하는 고유 키.
ctaText	문자열	아니오	시작 버튼 문구.
version	문자열	아니오	내부 관리용 버전 표기 (예: “1.0”).
theme	default | playground | obsidian | brutalist	아니오	적용할 시각 테마.
overallTierStrategy	weakest | average	아니오	종합 결과 산출 전략: weakest (가장 취약한 영역 기준) 또는 average (평균값).
tiers	객체 배열	아니오	종합 결과 등급 구성.
emailCaptureBeforeQuestions	불리언	아니오	이메일 수집을 문항 풀이 전에 배치할지 여부.
privacyPolicyUrl	문자열 또는 null	아니오	개인정보처리방침 URL.
termsUrl	문자열 또는 null	아니오	이용약관 URL.
embed	객체	아니오	iframe 임베드 설정.
branding	객체	아니오	브랜드 컬러, 로고 및 최종 CTA 설정.
emailCapture	객체	아니오	연락처 수집 폼 설정.
detail	summary | full	아니오	반환 정보의 상세 수준 (기본값: summary).

update_scorecard_config

영역이나 문항을 변경하지 않고 스코어카드의 전반적인 설정을 변경합니다.

스코프: scorecards:write · 파괴적

인자	타입	필수 여부	설명
slug	문자열	예	수정할 스코어카드의 현재 슬러그.
newSlug	문자열	아니오	새로 변경할 슬러그 (기존 URL 리다이렉트는 생성되지 않음).
title	문자열	아니오	새로운 제목.
subtitle	문자열	아니오	새로운 부제목.
ctaText	문자열	아니오	새로운 시작 버튼 문구.
version	문자열	아니오	새로운 버전 문자열.
theme	default | playground | obsidian | brutalist	아니오	새로운 시각 테마.
overallTierStrategy	weakest | average	아니오	새로운 종합 결과 산출 전략.
tiers	객체 배열	아니오	새로운 종합 등급 설정.
emailCaptureBeforeQuestions	불리언	아니오	이메일 수집 시점.
privacyPolicyUrl	문자열 또는 null	아니오	새로운 개인정보처리방침 URL.
termsUrl	문자열 또는 null	아니오	새로운 이용약관 URL.
embed	객체	아니오	수정할 임베드 설정.
branding	객체	아니오	수정할 브랜드 색상 및 설정.
emailCapture	객체	아니오	수정할 연락처 폼 설정.
detail	summary | full	아니오	반환 정보 상세 수준.

add_dimension

스코어카드에 평가 영역을 추가합니다.

스코프: scorecards:write

인자	타입	필수 여부	설명
slug	문자열	예	스코어카드 슬러그.
label	문자열	예	영역 명칭 (예: “범위 합의의 명확성”).
shortLabel	문자열	아니오	차트 축 등에 사용할 짧은 명칭.
key	문자열	아니오	영역의 영구 고유 키.
detail	summary | full	아니오	반환 정보 상세 수준.

add_questions

특정 영역에 속하는 모든 문항을 단일 호출로 일괄 추가합니다. 선택지는 최악에서 최선 순으로 점수가 매겨져 있어야 합니다.

스코프: scorecards:write

인자	타입	필수 여부	설명
slug	문자열	예	스코어카드 슬러그.
dimensionKey	문자열	예	문항이 속할 영역 키.
questions	객체 배열	예	정렬된 문항 배열 (권장: 3~5개).
detail	summary | full	아니오	반환 정보 상세 수준.

add_question

영역에 단일 문항을 개별 추가합니다.

스코프: scorecards:write

인자	타입	필수 여부	설명
slug	문자열	예	스코어카드 슬러그.
dimensionKey	문자열	예	영역 키.
text	문자열	예	질문 문장.
answers	객체 배열	아니오	채점된 선택지 배열.
detail	summary | full	아니오	반환 정보 상세 수준.

set_dimension_tiers

영역별 결과 등급(등급명 및 진단 인사이트)을 최하위 등급부터 최상위 순으로 설정합니다. 점수 기준선은 자동 산출됩니다.

스코프: scorecards:write · 파괴적, 멱등성(Idempotent)

인자	타입	필수 여부	설명
slug	문자열	예	스코어카드 슬러그.
dimensionKey	문자열	예	대상 영역 키.
tiers	객체 배열	예	오름차순 등급 정의 (통상 3단계).
detail	summary | full	아니오	반환 정보 상세 수준.

update_dimension

영역의 명칭, 축약명, 가중치 또는 표시 순서를 수정합니다. 영구 키는 변경할 수 없습니다.

스코프: scorecards:write · 파괴적, 멱등성(Idempotent)

인자	타입	필수 여부	설명
slug	문자열	예	스코어카드 슬러그.
dimensionKey	문자열	예	수정할 영역 키.
label	문자열	아니오	새로운 전체 명칭.
shortLabel	문자열	아니오	새로운 축약 명칭.
weight	정수	아니오	종합 산출 시 상대 가중치.
position	정수	아니오	정렬 순서 (0부터 시작).
detail	summary | full	아니오	반환 정보 상세 수준.

update_question

문항의 텍스트, 선택지 구성 또는 영역 내 표시 순서를 변경합니다. 과거 제출 내역에는 영향을 미치지 않습니다.

스코프: scorecards:write · 파괴적, 멱등성(Idempotent)

인자	타입	필수 여부	설명
slug	문자열	예	스코어카드 슬러그.
questionId	문자열	예	수정할 문항 ID.
text	문자열	아니오	새로운 질문 문장.
answers	객체 배열	아니오	새로운 선택지 및 점수.
position	정수	아니오	영역 내 새로운 순서.
detail	summary | full	아니오	반환 정보 상세 수준.

remove_question

영역에서 문항을 삭제하며, 영역의 등급 점수 구간은 자동으로 재계산됩니다.

스코프: scorecards:write · 파괴적

인자	타입	필수 여부	설명
slug	문자열	예	스코어카드 슬러그.
questionId	문자열	예	삭제할 문항 ID.
detail	summary | full	아니오	반환 정보 상세 수준.

remove_dimension

영역과 그에 속한 모든 문항을 완전히 삭제합니다.

스코프: scorecards:write · 파괴적

인자	타입	필수 여부	설명
slug	문자열	예	스코어카드 슬러그.
dimensionKey	문자열	예	삭제할 영역 키.
detail	summary | full	아니오	반환 정보 상세 수준.

check_scorecard

스코어카드가 발행 요건을 충족하는지 검사하고 부족한 점을 분석해 보고합니다.

스코프: scorecards:read · 멱등성(Idempotent)

인자	타입	필수 여부	설명
slug	문자열	예	대상 스코어카드 슬러그.

publish_scorecard

스코어카드를 공개 상태로 전환하거나 다시 초안 상태로 되돌립니다.

스코프: scorecards:write · 파괴적, 멱등성(Idempotent)

인자	타입	필수 여부	설명
slug	문자열	예	대상 스코어카드 슬러그.
published	불리언	아니오	공개하려면 true, 초안 회수는 false.
detail	summary | full	아니오	반환 정보 상세 수준.

list_submissions

수집된 제출 내역을 최신순으로 조회하며 상태, 등급, 날짜 필터링을 지원합니다.

스코프: scorecards:read · 멱등성(Idempotent)

인자	타입	필수 여부	설명
slug	문자열	아니오	특정 스코어카드로 한정. 생략 시 전체 계정 대상.
status	all | completed | partial	아니오	완료 또는 중도 이탈 필터.
tier	문자열	아니오	종합 등급명으로 필터링.
dimension	문자열	아니오	최저점을 받은 취약 영역명으로 필터링.
since	문자열	아니오	시작 일자 (YYYY-MM-DD).
until	문자열	아니오	종료 일자 (YYYY-MM-DD).
search	문자열	아니오	이름, 이메일, 회사명 검색.
limit	정수	아니오	반환 건수 (기본값: 25).

get_submission

단일 제출 내역의 전체 데이터(연락처, 종합 결과, 영역별 점수, 제출 당시의 문항 및 선택지)를 상세 조회합니다.

스코프: scorecards:read · 멱등성(Idempotent)

인자	타입	필수 여부	설명
submissionId	문자열	예	제출 ID.