명언 API 사용 안내

버전이 명시된 JSON API와 고정 데이터셋을 제공합니다.

빠른 시작

개발자 작업 공간에서 무료 조직과 소비 앱을 등록한 뒤 API 키를 발급하세요. 키 전체는 발급 응답에 한 번만 표시됩니다. 서버의 비밀 저장소에 보관하고 URL·공개 코드·로그에 넣지 마세요.

curl "$MERA_QUOTES_ORIGIN/api/v1/quotes?limit=12" \
  -H "Authorization: Bearer $MERA_QUOTES_API_KEY"

현재 공급은 권리·출처가 확인된 소량의 영어 원문입니다. 문장별 권리 지역과 허락 범위를 준수해야 하며, 유료 요금제만으로 제3자 권리가 확대되지는 않습니다.

실시간 조회

GET 경로	용도
/api/v1/quotes	페이지별 문장
/api/v1/quotes/:id	문장·출처·권리 상세
/api/v1/quotes/random	랜덤 한 문장
/api/v1/quotes/today	UTC 기준 오늘의 문장

목록 필터: q, category, language, kind(historical/original), length(short/medium/long), page, limit. 문장 길이는 공백·문장부호 포함 50자 이하·51~100자·101자 이상입니다. 원저작자(author)와 번역자(translation_author), 원문·언어, 라이선스·허락 범위를 구분합니다. 화면 공개 여부와 상품별 공급 권한은 별도로 검증합니다.

{
  "data": [
    {
      "id": "…",
      "text": "…",
      "author": "…",
      "kind": "historical",
      "source_title": "…",
      "source_locator": "…",
      "rights_license": "public_domain",
      "rights_territory": "KR,US",
      "revision": "1"
    }
  ],
  "total": 6,
  "page": 1,
  "limit": 12
}

위 JSON은 응답 구조 예시이며 실제 콘텐츠 수는 API 응답을 기준으로 합니다.

변경분·철회 동기화

GET /api/v1/changes?cursor=0&limit=100
GET /api/v1/revocations?cursor=0&limit=100

처음 cursor=0으로 요청하고 응답의 next_cursor를 체크포인트로 보관하세요.
upsert는 해당 revision의 최신 문장을 반영하고 delete는 로컬·캐시·검색 인덱스에서 제거하세요.
페이지를 모두 반영한 뒤에만 cursor를 저장하세요. 중복 수신도 안전하게 적용해야 합니다.
스냅샷 사용 전/최소 매일 철회 목록을 확인하세요. 유효한 키의 철회 조회는 무과금이며 실시간 구독 종료 후에도 가능합니다.

별도 라이선스의 스냅샷

GET /api/v1/exports/manifest
GET /api/v1/exports/:version
Authorization: Bearer $MERA_QUOTES_API_KEY

snapshot 이용권이 별도로 필요합니다. 실시간 상품이나 무료 API 키만으로 다운로드할 수 없습니다. manifest의 SHA256과 다운로드 응답의 X-Checksum-SHA256을 검증하고, 버전·권리 범위·철회 cursor를 기록하세요. 라이선스는 주문에 고정한 버전과 조직·앱 범위에 적용됩니다.

파일은 고정 버전입니다. 새 버전은 자동 구매되지 않으며 철회가 반영된 대체 파일의 제공 범위는 상품 약정에 따릅니다. 철회·권리 만료 문장이 있는 구버전은 다시 공급하지 않습니다.

쿼터·오류 처리

성공한 콘텐츠 응답만 조직 단위로 합산합니다. 한도는 X-Quota-Limit, X-Quota-Remaining, X-Quota-Period 응답 헤더에서 확인하세요. 앱별 월 사용량을 집계하며 키 교체로 한도를 우회할 수 없습니다.

개발자 작업 공간에서 조직별 쿼터 현황, 최근 30일의 요청 로그와 키 발급·철회 감사 이력을 확인하세요. 키별 월 집계는 제공하지 않습니다.

조직별 쿼터 현황 API 요청 로그 키 발급·철회 감사 이력

상태	앱에서 할 일
401	키 누락·철회 확인. 재발급 전 호출 중단.
402 / 403	현재 상품·조직·다운로드 권한 확인.
404 / 410	철회·변경분 확인 후 로컬 표시 제거.
429	호출 중단, 재시도 안내 시간과 기간 한도 확인. 자동 초과 결제 없음.
5xx	지수 백오프로 제한 재시도. 성공으로 저장하지 않음.

{"error":{"code":"quota_exceeded","message":"…"},"requestId":"…"}

오류 전문·요청 ID는 문의에 사용할 수 있지만 키·쿠키·비밀번호를 함께 보내지 마세요.

화면 설정