인증
워크스페이스 API 키를 사용합니다.
발급 시 한 번만 표시되는 oslr_ API 키를 X-API-Key에 전송합니다. URL, 브라우저 스크립트, 공개 저장소, 지원 메일에 API 키를 넣지 마세요.
AI READER API 가이드
공개 HTTPS 콘텐츠를 동기식으로 읽거나 요약하고, Direct 비동기 작업을 제출해 서명된 완료 웹훅을 받을 수 있습니다. LLM, RAG, 에이전트 워크플로에 안정적인 입력을 만드세요.
인증
발급 시 한 번만 표시되는 oslr_ API 키를 X-API-Key에 전송합니다. URL, 브라우저 스크립트, 공개 저장소, 지원 메일에 API 키를 넣지 마세요.
크레딧 사용
Reader와 Document는 성공 시 1크레딧, Summary는 5크레딧입니다. 비동기 작업도 제출 시 같은 크레딧을 예약하고 최종 결과 정산이 끝날 때만 확정합니다. 부분 결과, 실패, 취소, 게이트웨이 거부는 0크레딧입니다.
요청 추적
X-Request-Id요청 준비가 끝난 Direct 응답에는 불투명한 X-Request-Id가 포함됩니다. 해당 작업의 지원 문의에 이 값을 보내세요. 인증 또는 요청 수신 단계의 조기 거부에는 없을 수 있습니다.
POST 재시도
Idempotency-Key는 네트워크 타임아웃이나 클라이언트 연결 종료로 결과를 알 수 없을 때 게이트웨이가 같은 논리적 POST 작업을 인식하게 합니다. 동기식 POST에서는 선택 사항이고 모든 비동기 제출에서는 필수입니다.
Idempotency-Key POST 예시에 표시된 값은 새 값으로 바꿔 사용하세요. 실제 요청에서 예시 값을 그대로 재사용하면 안 됩니다.
빠르게 경험하기
OngsooLabs가 직접 작성한 정적 HTML 입력으로 Direct API의 요청과 응답 형식을 빠르게 확인할 수 있습니다. 실제 호출을 실행하는 도구가 아니라 응답 형식을 확인하기 위한 참고 예시입니다.
POST /api/v1/readerX-API-Key: oslr_your_api_keymarkdownPOST /api/v1/reader
X-API-Key: oslr_your_api_key
Idempotency-Key: <new UUID or ULID for this POST>
Content-Type: application/json
{
"url": "https://ongsoolabs.com/examples/reader/owned-controlled-reader-source.html",
"mode": "generic",
"output_format": "markdown",
"enable_chunking": false
}
X-Request-Id: dgr_example_request_id
{
"status": "success",
"title": "OngsooLabs controlled Reader source",
"content": {
"format": "markdown",
"value": "# OngsooLabs controlled Reader source\n\nThis page is an owned, controlled input..."
},
"usage": { "credits": 1 }
}
원본 페이지와 정제된 계약 예시는 모두 OngsooLabs가 관리합니다.
OngsooLabs Direct는 현재 공개되어 있습니다. 로그인 후 Direct API 키를 만들고 대시보드에서 크레딧과 결제를 관리할 수 있습니다. 이 정적 예시는 실제 API 호출을 실행하지 않습니다.
/api/v1/reader
URL 매개변수로 공개 HTTPS 웹페이지 하나에서 본문, 메타데이터, 선택적 청크를 추출합니다.
적합한 경우: JSON 본문 없이 URL만으로 연동하거나 간단한 진단 요청이 필요할 때 적합합니다.
https://ongsoolabs.com| 파라미터 | 필수 여부 | 기본값 | 설명 |
|---|---|---|---|
url |
필수 | - |
공개 HTTPS 웹페이지 URL입니다. |
output_format |
선택 | markdown |
markdown, text 또는 json 출력 형식입니다. |
tokenizer |
선택 | openai |
token 추정기: openai, claude, gemini 또는 llama입니다. |
enable_chunking |
선택 | false |
Reader 또는 Document 응답에 중첩 chunk를 포함합니다. |
chunk_size_tokens |
선택 | 500 |
token 기반 chunk 하나의 목표 token 수입니다. |
overlap_size_tokens |
선택 | 100 |
인접 chunk 간 token overlap이며 chunk 크기보다 작아야 합니다. |
force_dynamic |
선택 | false |
client-side 렌더링이 필요한 페이지에 브라우저 렌더링을 요청하며 접근 통제를 우회하지 않습니다. |
mode |
선택 | generic |
추출 모드: generic, article, documentation, product 또는 forum입니다. |
output_content |
선택 | true |
응답의 content, metadata, table, code block, image, link 포함 여부를 제어합니다. |
output_metadata |
선택 | true |
응답의 content, metadata, table, code block, image, link 포함 여부를 제어합니다. |
output_tables |
선택 | true |
응답의 content, metadata, table, code block, image, link 포함 여부를 제어합니다. |
output_code_blocks |
선택 | true |
응답의 content, metadata, table, code block, image, link 포함 여부를 제어합니다. |
output_images |
선택 | false |
응답의 content, metadata, table, code block, image, link 포함 여부를 제어합니다. |
output_links |
선택 | false |
응답의 content, metadata, table, code block, image, link 포함 여부를 제어합니다. |
disable_css |
선택 | null |
선택적 렌더링 힌트입니다. 확인된 렌더링 문제를 검증할 때만 설정하세요. |
curl --request GET \
--url "https://ongsoolabs.com/api/v1/reader?url=https%3A%2F%2Fongsoolabs.com%2Fexamples%2Freader%2Fowned-controlled-reader-source.html&output_format=markdown&mode=article" \
--header "X-API-Key: oslr_your_api_key"$headers = @{
"X-API-Key" = "oslr_your_api_key"
}
Invoke-RestMethod -Method GET `
-Uri "https://ongsoolabs.com/api/v1/reader?url=https%3A%2F%2Fongsoolabs.com%2Fexamples%2Freader%2Fowned-controlled-reader-source.html&output_format=markdown&mode=article" `
-Headers $headers{
"id": "read_example",
"status": "success",
"contentType": "webpage",
"title": "OngsooLabs Reader controlled source",
"content": {
"format": "markdown",
"value": "# Controlled Reader source\n\nThis page is maintained by OngsooLabs for Reader contract verification."
},
"usage": {
"characters": 92,
"tokens": 18,
"chunks": 0,
"credits": 1
}
}{
"id": "read_example",
"status": "partial",
"error": {
"code": "PARTIAL_CONTENT",
"message": "The extracted main content did not meet the quality gate.",
"retryable": true,
"recommendedProfile": "standard"
},
"usage": {
"characters": 0,
"tokens": 0,
"chunks": 0,
"credits": 0
}
}이 예시는 승인된 API 명세를 기준으로 작성되었습니다.
/api/v1/reader
공개 HTTPS 웹페이지 하나를 읽어 Markdown, 텍스트 또는 구조화된 JSON으로 반환합니다. 출력 형식과 청크 옵션을 지정할 수 있습니다.
적합한 경우: 반복 가능한 RAG 수집, 메타데이터 관리, 동적 렌더링 재시도 또는 응답 내 청크가 필요할 때 적합합니다.
https://ongsoolabs.com| 파라미터 | 필수 여부 | 기본값 | 설명 |
|---|---|---|---|
url |
필수 | - |
공개 HTTPS 웹페이지 URL입니다. |
output_format |
선택 | markdown |
markdown, text 또는 json 출력 형식입니다. |
tokenizer |
선택 | openai |
token 추정기: openai, claude, gemini 또는 llama입니다. |
enable_chunking |
선택 | false |
Reader 또는 Document 응답에 중첩 chunk를 포함합니다. |
chunk_size_tokens |
선택 | 500 |
token 기반 chunk 하나의 목표 token 수입니다. |
overlap_size_tokens |
선택 | 100 |
인접 chunk 간 token overlap이며 chunk 크기보다 작아야 합니다. |
force_dynamic |
선택 | false |
client-side 렌더링이 필요한 페이지에 브라우저 렌더링을 요청하며 접근 통제를 우회하지 않습니다. |
mode |
선택 | generic |
추출 모드: generic, article, documentation, product 또는 forum입니다. |
output |
선택 | object defaults |
응답의 content, metadata, table, code block, image, link 포함 여부를 제어합니다. |
disable_css |
선택 | null |
선택적 렌더링 힌트입니다. 확인된 렌더링 문제를 검증할 때만 설정하세요. |
curl --request POST \
--url "https://ongsoolabs.com/api/v1/reader" \
--header "X-API-Key: oslr_your_api_key" \
--header "Idempotency-Key: 00000000-0000-4000-8000-000000000000" \
--header "Content-Type: application/json" \
--data '{
"url": "https://ongsoolabs.com/examples/reader/owned-controlled-reader-source.html",
"output_format": "markdown",
"tokenizer": "openai",
"enable_chunking": false,
"force_dynamic": false,
"mode": "article"
}'$headers = @{
"X-API-Key" = "oslr_your_api_key"
"Idempotency-Key" = "00000000-0000-4000-8000-000000000000"
}
$body = @'
{
"url": "https://ongsoolabs.com/examples/reader/owned-controlled-reader-source.html",
"output_format": "markdown",
"tokenizer": "openai",
"enable_chunking": false,
"force_dynamic": false,
"mode": "article"
}
'@
Invoke-RestMethod -Method POST `
-Uri "https://ongsoolabs.com/api/v1/reader" `
-Headers $headers `
-ContentType "application/json" `
-Body $body{
"url": "https://ongsoolabs.com/examples/reader/owned-controlled-reader-source.html",
"output_format": "markdown",
"tokenizer": "openai",
"enable_chunking": false,
"force_dynamic": false,
"mode": "article"
}{
"id": "read_example",
"status": "success",
"contentType": "webpage",
"title": "OngsooLabs Reader controlled source",
"content": {
"format": "markdown",
"value": "# Controlled Reader source\n\nThis page is maintained by OngsooLabs for Reader contract verification."
},
"usage": {
"characters": 92,
"tokens": 18,
"chunks": 0,
"credits": 1
}
}{
"id": "read_example",
"status": "failed",
"error": {
"code": "INVALID_REQUEST",
"message": "The request options are invalid.",
"retryable": false
},
"usage": {
"characters": 0,
"tokens": 0,
"chunks": 0,
"credits": 0
}
}이 예시는 승인된 API 명세를 기준으로 작성되었습니다.
/api/v1/reader/document
공개 HTTPS의 텍스트 레이어 PDF URL에서 본문을 읽어 Markdown으로 반환하고, 필요하면 토큰 계산과 청크 분할을 수행합니다.
적합한 경우: 텍스트를 선택하고 추출할 수 있는 공개 규격서, 보고서 또는 논문의 본문이 필요할 때 적합합니다.
https://ongsoolabs.com| 파라미터 | 필수 여부 | 기본값 | 설명 |
|---|---|---|---|
url |
필수 | - |
추출 가능한 텍스트 레이어가 있는 PDF의 공개 HTTPS URL입니다. |
tokenizer |
선택 | openai |
token 추정기: openai, claude, gemini 또는 llama입니다. |
enable_chunking |
선택 | false |
Reader 또는 Document 응답에 중첩 chunk를 포함합니다. |
chunk_size_tokens |
선택 | 500 |
token 기반 chunk 하나의 목표 token 수입니다. |
overlap_size_tokens |
선택 | 100 |
인접 chunk 간 token overlap이며 chunk 크기보다 작아야 합니다. |
curl --request POST \
--url "https://ongsoolabs.com/api/v1/reader/document" \
--header "X-API-Key: oslr_your_api_key" \
--header "Idempotency-Key: 00000000-0000-4000-8000-000000000000" \
--header "Content-Type: application/json" \
--data '{
"url": "https://ongsoolabs.com/examples/reader/owned-controlled-reader-document.pdf",
"tokenizer": "openai",
"enable_chunking": false
}'$headers = @{
"X-API-Key" = "oslr_your_api_key"
"Idempotency-Key" = "00000000-0000-4000-8000-000000000000"
}
$body = @'
{
"url": "https://ongsoolabs.com/examples/reader/owned-controlled-reader-document.pdf",
"tokenizer": "openai",
"enable_chunking": false
}
'@
Invoke-RestMethod -Method POST `
-Uri "https://ongsoolabs.com/api/v1/reader/document" `
-Headers $headers `
-ContentType "application/json" `
-Body $body{
"url": "https://ongsoolabs.com/examples/reader/owned-controlled-reader-document.pdf",
"tokenizer": "openai",
"enable_chunking": false
}{
"id": "read_document_example",
"status": "success",
"contentType": "document",
"title": "OngsooLabs Reader controlled document",
"content": {
"format": "markdown",
"value": "# OngsooLabs Reader controlled document\n\nThis text-layer PDF is maintained for Reader contract verification."
},
"usage": {
"characters": 105,
"tokens": 19,
"chunks": 0,
"credits": 1
},
"execution": {
"profile": "document",
"usedBrowser": false
}
}{
"id": "read_document_example",
"status": "failed",
"error": {
"code": "DOCUMENT_NO_TEXT_LAYER",
"message": "The PDF does not contain extractable text.",
"retryable": false
},
"usage": {
"characters": 0,
"tokens": 0,
"chunks": 0,
"credits": 0
},
"execution": {
"profile": "document",
"usedBrowser": false
}
}이 예시는 승인된 API 명세를 기준으로 작성되었습니다.
/api/v1/reader/chunk
입력 텍스트를 임베딩·검색 파이프라인에 맞게 토큰 또는 문자 기준의 겹치는 순차 청크로 나눕니다.
적합한 경우: 이미 텍스트 원문을 가지고 있으며 URL을 읽지 않고 일정한 청크 경계가 필요할 때 적합합니다.
https://ongsoolabs.com| 파라미터 | 필수 여부 | 기본값 | 설명 |
|---|---|---|---|
text |
필수 | - |
분할할 원문이며 최대 1,000,000자입니다. |
tokenizer |
선택 | openai |
token 추정기: openai, claude, gemini 또는 llama입니다. |
use_tokens |
선택 | true |
true이면 token 크기, false이면 문자 크기를 사용합니다. |
chunk_size_tokens |
선택 | 500 |
token 기반 chunk 하나의 목표 token 수입니다. |
overlap_size_tokens |
선택 | 100 |
인접 chunk 간 token overlap이며 chunk 크기보다 작아야 합니다. |
chunk_size |
선택 | 1000 |
use_tokens가 false일 때 chunk 하나의 목표 문자 수입니다. |
overlap_size |
선택 | 200 |
use_tokens가 false일 때의 문자 overlap이며 chunk 크기보다 작아야 합니다. |
curl --request POST \
--url "https://ongsoolabs.com/api/v1/reader/chunk" \
--header "X-API-Key: oslr_your_api_key" \
--header "Idempotency-Key: 00000000-0000-4000-8000-000000000000" \
--header "Content-Type: application/json" \
--data '{
"text": "OngsooLabs Reader prepares clean source text for retrieval pipelines. This controlled sample demonstrates overlapping token chunks.",
"tokenizer": "openai",
"use_tokens": true,
"chunk_size_tokens": 32,
"overlap_size_tokens": 8
}'$headers = @{
"X-API-Key" = "oslr_your_api_key"
"Idempotency-Key" = "00000000-0000-4000-8000-000000000000"
}
$body = @'
{
"text": "OngsooLabs Reader prepares clean source text for retrieval pipelines. This controlled sample demonstrates overlapping token chunks.",
"tokenizer": "openai",
"use_tokens": true,
"chunk_size_tokens": 32,
"overlap_size_tokens": 8
}
'@
Invoke-RestMethod -Method POST `
-Uri "https://ongsoolabs.com/api/v1/reader/chunk" `
-Headers $headers `
-ContentType "application/json" `
-Body $body{
"text": "OngsooLabs Reader prepares clean source text for retrieval pipelines. This controlled sample demonstrates overlapping token chunks.",
"tokenizer": "openai",
"use_tokens": true,
"chunk_size_tokens": 32,
"overlap_size_tokens": 8
}[
{
"index": 0,
"start_char": 0,
"end_char": 120,
"token_count": 24,
"content": "OngsooLabs Reader prepares clean source text for retrieval pipelines. This controlled sample demonstrates overlapping token chunks."
}
]{
"id": "read_chunk_example",
"status": "failed",
"error": {
"code": "INVALID_REQUEST",
"message": "Chunk size or overlap is outside the supported boundary.",
"retryable": false
},
"usage": {
"characters": 0,
"tokens": 0,
"chunks": 0,
"credits": 0
}
}이 예시는 승인된 API 명세를 기준으로 작성되었습니다.
/api/v1/summary공개 HTTPS 웹페이지 URL 하나를 제출합니다. quality는 선택이며 현재 standard만 허용합니다.
https://ongsoolabs.com{
"url": "https://example.com/article",
"quality": "standard"
}Idempotency-Key 논리적인 POST 작업마다 고유한 UUID D 형식 또는 ULID를 사용하고, 같은 작업을 재시도할 때만 같은 값을 다시 사용하세요. 다른 요청에 재사용하면 409를 반환합니다.
성공 응답은 title, summary, keywords, sourceType, usage, execution과 버전 정보를 포함한 Summary 객체입니다. 제공업체와 모델 이름은 노출하지 않습니다.
POST /api/v1/{operation}/jobs처음 연결한 HTTP 요청을 계속 열어 두지 않고 작업을 제출합니다. 제출에 성공하면 불투명한 작업 ID와 상태·결과 조회 URL을 담은 202 Accepted 응답을 반환합니다.
적합한 경우: 제출 응답에서 결과를 기다리는 대신 완료될 때까지 조회하거나 완료 웹훅을 받을 수 있을 때 사용합니다.
https://ongsoolabs.com| 메서드 | 엔드포인트 | 설명 |
|---|---|---|
POST | /api/v1/reader/jobs | Reader 요청을 제출하고 작업 ID를 받습니다. |
POST | /api/v1/reader/document/jobs | 공개 텍스트 레이어 PDF Document 요청을 제출하고 작업 ID를 받습니다. |
POST | /api/v1/summary/jobs | Summary 요청을 제출하고 작업 ID를 받습니다. |
GET | /api/v1/jobs/{jobId} | 워크스페이스 소유권이 확인된 작업 상태를 조회합니다. |
GET | /api/v1/jobs/{jobId}/result | Web 정산이 끝난 뒤 표준 결과를 조회합니다. |
DELETE | /api/v1/jobs/{jobId} | 대기 또는 실행 중인 작업의 취소를 요청합니다. |
X-API-Key 는 모든 생명주기 요청에 필수입니다. Idempotency-Key 는 모든 제출 요청에 필수입니다. 정확히 같은 논리 요청을 재시도할 때만 재사용하세요.
| 상태 | 설명 |
|---|---|
created | 지속성 작업을 생성했고 활성화를 마무리하는 중입니다. |
queued | 실행 슬롯을 기다리고 있습니다. |
running | 작업을 실행하고 있습니다. |
succeeded / partial / failed / cancelled | 작업이 최종 결과에 도달했습니다. 크레딧과 웹훅 전송을 정산하는 동안 결과 조회는 잠시 보류될 수 있습니다. |
reconciliation_required | Web이 정산을 안전하게 끝내지 못했습니다. 새 멱등성 키로 대체 작업을 제출하지 말고 나중에 상태를 다시 조회하거나 지원팀에 문의하세요. |
JOB_FINALIZATION_PENDING Web 정산이 끝날 때까지 결과 엔드포인트는 retryable=true와 함께 HTTP 409를 반환합니다. 같은 결과 URL을 다시 조회하고 새 작업을 만들지 마세요.
고객이 검증한 HTTPS 443 수신 주소워크스페이스 소유자는 대시보드의 웹훅 설정에서 HTTPS 수신 주소와 서명용 비밀값을 관리하고, 비동기 작업 완료 이벤트와 watchdog.changed를 선택하며, 서명 테스트와 전송 이력을 확인할 수 있습니다.
웹훅 설정 열기 →| 이벤트 | 설명 |
|---|---|
job.succeeded | 작업이 성공했고 결과를 조회할 수 있습니다. |
job.partial | 작업이 부분 결과로 완료됐습니다. |
job.failed | 작업이 최종 실패 상태에 도달했습니다. |
job.cancelled | 작업이 취소됐습니다. |
watchdog.changed | 감시 중인 페이지의 변경을 감지했고 변경 이력을 확인할 수 있습니다. |
| 헤더 | 설명 |
|---|---|
X-OngsooLabs-Timestamp | 서명과 재생 방지 시간 검증에 사용하는 Unix 초입니다. |
X-OngsooLabs-Signature | v1=<digest> 형식의 버전이 포함된 소문자 16진수 HMAC-SHA-256 값입니다. |
X-OngsooLabs-Event-Id | 변하지 않는 이벤트 ID입니다. 수신기의 멱등성 키로 사용하세요. |
X-OngsooLabs-Delivery-Id | 이번 개별 전송 시도의 ID입니다. |
검증: 요청 본문을 변형하지 않은 바이트로 읽고, 5분을 벗어난 타임스탬프를 거부하고, 활성 시크릿으로 서명을 계산해 상수 시간으로 비교한 뒤 이벤트 ID로 중복을 제거하세요.
자동 재시도: 즉시 전송하고 실패하면 1분, 5분, 30분, 2시간 뒤에 재시도해 총 5회 시도합니다. 수신을 확인하려면 10초 안에 2xx 응답을 반환하세요.
수동 재전송: 이력은 30일 보존합니다. 재전송은 현재 수신 주소와 비밀값으로 같은 이벤트를 보내되 새 전송 ID·시각·서명을 사용합니다. 작업이나 와치독 확인을 다시 실행하거나 크레딧을 바꾸지 않으며 중복 수신될 수 있습니다.
네트워크 경계: 고정 송신 IP나 고객 IP 허용 목록은 제공하지 않습니다. 모든 전송에서 원본 본문 HMAC, 타임스탬프, 이벤트 ID를 검증하세요.
공개 웹페이지 URL 단위 감시 · 6 / 12 / 24시간 주기공개 웹페이지를 URL 단위로 등록하고 6·12·24시간 주기로 읽을 수 있는 본문 변경을 확인합니다.
현재 제공 범위: 와치독은 로컬 및 격리된 시험 환경에서 검증된 기능이며 아직 운영 환경에 배포되지 않았습니다.
와치독 대시보드 열기 →1. 공개 HTTP 또는 HTTPS 절대 주소를 등록합니다.
2. 6·12·24시간 중 확인 주기를 선택합니다. 필요하면 변경 후 AI 요약을 켭니다.
3. 첫 정상 확인은 비교 기준 본문만 저장하고 변경 이벤트를 보내지 않습니다.
4. 이후 정해진 주기에 읽을 수 있는 본문을 다시 확인합니다.
5. 본문이 달라지면 변경 이력과 watchdog.changed 이벤트를 만듭니다.
6. 대시보드에서 변경 전후 본문·차이·AI 요약을 확인하거나 웹훅으로 알림을 받습니다.
| 항목 | 무료 제공 및 한도 |
|---|---|
| 동시에 감시 가능한 페이지 | 3개 |
| 무료 확인 | 30 Checks / 30일 |
| 확인 주기 | 6 / 12 / 24시간 |
| 전체 활성 감시 한도 | 30개 |
첫 기준 생성과 이후 성공한 확인은 각각 1 Check를 사용합니다. 실행되지 않은 예약은 반환됩니다.
1. 인증 정보가 포함되지 않은 공개 HTTP 또는 HTTPS 절대 주소를 등록합니다.
2. 6시간, 12시간, 24시간 중 확인 주기를 선택합니다. AI 요약은 선택 사항이며 변경이 감지된 뒤에만 생성됩니다.
3. 첫 정상 확인은 기준 본문만 저장하며 변경 이벤트를 보내지 않습니다. 이후에는 정상 확인에서 본문 변경을 감지했을 때만 변경 이력을 남기고 watchdog.changed 이벤트를 생성합니다.
사용 경로: 현재 감시 등록·조회·변경 상세 확인은 인증된 와치독 대시보드에서 제공합니다. 공개 Watchdog REST API는 아직 제공하지 않습니다.
웹훅을 설정하지 않아도 감시는 계속됩니다. 외부 서비스로 변경 알림을 받으려면 대시보드의 웹훅 설정에서 수신 주소를 등록하고 watchdog.changed를 선택하세요. 설정하지 않으면 와치독 대시보드에서 변경 이력을 확인할 수 있습니다.
웹훅 설정 열기 →웹훅은 변경 발생을 알리는 경량 이벤트입니다. URL, 변경 본문, 변경 전후 차이, AI 요약을 포함하지 않아 개인정보와 큰 본문을 알림에 직접 싣지 않습니다. 실제 변경 내용은 인증된 와치독 변경 이력에서 확인합니다.
| 필드 | 설명 |
|---|---|
id | 최상위 id와 X-OngsooLabs-Event-Id는 같은 웹훅 이벤트 식별값입니다. 중복 처리 키로 사용합니다. |
createdAt | 변경 정산 뒤 웹훅 이벤트가 생성된 시각입니다. |
data.eventId | 와치독 원본 이벤트 식별값입니다. |
data.monitorId | 변경이 감지된 감시의 식별값입니다. |
data.runId | 변경을 확인한 실행의 식별값입니다. |
data.status | 변경이 감지되었음을 나타내며 현재 값은 changed입니다. |
data.completedAt | 실제 확인 실행이 완료된 시각입니다. |
data.monitorId는 와치독 대시보드의 감시 설정 및 상세 상태에 표시되는 감시 ID와 같습니다. 검색창에 이 값을 입력하면 해당 감시를 바로 찾을 수 있습니다.
웹훅은 상세 본문 자체가 아니라 변경 이력을 확인하라는 신호입니다.
1. watchdog.changed를 수신하고 서명을 검증합니다.
2. 최상위 id 또는 X-OngsooLabs-Event-Id로 이미 처리한 이벤트를 건너뜁니다.
3. data.monitorId에 해당하는 감시를 와치독 대시보드에서 엽니다.
4. 변경 이력에서 변경 전후 본문, 차이, 선택적으로 생성된 AI 요약을 확인합니다.
변경 상세는 현재 인증된 대시보드에서만 제공합니다. 외부 시스템에서 상세 본문을 자동 조회하는 공개 API는 없습니다.
| 항목 | 보장 범위 |
|---|---|
| 중복 전달 | 자동 재시도와 수동 재전송으로 같은 이벤트가 여러 번 도착할 수 있습니다. |
| 중복 처리 키 | X-OngsooLabs-Event-Id 또는 같은 값인 최상위 id를 사용합니다. 수동 재전송에서도 유지됩니다. |
| 전달 순서 | 재시도와 수동 재전송으로 순서가 바뀔 수 있으므로 도착 순서에 의존하지 않습니다. |
| 성공 응답 | 10초 이내의 HTTP 2xx 응답을 성공으로 인정합니다. |
| 자동 재시도 | 최초 전송 후 실패 시 1분, 5분, 30분, 2시간 뒤 재시도합니다. 최초 전송을 포함해 최대 5회 시도합니다. |
| 시각 관계 | data.completedAt은 확인 완료 시각, createdAt은 정산 뒤 이벤트 생성 시각, X-OngsooLabs-Timestamp는 각 전송 시도의 시각입니다. |
서명 검증: 원본 요청 본문 바이트와 타임스탬프로 HMAC-SHA-256을 계산하고 상수 시간으로 비교합니다. 서명·재시도 가이드 보기 →
| 상태 | 설명 |
|---|---|
submitting | 등록 요청을 처리하고 있습니다. |
baselining | 첫 기준 본문을 만들고 있습니다. 이 단계에서는 변경 이벤트를 보내지 않습니다. |
active | 정해진 주기로 변경을 확인하고 있습니다. |
paused | 정기 확인이 중지된 상태입니다. |
failed | 최근 등록 또는 확인을 완료하지 못했습니다. 대시보드의 마지막 오류를 확인하세요. |
오류가 발생하면 기존 감시의 상태와 마지막 오류를 먼저 확인하세요. 같은 URL을 새 감시로 중복 등록하지 마세요.
감시 등록과 변경 상세는 와치독 대시보드에서, 외부 알림 설정은 웹훅 대시보드에서, 서명과 재시도 규칙은 이 페이지의 공통 웹훅 계약에서 확인합니다.
공통 참고
게이트웨이 오류는 usage.credits = 0인 Reader 오류 응답 형식을 사용합니다. 게이트웨이가 요청을 수락한 뒤에는 다운로드 OpenAPI에 정의된 Reader 오류도 반환될 수 있습니다.
| HTTP | 오류 코드 | 설명 |
|---|---|---|
| 400 | INVALID_REQUEST | 요청 또는 Idempotency-Key 형식이 올바르지 않습니다. |
| 401 | INVALID_API_KEY | X-API-Key가 없거나 비활성·유효하지 않습니다. |
| 403 | USAGE_EXHAUSTED | 워크스페이스에 현재 사용할 수 있는 Direct 크레딧이 없습니다. |
| 409 | IDEMPOTENCY_KEY_CONFLICT | 같은 Idempotency-Key를 다른 method, path 또는 body에 사용했습니다. |
| 413 | REQUEST_BODY_TOO_LARGE | 요청 본문이 Direct 게이트웨이의 수신 제한을 초과했습니다. |
| 429 | RATE_LIMITED | 요청 수신, 자격 증명 또는 워크스페이스 제한에 도달했습니다. Retry-After를 따르세요. |
| 503 | TEMPORARY_UNAVAILABLE | 게이트웨이가 전달 또는 크레딧 정산 상태를 안전하게 확정할 수 없습니다. 같은 Idempotency-Key로 동일 작업을 재시도하세요. |
재시도: error.retryable이 true일 때만 재시도하세요. 429의 Retry-After를 따르고, 동일한 Direct POST 작업 재시도에만 같은 Idempotency-Key를 사용하세요.
개인정보: 공개 HTTPS 웹페이지 또는 공개 텍스트 레이어 PDF URL만 제출하세요. 인증, 쿠키, 임의 헤더, 유료벽 우회, 파일 업로드, OCR, DOCX, 암호화 PDF는 지원하지 않습니다.
지원: 특정 요청 장애는 응답의 X-Request-Id 또는 Reader id를 support@ongsoolabs.com으로 보내세요. 원본 URL은 지원팀이 승인된 경로로 요청한 경우에만 보내세요.