세미클래스를 내 도구에 연결하세요
강의 일정을 가져오고, 배운 내용을 내 기록으로 남겨 보세요.
코드가 익숙하지 않아도 시작할 수 있는 공개 API 문서입니다.
나에게 편한 설명으로 읽으세요
시작하기
API는 AI나 프로그램이 세미클래스에 정보를 요청하는 통로예요. 강의 목록을 받아 일정표를 만들거나, 배운 내용을 내 후기로 남길 수 있어요.
- 아래에서 하고 싶은 일을 고르세요.
- ‘사용법’의 프롬프트를 복사해 AI에게 붙여넣으세요.
- API 키가 필요한 요청이면 키를 발급받고 내려받은 파일의 위치를 AI에게 알려 주세요.
처음이라면 ‘강의 목록 받기’부터 시작하세요. 로그인이나 API 키 없이 바로 사용해 볼 수 있어요.
키 원문은 대화에 붙여넣지 마세요. 파일은 내 기기에 보관하세요. 일반 채팅 AI는 직접 요청하지 못할 수 있으니, 요청을 실행할 수 있는 AI 도구를 사용하세요.
https://semiclass.kr/api/v1HTTPS JSON REST API입니다. 강의 목록은 무인증, 나머지는 회원 키를 사용하는 Bearer 인증입니다. 회원 API 관리에서 발급하세요. REST 키와 MCP 연결 키는 별개입니다.
- 키 수명 30일, 활성 키 최대 5개. 원문은 발급 직후 한 번만 내려받을 수 있습니다. 폐기 즉시 새 요청이 거부됩니다.
- 회원 데이터 요청은 회원당 합산 분당 60회, 무인증 강의 조회는 전체 합산 분당 600회입니다. 429 응답에는 Retry-After: 60이 포함됩니다.
- 목록은 limit / offset 페이지네이션입니다. 정의되지 않은 쿼리·본문 필드는 400입니다. 응답은 Cache-Control: private, no-store를 사용합니다.
- 외부 Origin에 대한 CORS 허용 헤더를 제공하지 않습니다. 외부 웹앱에서는 서버에서 호출하고, 회원 키를 프런트엔드 코드에 포함하지 마세요.
- 후기 생성은 자동 재시도하지 마세요. 응답이 불확실하면 GET으로 저장 여부를 확인하세요. API에서 후기 수정·삭제·공개 승인은 제공하지 않습니다.
오류 응답과 상태 코드
{
"error": {
"code": "invalid_key",
"message": "유효한 회원 API 키가 필요합니다."
}
}| 필드 | 타입 / 필수 여부 | 설명 |
|---|---|---|
| 400 | invalid_input | 필수 항목, 타입, 범위, JSON 문법과 추가 필드를 확인하세요. |
| 401 | invalid_key | 키 누락·형식 오류·만료·폐기입니다. 유효한 회원 REST 키를 보내세요. |
| 403 | access_blocked | 현재 회원 계정으로 API를 사용할 수 없습니다. |
| 404 | lecture_not_found | 후기를 남길 공개 강의를 찾을 수 없습니다. |
| 409 | review_exists | 이미 후기가 있습니다. 웹에서 확인하거나 수정하세요. |
| 413 | payload_too_large | 본문을 UTF-8 기준 32KiB 이하로 줄이세요. |
| 415 | json_required | Content-Type: application/json 헤더가 필요합니다. |
| 429 | rate_limited | Retry-After: 60에 따라 60초 후 다시 요청하세요. |
| 503 | unavailable | 잠시 후 다시 확인하세요. 후기 쓰기는 GET으로 저장 여부부터 확인하세요. |
강의 목록 받기
- 이 요청은?
- 공개된 강의 목록을 받기 위한 요청이에요.
- 필요한 것
- 로그인 필요 없음API 키 필요 없음
- 로그인도 API 키도 필요 없어요. 아래 프롬프트부터 사용해 보세요.
- 받는 것
- 강의 목록 — 강의 이름, 소개, 강의 시간, 강의 번호
강의 소개 목록을 받아요. 강의 자료 파일을 내려받는 요청은 아니에요.
사용법
아래 프롬프트를 복사해 API 요청을 실행할 수 있는 AI에게 붙여넣으세요.
세미클래스의 공개 강의 목록을 가져와 줘.
GET https://semiclass.kr/api/v1/lectures?limit=20&offset=0 으로 요청해 줘. 로그인이나 API 키는 필요 없어.
응답의 lectures에서 title(강의명), subtitle(소개), duration_min(분)을 읽어 보기 쉬운 표로 정리해 줘.
목록이 20개이면 offset을 20씩 늘려 나머지도 확인해 줘. 429가 오면 60초 후 다시 시도해 줘./api/v1/lectures
공개된 강의 목록을 받기 위한 요청이에요.
요청 헤더
| 필드 | 타입 / 필수 여부 | 설명 |
|---|---|---|
| Accept | 선택 | application/json. 응답 형식은 JSON입니다. |
쿼리 파라미터
| 필드 | 타입 / 필수 여부 | 설명 |
|---|---|---|
| limit | integer · 선택 | 1~50, 기본 20. 한 번에 받을 개수입니다. |
| offset | integer · 선택 | 0~10000, 기본 0. 앞에서 건너뛸 개수입니다. |
curl 'https://semiclass.kr/api/v1/lectures?limit=20&offset=0'성공 응답 · HTTP 200
아래 값은 응답 구조를 보여 주기 위한 가상 예제입니다.
{
"lectures": [
{
"id": 123,
"slug": "example-class",
"title": "API로 내 업무 연결하기",
"subtitle": "요청부터 업무 적용까지",
"duration_min": 120
}
]
}| 필드 | 타입 / 필수 여부 | 설명 |
|---|---|---|
| lectures | array | 공개 강의 목록. 결과가 없으면 []입니다. ID 오름차순입니다. |
| lectures[].id | integer | 강의 ID. 회차 조회의 lectureId에 사용합니다. |
| lectures[].slug | string | 강의 페이지 주소의 식별자입니다. |
| lectures[].title | string | 강의 제목입니다. |
| lectures[].subtitle | string | null | 강의 부제입니다. |
| lectures[].duration_min | integer | null | 강의 시간(분)입니다. |
- 강의 화면의 배포용 ‘강의 자료’ 파일이나 다운로드 링크를 반환하는 API는 아닙니다.
- 공개 조회 한도는 모든 호출자 합산 분당 600회입니다. total·next 필드는 없으며 lectures가 limit보다 짧으면 마지막 페이지입니다.
강의 일정 받기
- 이 요청은?
- 선택한 강의가 언제 열리는지, 내가 신청한 회차가 무엇인지 확인하는 요청이에요.
- 필요한 것
- 로그인 필요 · 키 발급 시API 키 필요
- 로그인해서 API 키를 한 번 발급받으세요. 요청할 때는 그 키와 강의 번호가 필요해요.
- 받는 것
- 강의 일정 목록 — 회차 이름, 시작·종료 시간, 진행 상태, 후기 작성 가능 여부
사용법
아래 프롬프트를 복사해 API 요청을 실행할 수 있는 AI에게 붙여넣으세요.
세미클래스 강의 일정을 확인해 줘.
API 키는 로그인 후 https://semiclass.kr/my/developer 에서 내려받은 semiclass-api-key.json 파일을 내 기기에서 읽어 사용해 줘. 파일 경로를 먼저 물어봐 줘. 키 원문을 대화나 로그에 출력하거나 코드에 저장하지 마. 이 키는 MCP 연결 키와 달라.
먼저 GET https://semiclass.kr/api/v1/lectures 로 강의를 보여 주고 내가 고르게 해 줘.
선택한 강의의 id를 lectureId에 넣어 GET https://semiclass.kr/api/v1/cohorts?lectureId=선택한_ID&limit=20&offset=0 을 Authorization: Bearer <파일의 token> 헤더로 요청해 줘.
cohorts의 label, startsAt, endsAt, status를 한국 시간 기준 일정표로 정리해 줘. 빈 목록이면 조회 가능한 회차가 없다고 알려 줘.키가 없다면 API 키 발급 페이지에서 로그인 후 내려받으세요. 요청할 때마다 웹에 로그인할 필요는 없어요.
/api/v1/cohorts
선택한 강의가 언제 열리는지, 내가 신청한 회차가 무엇인지 확인하는 요청이에요.
요청 헤더
| 필드 | 타입 / 필수 여부 | 설명 |
|---|---|---|
| Authorization | 필수 | Bearer <회원 REST API 키>. 웹 로그인 쿠키로 대체할 수 없습니다. |
| Accept | 선택 | application/json. 응답 형식은 JSON입니다. |
쿼리 파라미터
| 필드 | 타입 / 필수 여부 | 설명 |
|---|---|---|
| lectureId | integer · 필수 | 양의 정수 강의 ID. 강의 목록의 id입니다. |
| limit | integer · 선택 | 1~50, 기본 20. 한 번에 받을 개수입니다. |
| offset | integer · 선택 | 0~10000, 기본 0. 앞에서 건너뛸 개수입니다. |
curl 'https://semiclass.kr/api/v1/cohorts?lectureId=123&limit=20&offset=0' \
-H "Authorization: Bearer $SEMICLASS_API_KEY"예제의 SEMICLASS_API_KEY는 내 실행 환경의 변수입니다. 123과 예제 UUID는 실제 강의·회차 ID로 바꾸세요.
성공 응답 · HTTP 200
아래 값은 응답 구조를 보여 주기 위한 가상 예제입니다.
{
"cohorts": [
{
"id": "00000000-0000-4000-8000-000000000001",
"lectureId": 123,
"label": "10월 토요일반",
"startsAt": "2026-10-17T05:00:00+00:00",
"endsAt": "2026-10-17T07:00:00+00:00",
"status": "scheduled",
"canReview": true
}
]
}| 필드 | 타입 / 필수 여부 | 설명 |
|---|---|---|
| cohorts | array | 공개 모집 중인 회차 또는 본인의 유효한 수강 등록이 있는 회차입니다. 시작 시간·ID 순입니다. |
| cohorts[].id | UUID string | 회차 ID입니다. 후기는 강의 ID(lectureId)를 사용합니다. |
| cohorts[].lectureId | integer | 강의 ID입니다. |
| cohorts[].label | string | 회차 이름입니다. |
| cohorts[].startsAt / endsAt | ISO 8601 string / string | null | 시작·종료 시각입니다. 시간대 오프셋을 확인해 표시하세요. |
| cohorts[].status | string | 회차 상태입니다. scheduled, in_progress, completed입니다. |
| cohorts[].canReview | boolean | 공개 강의에 후기 작성이 가능한지 표시합니다. 회차 신청은 필요하지 않으며 기존 후기는 강의 단위로 조회하세요. |
- 공개 모집 회차도 회원 API 키가 있어야 조회할 수 있습니다. 비공개 회차는 본인의 수강 등록 범위에서만 반환됩니다.
- 결과가 없으면 cohorts: []입니다. 페이지당 최대 50개이며 total·next 필드는 없습니다.
내 후기 확인하기
- 이 요청은?
- 특정 강의에 내가 남긴 수강 후기와 업무 적용 기록을 확인하는 요청이에요.
- 필요한 것
- 로그인 필요 · 키 발급 시API 키 필요
- API 키와 강의 번호가 필요해요. 강의 번호는 ‘강의 목록 받기’에서 확인할 수 있어요.
- 받는 것
- 내 후기 한 건 — 별점, 배운 점, 업무에 적용할 내용, 공개 동의와 승인 상태
사용법
아래 프롬프트를 복사해 API 요청을 실행할 수 있는 AI에게 붙여넣으세요.
세미클래스에서 내가 남긴 후기를 확인해 줘.
API 키는 로그인 후 https://semiclass.kr/my/developer 에서 내려받은 semiclass-api-key.json 파일을 내 기기에서 읽어 사용해 줘. 파일 경로를 먼저 물어봐 줘. 키 원문을 대화나 로그에 출력하거나 코드에 저장하지 마. 이 키는 MCP 연결 키와 달라.
조회할 강의 ID(lectureId)를 물어봐 줘. 모르면 공개 강의 목록 조회로 내가 고르게 해 줘.
GET https://semiclass.kr/api/v1/reviews?lectureId=선택한_강의_ID 를 Authorization: Bearer <파일의 token> 헤더로 요청해 줘.
review의 rating, reflection, application, status를 정리해 줘. review가 null이면 아직 저장된 후기가 없다고 알려 줘. 다른 사람의 후기는 조회하지 마.키가 없다면 API 키 발급 페이지에서 로그인 후 내려받으세요. 요청할 때마다 웹에 로그인할 필요는 없어요.
/api/v1/reviews
특정 강의에 내가 남긴 수강 후기와 업무 적용 기록을 확인하는 요청이에요.
요청 헤더
| 필드 | 타입 / 필수 여부 | 설명 |
|---|---|---|
| Authorization | 필수 | Bearer <회원 REST API 키>. 웹 로그인 쿠키로 대체할 수 없습니다. |
| Accept | 선택 | application/json. 응답 형식은 JSON입니다. |
쿼리 파라미터
| 필드 | 타입 / 필수 여부 | 설명 |
|---|---|---|
| lectureId | integer · 필수 | 강의 목록 응답의 lectures[].id입니다. |
curl 'https://semiclass.kr/api/v1/reviews?lectureId=123' \
-H "Authorization: Bearer $SEMICLASS_API_KEY"예제의 SEMICLASS_API_KEY는 내 실행 환경의 변수입니다. 123과 예제 UUID는 실제 강의·회차 ID로 바꾸세요.
성공 응답 · HTTP 200
아래 값은 응답 구조를 보여 주기 위한 가상 예제입니다.
{
"review": {
"id": "00000000-0000-4000-8000-000000000001",
"cohortId": null,
"lectureId": 123,
"rating": 5,
"reflection": "반복 업무를 API로 연결하는 방법을 배웠습니다.",
"application": "팀 교육 일정표에 연결해 보겠습니다.",
"displayMode": "anonymous",
"publicConsent": false,
"status": "pending",
"createdAt": "2026-10-17T01:00:00+00:00",
"updatedAt": "2026-10-17T01:00:00+00:00"
}
}| 필드 | 타입 / 필수 여부 | 설명 |
|---|---|---|
| review | object | null | 내 후기 한 건. GET에서 없으면 null입니다. POST 성공 시에는 객체입니다. |
| review.id | UUID string | 후기 ID입니다. |
| review.cohortId | UUID string | null | 과거 회차 연결 정보입니다. 새 강의 후기는 null입니다. |
| review.lectureId | integer | 강의 ID입니다. |
| review.rating | integer | 1~5 별점입니다. |
| review.reflection / application | string | 배운 점 / 업무 적용 내용입니다. |
| review.displayMode | string | 후기 작성자 표시 방식입니다. API 생성 시 anonymous입니다. |
| review.publicConsent | boolean | 본인의 공개 동의 여부입니다. API 생성 시 false입니다. |
| review.status | string | 후기 승인 상태입니다. API 생성 시 pending입니다. |
| review.createdAt / updatedAt | ISO 8601 string / string | null | 생성 / 수정 시각입니다. |
- 본인의 후기만 조회합니다. 저장된 후기가 없으면 HTTP 200과 {"review":null}을 반환합니다.
- 수강 취소 후에도 본인이 작성한 후기 이력은 조회할 수 있습니다. 계정 차단·키 만료·폐기 시에는 사용할 수 없습니다.
내 후기 남기기
- 이 요청은?
- 선택한 강의에 배운 점과 업무에 적용할 내용을 새 후기로 저장하는 요청이에요.
- 필요한 것
- 로그인 필요 · 키 발급 시API 키 필요회차 신청 없이 작성 가능
- API 키, 공개 강의 번호, 별점(1~5), 배운 점, 업무 적용 내용이 필요해요.
- 받는 것
- 저장된 내 후기 — 처음에는 공개 동의 없이 승인 대기 상태로 저장돼요
사용법
아래 프롬프트를 복사해 API 요청을 실행할 수 있는 AI에게 붙여넣으세요.
세미클래스에 내 수강 후기를 남기는 것을 도와줘.
API 키는 로그인 후 https://semiclass.kr/my/developer 에서 내려받은 semiclass-api-key.json 파일을 내 기기에서 읽어 사용해 줘. 파일 경로를 먼저 물어봐 줘. 키 원문을 대화나 로그에 출력하거나 코드에 저장하지 마. 이 키는 MCP 연결 키와 달라.
강의 ID(lectureId), 별점(1~5), 배운 점(10~1200자), 업무 적용 내용(최대 1200자, 없으면 빈 문자열)을 한 번에 하나씩 물어봐 줘. 내용을 지어내지 마.
먼저 GET https://semiclass.kr/api/v1/reviews?lectureId=강의_ID 로 기존 후기를 확인해 줘. 있으면 웹에서 수정하도록 안내해 줘.
내가 입력한 최종 내용을 보여 주고 저장해도 되는지 확인받은 다음 POST https://semiclass.kr/api/v1/reviews 로 요청해 줘.
Authorization: Bearer <파일의 token>, Content-Type: application/json 헤더와 {"lectureId":강의_ID,"rating":별점,"reflection":"배운 점","application":"업무 적용 내용"} 본문을 사용해 줘.
201 응답일 때만 저장 완료라고 알려 줘. 409이면 덮어쓰지 말고 웹에서 확인하도록 안내해 줘. 응답을 못 받으면 GET으로 저장 여부부터 확인하고 POST를 자동 반복하지 마. 후기는 처음에 비공개로 저장돼.키가 없다면 API 키 발급 페이지에서 로그인 후 내려받으세요. 요청할 때마다 웹에 로그인할 필요는 없어요.
/api/v1/reviews
선택한 강의에 배운 점과 업무에 적용할 내용을 새 후기로 저장하는 요청이에요.
요청 헤더
| 필드 | 타입 / 필수 여부 | 설명 |
|---|---|---|
| Authorization | 필수 | Bearer <회원 REST API 키>. 웹 로그인 쿠키로 대체할 수 없습니다. |
| Content-Type | 필수 | application/json |
| Accept | 선택 | application/json. 응답 형식은 JSON입니다. |
JSON 요청 본문
| 필드 | 타입 / 필수 여부 | 설명 |
|---|---|---|
| lectureId | integer · 필수 | 후기를 남길 공개 강의 ID입니다. 회차 신청 여부와 관계없이 활성 회원 누구나 작성할 수 있습니다. |
| rating | integer · 필수 | 1~5의 정수 별점입니다. |
| reflection | string · 필수 | 앞뒤 공백 제거 후 10~1200자의 배운 점입니다. |
| application | string · 필수 | 앞뒤 공백 제거 후 최대 1200자. 내용이 없으면 빈 문자열을 보냅니다. |
curl 'https://semiclass.kr/api/v1/reviews' \
-X POST \
-H "Authorization: Bearer $SEMICLASS_API_KEY" \
-H 'Content-Type: application/json' \
--data '{
"lectureId": 123,
"rating": 5,
"reflection": "반복 업무를 API로 연결하는 방법을 배웠습니다.",
"application": "팀 교육 일정표에 연결해 보겠습니다."
}'예제의 SEMICLASS_API_KEY는 내 실행 환경의 변수입니다. 123과 예제 UUID는 실제 강의·회차 ID로 바꾸세요.
성공 응답 · HTTP 201
아래 값은 응답 구조를 보여 주기 위한 가상 예제입니다.
{
"review": {
"id": "00000000-0000-4000-8000-000000000001",
"cohortId": null,
"lectureId": 123,
"rating": 5,
"reflection": "반복 업무를 API로 연결하는 방법을 배웠습니다.",
"application": "팀 교육 일정표에 연결해 보겠습니다.",
"displayMode": "anonymous",
"publicConsent": false,
"status": "pending",
"createdAt": "2026-10-17T01:00:00+00:00",
"updatedAt": "2026-10-17T01:00:00+00:00"
}
}| 필드 | 타입 / 필수 여부 | 설명 |
|---|---|---|
| review | object | null | 내 후기 한 건. GET에서 없으면 null입니다. POST 성공 시에는 객체입니다. |
| review.id | UUID string | 후기 ID입니다. |
| review.cohortId | UUID string | null | 과거 회차 연결 정보입니다. 새 강의 후기는 null입니다. |
| review.lectureId | integer | 강의 ID입니다. |
| review.rating | integer | 1~5 별점입니다. |
| review.reflection / application | string | 배운 점 / 업무 적용 내용입니다. |
| review.displayMode | string | 후기 작성자 표시 방식입니다. API 생성 시 anonymous입니다. |
| review.publicConsent | boolean | 본인의 공개 동의 여부입니다. API 생성 시 false입니다. |
| review.status | string | 후기 승인 상태입니다. API 생성 시 pending입니다. |
| review.createdAt / updatedAt | ISO 8601 string / string | null | 생성 / 수정 시각입니다. |
- 회차 신청은 필요하지 않습니다. 같은 강의에 이미 후기가 있으면 409입니다. 이 API는 기존 후기를 덮어쓰지 않습니다.
- anonymous / publicConsent: false / pending으로 생성됩니다. 웹에서 본인이 공개에 동의하고 운영자가 승인한 뒤 공개됩니다.
- 본문은 UTF-8 기준 최대 32KiB입니다. 정의하지 않은 필드를 추가하면 400입니다.
다른 공개 API
아래 요청도 로그인·API 키 없이 사용할 수 있어요. 인증된 강의 자료나 개인 정보는 반환하지 않아요.
GET /api/public/wiki/{slug}공개 용어 설명을 받아요. 예: API 용어. 성공 시 {term: {slug, title, shortDefinition, plainSummary, category, relatedSlugs}}, 용어가 없으면 404예요.
GET /api/public/live-sessions진행 중인 공개 강의의 라이브 세션을 받아요. {sessions: [{code, lectureSlug, lectureTitle, artifactTitle, startedAt}]}이며 없으면 빈 목록이에요.
GET /api/health서비스 응답 상태를 확인해요. {status: "ok", timestamp: "ISO 시각"}을 받아요. 데이터베이스 전체 상태를 검사하는 요청은 아니에요.
이 문서는 외부 연동용 REST API를 다뤄요. AI 작업대의 MCP 연결은 MCP 연결 화면에서 설정할 수 있어요.