API 참조

모니터와 채널을 관리하고 변경 사항을 폴링하기 위한 작고 안정적인 REST API입니다. 대시보드와 동일한 기능을 지원합니다.

기본 URL

프로덕션: https://api.pagedeltas.com. 모든 엔드포인트는 /api 접두사가 붙습니다. 성공적인 응답은 JSON입니다.

인증

설정 → API 키에서 키를 생성하세요 (편집자 또는 관리자 역할 필요). 키는 생성 시 한 번만 표시되므로 즉시 복사하세요. 키를 취소하려면 같은 페이지에서 삭제하세요.

Authorization: Bearer pdt_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

키는 생성된 조직으로 범위가 지정되며 해당 조직 내에서 관리자 수준 액세스로 작동하며 특정 사용자에게 종속되지 않습니다. 팀원을 삭제해도 조직의 키가 취소되지 않으므로 액세스를 차단하려면 키 자체를 삭제하세요.

오류

오류는 2xx가 아닌 상태를 반환합니다. 인증 및 권한 오류는 짧은 일반 텍스트 메시지(예: unauthorized, forbidden)로 반환됩니다. 할당량 및 속도 제한 오류는 메시지와 관련 숫자가 포함된 작은 JSON 본문을 반환합니다. 고정된 오류 봉투를 구문 분석하지 말고 HTTP 상태 코드에 따라 분기하세요:

400 — 잘못된 요청 (잘못된 JSON, 유효하지 않은 URL, 누락된 필드).
401 — 누락되거나 유효하지 않은 자격 증명.
403 — 인증되었지만 역할에 이 작업에 대한 권한이 없습니다.
404 — 리소스가 없거나 조직에 없습니다.
409 — 충돌 (예: 반복된 차단으로 인해 모니터가 일시 중지됨).
422 — 할당량 초과 (예: 요금제의 모니터 한도). JSON 본문에 current 및 limit가 포함됩니다.
429 — 속도 제한 (수동 확인). Retry-After의 지연 시간 후에 재시도하세요.

할당량 오류 예시 (422):

{
  "error": "plan_url_limit exceeded",
  "current": 100,
  "limit": 100,
  "message": "Creating this monitor would exceed your plan's monitor limit (100)."
}

엔드포인트 참조

메서드 & 경로	설명
`GET /api/monitors`	조직의 모니터를 나열합니다.
`POST /api/monitors`	단일 모니터를 생성합니다.
`GET /api/monitors/{id}`	단일 모니터를 가져옵니다.
`PATCH /api/monitors/{id}`	`url`, `nl_description`, `filter_prompt`, `css_selector`, `xpath_selector`, `status`를 업데이트합니다.
`DELETE /api/monitors/{id}`	모니터와 그 기록을 삭제합니다.
`POST /api/monitors/{id}/check-now`	일정을 우회하여 즉시 확인을 대기열에 추가합니다 (속도 제한, 아래 참조).
`GET /api/monitors/{id}/changes`	모니터에 감지된 변경 사항을 나열합니다 (`?limit=` 지원, 최대 100).
`POST /api/monitors/import`	멀티파트 CSV 업로드를 통해 대량 가져오기 (`file` 필드).
`POST /api/monitors/bulk-pause`, `bulk-resume`, `bulk-delete`	모니터 ID 목록에 작업을 적용합니다.
`GET\|PUT /api/monitors/{id}/alert-channels`	모니터의 채널 재정의를 읽거나 교체합니다.
`GET /api/alert-channels`	알림 채널을 나열합니다.
`POST /api/alert-channels`	채널을 생성합니다.
`PATCH\|DELETE /api/alert-channels/{id}`	채널을 업데이트하거나 삭제합니다.
`POST /api/alert-channels/{id}/test`	전달을 확인하기 위해 테스트 페이로드를 보냅니다.
`GET\|POST /api/sitemap-monitors`	사이트맵 모니터를 나열하거나 생성합니다.
`POST /api/sitemap-monitors/import`	멀티파트 CSV 업로드를 통해 대량 생성 (`file` 필드).
`GET\|POST\|DELETE /api/tokens`	API 키를 나열, 생성 및 삭제합니다.
`GET /api/billing/plan`	조직의 현재 요금제와 한도를 가져옵니다.
`GET /api/plans`	공개 — 사용 가능한 요금제를 나열합니다 (인증 불필요).

예제 — 모니터 생성

curl -X POST https://api.pagedeltas.com/api/monitors \
  -H "Authorization: Bearer $PAGEDELTAS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/pricing",
    "nl_description": "Competitor pricing; alert on plan or price changes",
    "filter_prompt": "Alert on plan or price changes; ignore copy tweaks",
    "channel_ids": []
  }'

선택적 필드: filter_prompt, css_selector, xpath_selector, is_pdf, channel_ids (조직 기본값을 사용하려면 생략). frequency는 없습니다 — 일정은 적응형으로 예약됩니다.

예제 — 변경 사항 폴링

GET /api/monitors/01HW2X.../changes?limit=50
Authorization: Bearer $PAGEDELTAS_TOKEN

최신 변경 사항을 먼저 반환합니다 (기본 50, 최대 100). 커서는 없으므로 limit를 조정하고 이미 본 가장 최근의 detected_at을 추적하여 페이징하세요.

{
  "changes": [
    {
      "id": "01HW3...",
      "detected_at": "2026-06-01T08:42:00Z",
      "summary": "Pro plan increased from $29 to $39/month."
    }
  ]
}

속도 제한

현재 읽기 및 쓰기 엔드포인트에는 키별 속도 제한이 없습니다. 유일한 예외는 수동 확인입니다:

지금 확인: 모니터당 1분에 1개 요청.

해당 한도에 도달하면 응답은 429가 되며 초 단위의 Retry-After 헤더가 포함됩니다. 다른 엔드포인트에서도 속도를 조절해 주시기 바랍니다.

버전 관리

우리는 이 API의 안정성을 유지하고자 합니다. 예고 없이 새 필드와 엔드포인트가 추가될 수 있으므로 알 수 없는 JSON 필드를 무시하는 클라이언트를 작성하세요.