AI READER API 가이드

웹 콘텐츠를
AI가 바로 활용할 수 있는 결과로 변환합니다.

공개 HTTPS 콘텐츠를 동기식으로 읽거나 요약하고, Direct 비동기 작업을 제출해 서명된 완료 웹훅을 받을 수 있습니다. LLM, RAG, 에이전트 워크플로에 안정적인 입력을 만드세요.

Direct API 사용 가능

인증

워크스페이스 API 키를 사용합니다.

발급 시 한 번만 표시되는 oslr_ API 키를 X-API-Key에 전송합니다. URL, 브라우저 스크립트, 공개 저장소, 지원 메일에 API 키를 넣지 마세요.

크레딧 사용

AI Reader 성공 작업 1회는 1크레딧입니다.

Reader와 Document는 성공 시 1크레딧, Summary는 5크레딧입니다. 비동기 작업도 제출 시 같은 크레딧을 예약하고 최종 결과 정산이 끝날 때만 확정합니다. 부분 결과, 실패, 취소, 게이트웨이 거부는 0크레딧입니다.

요청 추적

`X-Request-Id`

요청 준비가 끝난 Direct 응답에는 불투명한 X-Request-Id가 포함됩니다. 해당 작업의 지원 문의에 이 값을 보내세요. 인증 또는 요청 수신 단계의 조기 거부에는 없을 수 있습니다.

POST 재시도

Idempotency-Key로 POST 요청을 안전하게 재시도하세요.

Idempotency-Key는 네트워크 타임아웃이나 클라이언트 연결 종료로 결과를 알 수 없을 때 게이트웨이가 같은 논리적 POST 작업을 인식하게 합니다. 동기식 POST에서는 선택 사항이고 모든 비동기 제출에서는 필수입니다.

새 POST 작업마다 UUID D 형식 또는 ULID 값을 새로 만듭니다.
첫 요청에 그 값을 넣고, 같은 작업을 재시도할 때에만 같은 값을 다시 사용합니다.
요청 내용이 달라지면 새 값을 사용합니다. 다른 입력에 같은 식별값을 재사용하면 409 IDEMPOTENCY_KEY_CONFLICT가 반환됩니다.

Idempotency-Key POST 예시에 표시된 값은 새 값으로 바꿔 사용하세요. 실제 요청에서 예시 값을 그대로 재사용하면 안 됩니다.

빠르게 경험하기

첫 Reader 요청 흐름을 빠르게 살펴보세요.

OngsooLabs가 직접 작성한 정적 HTML 입력으로 Direct API의 요청과 응답 형식을 빠르게 확인할 수 있습니다. 실제 호출을 실행하는 도구가 아니라 응답 형식을 확인하기 위한 참고 예시입니다.

원본 URL: /examples/reader/owned-controlled-reader-source.html
Direct 엔드포인트: POST /api/v1/reader
인증: X-API-Key: oslr_your_api_key
출력 형식: markdown

DIRECT 요청

POST /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 호출을 실행하지 않습니다.

실행 가능한 코드 예제 · GitHub

GET

URL 매개변수로 웹페이지 읽기

/api/v1/reader

URL 매개변수로 공개 HTTPS 웹페이지 하나에서 본문, 메타데이터, 선택적 청크를 추출합니다.

적합한 경우: JSON 본문 없이 URL만으로 연동하거나 간단한 진단 요청이 필요할 때 적합합니다.

사용량 규칙 성공 1회당 Direct 1크레딧 부분 결과·실패·게이트웨이 거부 요청은 0크레딧입니다.

Base URL: https://ongsoolabs.com
제한: 요청 한 번에 공개 HTTPS URL 한 개만 처리합니다. 로그인, 쿠키, 사용자 지정 헤더, 유료벽·봇 차단 우회, 배치·크롤·비동기 작업은 지원하지 않습니다.

요청 파라미터

파라미터	필수 여부	기본값	설명
`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 명세를 기준으로 작성되었습니다.

POST

JSON 옵션을 지정해 웹페이지 읽기

/api/v1/reader

공개 HTTPS 웹페이지 하나를 읽어 Markdown, 텍스트 또는 구조화된 JSON으로 반환합니다. 출력 형식과 청크 옵션을 지정할 수 있습니다.

적합한 경우: 반복 가능한 RAG 수집, 메타데이터 관리, 동적 렌더링 재시도 또는 응답 내 청크가 필요할 때 적합합니다.

사용량 규칙 성공 1회당 Direct 1크레딧 부분 결과·실패·게이트웨이 거부 요청은 0크레딧입니다.

Base URL: https://ongsoolabs.com
제한: 요청 한 번에 공개 HTTPS URL 한 개만 처리합니다. 먼저 정적 페이지 수집을 시도하며 force_dynamic은 브라우저 렌더링을 요청할 뿐 접근 제어를 우회하지 않습니다.

요청 파라미터

파라미터	필수 여부	기본값	설명
`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 명세를 기준으로 작성되었습니다.

POST

공개 PDF에서 텍스트 읽기

/api/v1/reader/document

공개 HTTPS의 텍스트 레이어 PDF URL에서 본문을 읽어 Markdown으로 반환하고, 필요하면 토큰 계산과 청크 분할을 수행합니다.

적합한 경우: 텍스트를 선택하고 추출할 수 있는 공개 규격서, 보고서 또는 논문의 본문이 필요할 때 적합합니다.

사용량 규칙 성공 1회당 Direct 1크레딧 부분 결과·실패·게이트웨이 거부 요청은 0크레딧입니다.

Base URL: https://ongsoolabs.com
제한: 최대 10 MiB, 100페이지까지 처리하며 Markdown만 반환합니다. 파일 업로드, DOCX, OCR, 암호화된 PDF, 브라우저 렌더링, 쿠키, 사용자 지정 헤더는 지원하지 않습니다.

요청 파라미터

파라미터	필수 여부	기본값	설명
`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 명세를 기준으로 작성되었습니다.

POST

텍스트를 청크로 나누기

/api/v1/reader/chunk

입력 텍스트를 임베딩·검색 파이프라인에 맞게 토큰 또는 문자 기준의 겹치는 순차 청크로 나눕니다.

적합한 경우: 이미 텍스트 원문을 가지고 있으며 URL을 읽지 않고 일정한 청크 경계가 필요할 때 적합합니다.

사용량 규칙 성공 1회당 Direct 1크레딧 부분 결과·실패·게이트웨이 거부 요청은 0크레딧입니다.

Base URL: https://ongsoolabs.com
제한: 입력은 최대 1,000,000자, 반환 청크는 최대 2,048개입니다. 토큰 크기는 16-8,192, 문자 크기는 64-65,536이며 겹침 크기는 청크 크기보다 작아야 합니다.

요청 파라미터

파라미터	필수 여부	기본값	설명
`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 명세를 기준으로 작성되었습니다.

POST

웹페이지 요약 만들기

/api/v1/summary

공개 HTTPS 웹페이지 URL 하나를 제출합니다. quality는 선택이며 현재 standard만 허용합니다.

사용량 규칙 Summary 성공 1회당 Direct 5크레딧 요청 실패, Reader 부분 결과 또는 게이트웨이 거부에는 Summary 크레딧이 차감되지 않습니다.

Base URL: https://ongsoolabs.com
제한: 요청 하나에 공개 HTTPS 웹페이지 하나만 처리합니다. PDF, 파일 업로드, OCR, 사용자 프롬프트, 쿠키, 헤더, 일괄 처리는 지원하지 않습니다. 같은 HTTP 요청에서 결과를 기다리지 않으려면 Direct 비동기 작업 엔드포인트를 사용하세요.

요청 본문

{
  "url": "https://example.com/article",
  "quality": "standard"
}

응답 예시

{
  "id": "sum_example",
  "schemaVersion": "1.0",
  "apiVersion": "v1",
  "url": "https://example.com/article",
  "finalUrl": "https://example.com/article",
  "status": "success",
  "sourceType": "html",
  "title": "Example article",
  "summary": "This controlled example shows the response shape for one successful webpage summary.",
  "keywords": [
    "controlled example",
    "webpage summary"
  ],
  "quality": "standard",
  "usage": {
    "inputTokens": 128,
    "outputTokens": 42,
    "credits": 5
  },
  "execution": {
    "durationMs": 412
  }
}

Idempotency-Key 논리적인 POST 작업마다 고유한 UUID D 형식 또는 ULID를 사용하고, 같은 작업을 재시도할 때만 같은 값을 다시 사용하세요. 다른 요청에 재사용하면 409를 반환합니다.

성공 응답은 title, summary, keywords, sourceType, usage, execution과 버전 정보를 포함한 Summary 객체입니다. 제공업체와 모델 이름은 노출하지 않습니다.

202

Reader·Document·Summary를 비동기로 실행

POST /api/v1/{operation}/jobs

처음 연결한 HTTP 요청을 계속 열어 두지 않고 작업을 제출합니다. 제출에 성공하면 불투명한 작업 ID와 상태·결과 조회 URL을 담은 202 Accepted 응답을 반환합니다.

적합한 경우: 제출 응답에서 결과를 기다리는 대신 완료될 때까지 조회하거나 완료 웹훅을 받을 수 있을 때 사용합니다.

사용량 규칙 동기 요청과 같은 크레딧을 예약한 뒤 한 번만 정산합니다. Reader와 Document는 1크레딧, Summary는 5크레딧을 예약합니다. 성공한 최종 결과만 예약을 확정하며 부분 결과, 실패, 취소는 예약을 해제합니다.

Base URL: https://ongsoolabs.com
제공 범위: OngsooLabs Direct에서만 제공합니다. 외부 마켓 채널에서는 비동기 제출과 완료 웹훅을 제공하지 않습니다.

비동기 작업 생명주기 엔드포인트

메서드	엔드포인트	설명
`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 는 모든 제출 요청에 필수입니다. 정확히 같은 논리 요청을 재시도할 때만 재사용하세요.

Reader 작업 제출

curl --request POST \
  --url "https://ongsoolabs.com/api/v1/reader/jobs" \
  --header "X-API-Key: oslr_your_api_key" \
  --header "Idempotency-Key: 00000000-0000-4000-8000-000000000000" \
  --header "Content-Type: application/json" \
  --data '{
  "url": "https://example.com/article",
  "output_format": "markdown"
}'

202 Accepted 응답

{
  "jobId": "aj_example",
  "operation": "reader",
  "status": "queued",
  "statusUrl": "/api/v1/jobs/aj_example",
  "resultUrl": "/api/v1/jobs/aj_example/result"
}

작업 상태 생명주기

상태	설명
`created`	지속성 작업을 생성했고 활성화를 마무리하는 중입니다.
`queued`	실행 슬롯을 기다리고 있습니다.
`running`	작업을 실행하고 있습니다.
`succeeded` / `partial` / `failed` / `cancelled`	작업이 최종 결과에 도달했습니다. 크레딧과 웹훅 전송을 정산하는 동안 결과 조회는 잠시 보류될 수 있습니다.
`reconciliation_required`	Web이 정산을 안전하게 끝내지 못했습니다. 새 멱등성 키로 대체 작업을 제출하지 말고 나중에 상태를 다시 조회하거나 지원팀에 문의하세요.

상태 응답

{
  "jobId": "aj_example",
  "operation": "reader",
  "status": "succeeded",
  "createdAt": "2026-09-05T00:00:00Z",
  "completedAt": "2026-09-05T00:00:08Z",
  "errorCode": null
}

JOB_FINALIZATION_PENDING Web 정산이 끝날 때까지 결과 엔드포인트는 retryable=true와 함께 HTTP 409를 반환합니다. 같은 결과 URL을 다시 조회하고 새 작업을 만들지 마세요.

POST

서명된 완료 웹훅 수신

검증된 고객 HTTPS 443 엔드포인트

워크스페이스 소유자는 Dashboard Webhooks에서 HTTPS 엔드포인트 하나와 한 번만 표시되는 시크릿을 관리하고, 작업 종류와 완료 이벤트를 선택하며, 서명 테스트와 전송 이력을 확인할 수 있습니다.

Dashboard Webhooks 열기 →

완료 이벤트

이벤트	설명
`job.succeeded`	작업이 성공했고 결과를 조회할 수 있습니다.
`job.partial`	작업이 부분 결과로 완료됐습니다.
`job.failed`	작업이 최종 실패 상태에 도달했습니다.
`job.cancelled`	작업이 취소됐습니다.

전송 헤더

헤더	설명
`X-OngsooLabs-Timestamp`	서명과 재생 방지 시간 검증에 사용하는 Unix 초입니다.
`X-OngsooLabs-Signature`	v1=<digest> 형식의 버전이 포함된 소문자 16진수 HMAC-SHA-256 값입니다.
`X-OngsooLabs-Event-Id`	변하지 않는 완료 이벤트 ID입니다. 수신기의 멱등성 키로 사용하세요.
`X-OngsooLabs-Delivery-Id`	이번 개별 전송 시도의 ID입니다.

완료 페이로드

{
  "id": "8b8b2ac0-bb51-4fbb-91f8-3a517739f687",
  "type": "job.succeeded",
  "createdAt": "2026-09-05T00:00:09Z",
  "data": {
    "jobId": "aj_example",
    "operation": "reader",
    "status": "succeeded",
    "completedAt": "2026-09-05T00:00:08Z",
    "errorCode": null
  }
}

서명 입력값

signed = UTF8(timestamp + ".") || raw_request_body
expected = "v1=" + hex(HMAC-SHA256(webhook_secret, signed))

검증: 요청 본문을 변형하지 않은 바이트로 읽고, 5분을 벗어난 타임스탬프를 거부하고, 활성 시크릿으로 서명을 계산해 상수 시간으로 비교한 뒤 이벤트 ID로 중복을 제거하세요.

자동 재시도: 즉시 전송하고 실패하면 1분, 5분, 30분, 2시간 뒤에 재시도해 총 5회 시도합니다. 수신을 확인하려면 10초 안에 2xx 응답을 반환하세요.

수동 재전송: 이력은 30일 보존합니다. 재전송은 현재 엔드포인트와 시크릿으로 같은 이벤트를 보내되 새 전송 ID·타임스탬프·서명을 사용합니다. 작업을 다시 실행하거나 크레딧을 바꾸지 않으며 중복 수신될 수 있습니다.

네트워크 경계: 고정 송신 IP나 고객 IP 허용 목록은 제공하지 않습니다. 모든 전송에서 원본 본문 HMAC, 타임스탬프, 이벤트 ID를 검증하세요.

공통 참고

오류·재시도 참고

게이트웨이 오류는 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은 지원팀이 승인된 경로로 요청한 경우에만 보내세요.

웹 콘텐츠를AI가 바로 활용할 수 있는 결과로 변환합니다.

워크스페이스 API 키를 사용합니다.

AI Reader 성공 작업 1회는 1크레딧입니다.

X-Request-Id

Idempotency-Key로 POST 요청을 안전하게 재시도하세요.

첫 Reader 요청 흐름을 빠르게 살펴보세요.

요청 파라미터

요청 예시

응답 예시

요청 파라미터

요청 예시

응답 예시

요청 파라미터

요청 예시

응답 예시

요청 파라미터

요청 예시

응답 예시

요청 본문

응답 예시

비동기 작업 생명주기 엔드포인트

Reader 작업 제출

202 Accepted 응답

작업 상태 생명주기

상태 응답

완료 이벤트

전송 헤더

완료 페이로드

서명 입력값

웹 콘텐츠를
AI가 바로 활용할 수 있는 결과로 변환합니다.

`X-Request-Id`