공개 상태와 데이터 경로
기본 주소는 https://api.redditgateway.com 입니다. GET /v1/status는 키 없이 무료로 호출합니다. 고정된 서비스 범위와 HTTP 애플리케이션의 응답을 보여 줍니다. 아카이브 소스, 검색 동작, 기록의 존재나 잔액은 검사하지 않습니다. 검색 검사 기능으로 표시하지 마세요. 그다음 보내는 데이터 요청은 자체 인증, 한도와 오류 처리 조건을 따르므로 별도로 상태와 내용을 평가해야 합니다.
GET /v1/search는 게시물과 댓글 검색, /v1/posts는 게시물, /v1/comments는 댓글 조회입니다. GET /v1/item?id=...는 단일 기록의 식별자를 받습니다. id는 item 전용이며 posts나 comments의 필터가 아닙니다. GET /v1/subreddits?prefix=...는 커뮤니티 이름의 시작 부분으로 조회하고 limit으로 요청 수를 정할 수 있습니다. 커뮤니티 집계 건수가 아카이브 전체에서 정확하다는 보장은 없습니다.
보호된 조회는 Authorization: Bearer YOUR_API_KEY와 X-API-Key: YOUR_API_KEY를 모두 지원합니다. 하나를 선택하고 실제 키는 서버에서만 보내세요. 계정 패널의 Secure HttpOnly 쿠키는 다른 세션을 관리하며 API 키 헤더를 대신하지 않습니다. 계정, 키와 잔액은 이 도메인 전용입니다. URL 매개변수나 브라우저 코드 대신 서버의 비밀 설정을 사용하세요. 공개 status는 이 키의 유효성도 검사하지 않습니다.
조건, 페이지와 결과의 한계
검색, 게시물과 댓글에는 q, subreddit, author, kind, from, to, min_score, limit, page를 사용할 수 있습니다. kind 값은 post 또는 comment입니다. 날짜는 UTC 기준 YYYY-MM-DD 형식이며 to 날짜를 포함합니다. min_score는 최소 점수 조건이지 정렬이 아닙니다. parent_id와 link_id는 조회 필터가 아니므로 관계 식별자를 보내 전체 대화를 요청하는 기능을 만들 수 있다고 생각하지 마세요.
limit은 1~100, page는 1~100입니다. 한 요청은 최대 100개 기록, 한 쿼리는 최대 100페이지이며 각 페이지는 따로 요청합니다. 결과는 아카이브 문서 순서로 시간, 관련도나 점수 순서가 아닙니다. 페이지 반복과 날짜 구간 분할은 전체 수집이나 중복 없는 결과를 보장하지 않습니다. 어떤 조건과 페이지를 저장했는지 자체 작업 기록으로 추적해 실제 받은 범위를 설명하세요.
전체 건수에서 eq는 정확한 수, gte는 하한, unknown이나 null은 신뢰할 수 있는 합계가 없음을 뜻합니다. 합계는 페이지 수가 아니고 정확한 값도 클라이언트가 모든 기록을 저장했다는 증거는 아닙니다. 응답은 평면 기록입니다. 읽거나 개수를 셀 때는 트리가 필요 없으며 관계를 조사할 때만 존재하는 parent_id나 link_id로 선택적 로컬 그룹화를 할 수 있습니다. 빠진 부모나 댓글은 복원되지 않습니다.
오류와 키 관리
HTTP 400은 조건의 형식이나 값, HTTP 401은 키 누락 또는 무효, HTTP 402는 잔액 부족, HTTP 429는 요청 속도 제한을 뜻합니다. 429는 연결 시간 초과가 아닙니다. 조건과 키 오류는 수정하고 속도 제한에서는 송신을 늦추세요. 성공한 조회는 빈 결과도 한 크레딧입니다. 잘못된 요청은 차감하지 않고 상위 소스 장애에서는 예약한 크레딧을 돌려줍니다.
클라이언트의 연결 실패는 서버에서 유료 성공이 발생하지 않았다는 증거는 아닙니다. 성공한 재시도는 추가 비용입니다. 네트워크 실패와 HTTP 응답을 구분하며 비밀 헤더 없이 저장된 작업을 추적하세요. 키는 가입할 때 결제 전에 한 번 표시됩니다. 로그인한 사용자는 비밀번호 확인 후 재발급할 수 있고 이전 키는 즉시 무효가 됩니다. 이메일 키 전달과 비밀번호 초기화 기능은 없습니다. 새 키를 쓰도록 앱 설정도 갱신해야 합니다.
