경로와 키 인증
조회 호스트는 https://api.redditextract.com 입니다. GET /v1/search는 일반 검색, /v1/posts는 게시물, /v1/comments는 댓글, /v1/item?id=...는 알려진 한 항목에 사용합니다. /v1/subreddits는 prefix와 limit으로 커뮤니티 이름을 찾으며 내용 검색 필터나 page를 받지 않습니다. /v1/status는 정적인 서비스 범위 설명입니다. 각 경로에 허용된 인수만 보내고 응답 필드를 검색 인수라고 가정하지 마세요.
Authorization: Bearer YOUR_API_KEY와 X-API-Key: YOUR_API_KEY 중 하나를 사용합니다. 두 형식 모두 이 도메인의 아카이브 키를 쓰며 Reddit OAuth 토큰이 아닙니다. 계정, 키와 잔액은 다른 브랜드와 공유되지 않습니다. 계정 패널의 Secure HttpOnly 세션 쿠키는 조회 인증과 별도입니다. 키 값을 서버 설정에서 관리하고 공개 예제나 변환 결과 파일에는 실제 값을 넣지 마세요.
id는 /v1/item에서 필요하며 게시물과 댓글 목록의 선택적 필터도 아닙니다. 알려진 한 레코드를 다시 확인할 때와 여러 레코드를 검색할 때는 경로 선택이 다릅니다. API는 플랫 레코드를 반환하고 대화 트리를 조립하지 않습니다. parent_id와 link_id가 있으면 로컬 관계 분석에 활용할 수 있지만 없는 부모를 찾아내거나 대화의 완전성을 보장하지 않습니다.
필터와 페이지 해석
내용 조회에서 q, subreddit, author, kind, from, to, min_score, limit과 page를 사용할 수 있습니다. kind는 post 또는 comment입니다. 날짜는 UTC의 YYYY-MM-DD이고 to는 마지막 날 전체를 포함합니다. min_score는 점수 하한 조건이지 정렬 제어가 아닙니다. parent_id와 link_id는 쿼리 필터가 아닙니다. 지원되지 않는 열 이름이나 임의의 질의 문법을 서버에 보내지 마세요. from과 to는 콘텐츠 생성 시각인 created_utc를 필터링하며, 데이터를 가져온 시각이나 아카이브에 적재한 시각을 기준으로 하지 않습니다.
limit과 page는 각각 1부터 100까지입니다. _doc 문서 순서는 시간, 관련도 또는 점수에 따른 순서가 아닙니다. 총계 관계가 eq이면 정확한 수, gte이면 하한, unknown이면 신뢰할 총계를 알 수 없으며 값이 null일 수도 있습니다. 하한을 확정 숫자로 바꾸거나 총계를 저장된 행 수와 같다고 보지 마세요. 날짜 분할과 페이지 반복도 전체 수집을 보장하지 않습니다.
예제 https://api.redditextract.com/v1/search?q=index&subreddit=PostgreSQL&limit=3 으로 받은 레코드마다 실제 필드와 자료형을 비교하세요. 어떤 필드를 출력 열로 옮길지, 없는 값과 null을 어떻게 처리할지 정하는 일은 여러분의 코드에 속합니다. 서버가 같은 모양의 완성된 출력 파일을 제공하는 것은 아닙니다. 변환 중 거절한 값과 원래 응답 건수를 따로 적으면 차이를 설명하기 쉽습니다. 필드 선택은 응답을 받은 뒤 로컬에서 수행합니다. 문서에 없는 fields 매개변수를 추가해 서버에 전용 출력 스키마를 요청하지 마세요.
실패와 로컬 작업 구분
400은 잘못된 요청, 401은 키 누락 또는 무효, 402는 잔액 부족, 429는 요청 빈도 제한입니다. 유효하지 않은 요청은 차감되지 않고 상위 시스템 실패의 예약분은 반환됩니다. 성공한 빈 결과는 한 크레딧입니다. /v1/status는 검색 저장소의 상태나 키 유효성을 검사하지 않습니다. 재시도 전에 어느 단계에서 실패했는지 구분하고 다른 계정으로 제한을 우회하지 마세요.
클라이언트가 응답을 잃어도 서버는 성공했을 수 있고 성공한 재시도는 추가 비용입니다. 반면 저장한 응답에 새 매핑 규칙을 적용하는 일은 새 API 요청이 아닙니다. 조회 조건, 원본 응답, 변환 버전과 출력 결과를 분리해 기록하세요. 이 기록은 로컬 처리 과정을 설명하지만 서버가 나중에도 같은 자료를 반환한다는 약속은 만들지 않습니다.
