KLASSLAB API / V1

빠른 시작

첫 번째 요청부터 데이터 활용까지.

API 버전

직접 수업 도구를 만들고 싶은 선생님이라면 선생님 개발 가이드부터 살펴보세요. Codex 연결부터 화면 개발까지 순서대로 안내합니다.

시작하기 전에

대표자 계정, 활성 API 구독과 사용할 기능의 권한이 필요합니다. 웹 서비스 구독 없이 가입할 수 있습니다.

02 API 키 만들기

키 관리에서 이름·유효기간·권한을 정합니다. 유효기간은 1~365일 또는 만료 없음으로 선택할 수 있습니다. 만료 없는 키도 API 사용에는 활성 구독이 필요합니다. 첫 조회에는 students.read를 선택하세요. 키 원문은 발급 직후 한 번만 표시됩니다.

03 첫 요청 보내기

아래 키와 학생 데이터는 예시입니다. 실제 키는 서버의 환경변수에 보관하세요.

BASH

curl "https://api.klasslab.com/v1/students?page=1&pageSize=30"   -H "Authorization: Bearer $KLASSLAB_API_KEY"

JAVASCRIPT · SERVER

const response = await fetch(
  'https://api.klasslab.com/v1/students?page=1',
  { headers: { Authorization: `Bearer ${process.env.KLASSLAB_API_KEY}` } }
);
if (!response.ok) throw new Error(`HTTP ${response.status}`);
const { data, meta } = await response.json();

04 데이터를 변경할 때

POST·PUT·PATCH·DELETE에는 Idempotency-Key 헤더가 필수입니다. 서버에서 발급받는 값이 아니라 호출하는 프로그램에서 직접 생성하는 중복 방지 키이며, API 인증 키와 별개입니다. 조회(GET)에는 필요하지 않습니다.

영문·숫자·하이픈·밑줄로 8~100자를 사용하세요. UUID를 권장합니다. JavaScript에서는 crypto.randomUUID(), C#에서는 Guid.NewGuid().ToString()으로 생성할 수 있습니다.

새 작업에는 새 키를 생성합니다.
통신 오류 등으로 같은 요청을 재시도할 때는 기존 키·경로·본문을 그대로 사용합니다. 재시도할 때마다 키를 새로 만들면 중복 실행을 막을 수 없습니다.
다른 요청에 같은 키를 사용하면 409 idempotency_mismatch 오류가 발생합니다.

아래 값은 형식 예시입니다. 실제 호출에서는 직접 생성하고 재시도에 사용할 수 있도록 보관하세요. 실제 수정 필드와 필수값은 해당 API 레퍼런스를 확인하세요.

Content-Type: application/json
Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000

응답과 오류 확인

성공 응답은 data와 meta.requestId를 반환합니다. 401은 키 인증, 403은 구독·권한, 402는 크레딧, 409는 입력 상태·중복 요청, 429는 사용량 한도를 확인하세요. 처리 결과가 불확실하면 새 키로 반복 실행하지 말고 요청·작업 번호로 확인하세요.

빠른 시작

02 API 키 만들기

03 첫 요청 보내기

04 데이터를 변경할 때

응답과 오류 확인

페이지

문서

API 레퍼런스

빠른 시작

01 API 전용 구독 신청

02 API 키 만들기

03 첫 요청 보내기

04 데이터를 변경할 때

응답과 오류 확인