AI 에이전트용 API 가이드

기준 URL 및 요청 형식

요청은 https://seohabit.com/api/v1을 사용합니다. JSON 본문은 Content-Type: application/json로 전송하세요. 웹사이트 프로젝트와 자동 제출 진행 상황을 확인하려면 인증이 필요합니다. 요청 빈도는 제한됩니다.

제3자 제출 추적

허용된 디렉터리 정보를 포함한 프로젝트를 생성하여, 자동 제출을 가능하게 합니다. UTC 기준 하루에 최대 2회 시도하며, 5개의 인식된 디렉터리 이후 중단됩니다. SEOHabit은 배경에서 적합한 디렉터리를 선택합니다. 사용자는 디렉터리 목록을 브라우징하거나 선택하지 않습니다. 적합한 제공자가 없을 경우 프로젝트는 대기합니다. 인식은 출판이나 검증된 백링크가 아닙니다.

작업 상태 조회

상태 URL을 확인하여 작업이 completed 또는 failed에 도달할 때까지 반복합니다. 각 확인 요청에는 작업의 접근 토큰을 헤더에 함께 인증해야 합니다. 작업 토큰은 해당 작업만에 대한 접근을 제공합니다.

curl 'https://seohabit.com/api/v1/jobs/job_example' \
  -H 'X-Access-Token: YOUR_JOB_ACCESS_TOKEN'

응답에는 queued, running, completed, 또는 failed가 포함되며, result는 아직 제공되지 않습니다.

계정, 프로젝트 키, 결제 기능

계정 등록 및 로그인 시 HttpOnly sh_session 쿠키를 설정합니다. 브라우저 쿠키 작성은 출처를 확인합니다. 통합 기능에서는 로그인된 계정이 프로젝트 범위의 API 키를 생성하고 명시적인 범위를 설정하여 Authorization: Bearer shk_…으로 전송할 수 있습니다. 키는 다른 프로젝트에 접근할 수 없으며, 키 범위는 제공할 수 있는 작업을 제한합니다. 세션 쿠키와 API 키는 비밀로 유지되어야 하며, URL에 포함해서는 절대 사용하지 마십시오.

키워드 작업은 details.keyword을 수용하며, 선택적으로 details.language (기본값 en)과 선택적으로 명시적인 details.pageUrl을 수용합니다. 제안은 일치하는 페이지 증거를 제공하고 언어나 검색 수요가 불확실할 경우 이를 표시합니다.

무료 프로젝트에서는 무료 제한 내에서 작업을 대기할 수 있습니다. 모니터링된 백링크, 작업 생성, 작업 실행은 확인된 웹사이트와 활성 구독이 필요합니다. 결제된 작업은 사용자가 소유권을 확립하고 계정 결제 흐름을 통해 명시적으로 구독을 획득해야 합니다. 다른 사람을 대신해 체크아웃, 구독, 또는 웹사이트 변경을 시작하거나 승인하지 마십시오. 작업 실행은 변경이 적용되었음을 증명하지 않습니다. 작업이 준비되었을 경우 사용자가 검토 및 수락을 해야 합니다.

프로젝트 키는 project:read, project:write, checks:write, tasks:write을 지원합니다. 키는 해당 프로젝트에만 적용됩니다. 경로와 요청 형식은 OpenAPI 문서를 참고하세요.

오류 및 안전 사용

오류는 error 및 message를 포함한 JSON 형식으로 제공됩니다. 일반적인 응답으로는 400이 잘못된 입력 또는 안전하지 않은 URL에 해당하고, 401은 계정 인증 누락, 403은 허용되지 않은 출처 또는 범위, 404은 사용할 수 없는 자원, 409은 충돌, 429은 레이트리밋, 402은 결제된 작업이 활성 구독이 필요할 때 발생합니다.

공인된 페이지만 점검할 수 있습니다. 서비스는 개인 및 로컬 네트워크 목적지에 대해 차단하며, 원본 사이트의 크롤링 정책이 제공될 경우 그에 따라 적용합니다. 리트리able POST 요청에는 동일성 키를 사용하고, 레이트리밋 응답은 백오프를 통해 처리합니다.