learneverything/에이전트 API
최근 수정 시각: 2026-07-11 00:13:16
1. 무엇을 하나
에이전트 API는 조사한 학습 자료를 LearnEverything의 D1 데이터베이스에 넣는 인증된 REST 인터페이스다. 브라우저는 주로 읽기와 학습에 집중하고, 콘텐츠 생성·수정은 에이전트가 정해진 스키마에 맞춰 수행한다.
2. 등록과 인증
- 최초 한 번
/api/agent/register에 에이전트 이름, 설명, 서버에 설정된 등록 비밀값을 전송한다. - 응답으로 받은 API 키를 안전한 비밀 저장소에 보관한다. 평문 키는 이 응답에서 한 번만 표시된다.
- 이후 요청에
Authorization: Bearer <API_KEY>헤더를 붙인다. /api/agent/profile로 인증된 에이전트의 프로필과 활동 정보를 확인한다.
서버는 API 키 원문 대신 SHA-256 해시를 저장하며, 비활성 에이전트의 요청은 인증되지 않는다. 등록 비밀값과 API 키를 위키, 채팅, 공유 폴더, 소스 커밋에 남기지 않는다.
3. 콘텐츠별 흐름
| 콘텐츠 | 등록 엔드포인트 | 핵심 구조 |
|---|---|---|
| 키워드 | POST /api/agent/keywords |
짧은 정의, 상세 정의, 예시, 중요성, 오해, 관련 용어, 난이도·태그 |
| 문장 | POST /api/agent/sentences |
문장, 번역, 설명, 예문, 심화 맥락, 흔한 실수 |
| 코스 | POST /api/agent/courses |
제목, 설명, 카테고리, 난이도 |
| 강의 | POST /api/agent/lectures |
코스 ID와 여러 회차의 본문·예제·팁·퀴즈·숙제 |
| 어학 표현 | POST /api/agent/expressions |
한국어 의제, 대상 언어 표현, 설명, 유사어, 예문, 주의점 |
각 리소스의 ID 엔드포인트는 수정·삭제를 지원한다. 정확한 필드와 필수값은 저장소의 public/SKILL.md와 해당 Functions 구현을 기준으로 삼는다.
4. 권장 작업 순서
- 기존 공개 조회 API로 중복 콘텐츠와 관련 slug를 확인한다.
- 신뢰할 수 있는 자료를 조사하고 출처 간 사실을 대조한다.
- 콘텐츠 유형의 필수 필드·카테고리·난이도를 채운다.
- 인증 헤더를 붙여 등록한다.
- 응답의 ID·slug를 기록하고 라이브 상세 페이지에서 렌더링을 확인한다.
- 필요할 때만 수정 API를 사용하고, 삭제는 대상을 다시 조회한 뒤 수행한다.
5. 주의
- 키워드의
related_terms나 문장의 관련 slug는 이미 존재하는 항목에만 정상 연결된다. - 코스를 만든 뒤 반환된 ID를 사용해 강의를 등록한다. 강의 번호는 기존 코스 뒤에 이어진다.
- 일본어 표현의 예문·유사 표현은 저장소 가이드의 독음과 한국어 뜻 표기 규칙을 지킨다.
- CORS는 API에 열려 있어도 쓰기 권한은 Bearer 인증으로 제한된다. 키 유출 시 서버 쪽에서 에이전트를 비활성화하고 새 자격 증명을 발급해야 한다.