Karon Web Access API 문서

Base URL: https://api.karonlabs.net

Karon Web Access API는 AI 에이전트가 공식 문서, 표준, 논문, 기술 레퍼런스 같은 공개 지식을 읽고 정리할 수 있도록 만든 프로덕션 API입니다.

실측 기준

이 문서는 2026-06-13 기준 라이브 OpenAPI, prod server/models.py, prod CreditPolicy, 실제 라이브 smoke 호출을 기준으로 정리했습니다. 공개 문서에는 일반 사용자에게 필요한 공개 계약만 싣고, 내부 운영·관리·보안 실험 라우트와 내부 진단 필드는 제외합니다.

상태	엔드포인트	메모
핵심	`/v1/agent/browse`, `/v1/fetch`	AI 에이전트가 공개 지식을 읽는 주력 경로입니다. Bearer API 키가 필요합니다.
지원	`/v1/watch/snapshot`, `/v1/watch/diff`, `/v1/watch/list`, `/v1/credits`	변경 감지와 계정 상태 확인용입니다. Bearer API 키가 필요합니다.
공개	`/health`, `/v1/pricing`	인증 없이 호출할 수 있습니다.
인증 흐름	`/auth/google`, `/auth/google/callback`, `/auth/signup-result`	API 키 발급과 계정 확인 화면에서 사용합니다.

빠른 시작

curl -sS -X POST "https://api.karonlabs.net/v1/agent/browse" \
  -H "Authorization: Bearer __YOUR_API_KEY__" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com",
    "extract": "markdown",
    "readability": true
  }'

/v1/agent/browse는 AI 에이전트용 주력 엔드포인트입니다. HTML 원문보다 본문 중심의 text, markdown, html, json, pruned 결과가 필요할 때 사용합니다.

인증

API 키가 필요한 엔드포인트는 아래 헤더를 사용합니다. 공개 요금 조회와 health check는 인증이 필요 없습니다.

Authorization: Bearer __YOUR_API_KEY__

POST /v1/agent/browse

공개 웹 페이지를 AI가 읽기 좋은 본문으로 바꿉니다. 동적 렌더링이 필요하면 브라우저 fallback을 사용하며, 응답의 timing과 cost_credits로 처리 경로와 비용을 확인합니다.

필드	기본값	설명
url 필수	-	읽을 공개 URL입니다.
extract	text	`text`, `markdown`, `html`, `json`, `pruned`
selector	-	특정 CSS selector만 추출합니다.
wait_selector	-	브라우저 fallback에서 특정 요소가 렌더링될 때까지 기다립니다.
wait_timeout_ms	30000	범위는 `1000-60000ms`입니다.
full_access	false	경량/cache 경로를 건너뛰고 브라우저 렌더링 경로를 강제합니다.
session_id	-	연속 요청에서 쿠키와 세션 흐름을 묶습니다.
auto_links	false	페이지의 절대 HTTP/HTTPS 링크 목록을 함께 반환합니다.
readability	true	본문 중심 정리를 적용합니다. 목록·검색·포털형 페이지는 `false`를 테스트하세요.
json_schema	-	`extract: "json"`에서만 사용합니다.
json_prompt	-	`extract: "json"`에서만 사용하며 최대 1000자입니다.

{
  "success": true,
  "url": "https://example.com",
  "rid": "<request-id>",
  "cost_credits": 0,
  "your_credits": null,
  "error": null,
  "timing": {
    "total_ms": 466,
    "cache_hit": false,
    "curl": true
  },
  "content": "# Example Domain\n\nThis domain is for use in documentation examples without needing permission. Avoid use in operations.\n\n[Learn more](https://iana.org/domains/example)",
  "content_len": 167,
  "structured_data": null,
  "extract_mode": "markdown",
  "links": null,
  "warning": "extracted_content_too_short",
  "page_title": "Example Domain",
  "page_description": null
}

위 예시는 실제 이용자 키로 https://example.com을 호출한 형태입니다. rid, timing, cost_credits, your_credits는 계정 정책과 캐시 상태에 따라 달라질 수 있습니다. 운영 세부 필드는 예시에서 생략했습니다.

구조화 추출

extract: "json"은 가져온 공개 본문에서 필요한 필드 구조화를 시도합니다. json_schema와 json_prompt는 JSON 모드에서만 유효합니다.

curl -sS -X POST "https://api.karonlabs.net/v1/agent/browse" \
  -H "Authorization: Bearer __YOUR_API_KEY__" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com",
    "extract": "json",
    "json_prompt": "페이지 제목과 용도를 추출하세요.",
    "json_schema": {
      "type": "object",
      "properties": {
        "title": { "type": "string" },
        "purpose": { "type": "string" }
      }
    }
  }'

{
  "success": true,
  "url": "https://example.com",
  "rid": "<request-id>",
  "cost_credits": 6,
  "your_credits": "<account-dependent>",
  "error": null,
  "timing": {
    "total_ms": 2284,
    "cache_hit": false,
    "curl": true
  },
  "content": "",
  "content_len": 0,
  "structured_data": {
    "title": "Example Domain",
    "purpose": "This domain is for use in documentation examples without needing permission. Avoid use in operations."
  },
  "extract_mode": "json",
  "links": null,
  "warning": null,
  "page_title": "Example Domain"
}

JSON 구조화 추출은 현재 라이브에서 로컬 SuperGemma 백엔드를 사용합니다. 구조화 결과가 실제로 만들어진 경우에만 JSON 추가 비용이 붙으며, 일반 사용자 기준 cache/curl 1에 구조화 추출 +5가 더해집니다. 관리자 또는 내부 검증 키는 cost_credits가 0으로 보일 수 있습니다.

POST /v1/fetch

공개 URL의 HTML 본문, status code, headers가 필요할 때 사용합니다.

필드	기본값	설명
url 필수	-	가져올 공개 URL입니다.
wait_selector	-	브라우저 fallback에서 기다릴 CSS selector입니다.
wait_timeout_ms	30000	범위는 `1000-60000ms`입니다.
session_id	-	연속 요청 세션을 유지합니다.
cache_scope	global	`global` 또는 `session`입니다.
fallback	true	경량 요청이 충분하지 않을 때 브라우저 fallback을 허용합니다.

curl -sS -X POST "https://api.karonlabs.net/v1/fetch" \
  -H "Authorization: Bearer __YOUR_API_KEY__" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com"}'

{
  "success": true,
  "url": "https://example.com",
  "rid": "<request-id>",
  "cost_credits": 0,
  "your_credits": null,
  "error": null,
  "timing": {
    "total_ms": 0,
    "full_access": false,
    "cache_hit": true
  },
  "status_code": 200,
  "body": "<!doctype html><html lang=\"en\"><head><title>Example Domain</title>...",
  "body_len": 559,
  "session_id": "https://example.com",
  "headers": {
    "content-type": "text/html"
  },
  "set_cookies": null
}

POST Watch API

공개 페이지의 스냅샷을 저장하고 이전 스냅샷과 비교합니다. watch는 내부적으로 browse 흐름을 사용하므로 비용도 browse 정책을 따릅니다.

엔드포인트	요청 필드	응답 핵심
/v1/watch/snapshot	`url`, `extract`, `readability`, `json_schema`, `json_prompt`, `ttl_days`	`snapshot_id`, `content_hash`, `content_len`, `previous_snapshot`, `diff`
/v1/watch/diff	`url`, `extract`, `readability`, `json_schema`, `json_prompt`	`changed`, `current_snapshot_id`, `previous_snapshot_id`, `change_ratio`, `diff_text`
/v1/watch/list	-	`total`, `urls`

curl -sS -X POST "https://api.karonlabs.net/v1/watch/snapshot" \
  -H "Authorization: Bearer __YOUR_API_KEY__" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com", "extract": "text", "ttl_days": 1}'

{
  "success": true,
  "url": "https://example.com",
  "snapshot_id": "<snapshot-id>",
  "content_hash": "<sha256>",
  "content_len": 127,
  "previous_snapshot": null,
  "diff": null,
  "cost_credits": 0,
  "error": null
}

curl -sS -X POST "https://api.karonlabs.net/v1/watch/diff" \
  -H "Authorization: Bearer __YOUR_API_KEY__" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com", "extract": "text"}'

{
  "success": true,
  "url": "https://example.com",
  "changed": false,
  "current_snapshot_id": "<snapshot-id>",
  "previous_snapshot_id": "<snapshot-id>",
  "current_content_len": 127,
  "previous_content_len": 127,
  "diff_text": "",
  "cost_credits": 0,
  "error": null
}

curl -sS "https://api.karonlabs.net/v1/watch/list" \
  -H "Authorization: Bearer __YOUR_API_KEY__"

{
  "total": 1,
  "urls": [
    {
      "url": "https://example.com",
      "extract_mode": "text",
      "content_hash": "<sha256>",
      "content_len": 127,
      "last_snapshot_at": "<iso8601>"
    }
  ]
}

/v1/watch/snapshot과 /v1/watch/diff는 호출할 때마다 스냅샷을 저장합니다. snapshot_id, content_hash, last_snapshot_at은 계정과 호출 시점마다 달라집니다.

GET /v1/credits

내 계정의 남은 크레딧, tier, rate limit을 확인합니다.

curl -sS "https://api.karonlabs.net/v1/credits" \
  -H "Authorization: Bearer __YOUR_API_KEY__"

{
  "name": "<account-name>",
  "credits_remaining": "<account-dependent>",
  "tier": "free",
  "tier_name": "Free",
  "credits_included": 5000,
  "rate_limit": 300
}

GET /v1/pricing

인증 없이 현재 공개 요금제를 확인합니다. 현재 라이브 tier는 Free, Starter, Growth, Scale, Enterprise입니다.

{
  "tiers": {
    "free": { "price_usd": 0, "credits": 5000, "rate_limit": 300, "daily_limit": 10000, "name": "Free" },
    "starter": { "price_usd": 29, "credits": 10000, "rate_limit": 60, "daily_limit": 2000, "name": "Starter" }
  }
}

GET /health

서비스 상태 확인용 엔드포인트입니다. 현재 라이브 응답은 status: "ok"와 버전 값을 반환합니다.

{
  "status": "ok",
  "version": "0.2.0",
  "timestamp": "<iso8601>",
  "court_rig": {
    "ready": false,
    "last_checked": "",
    "details": {}
  }
}

크레딧 정책

경로	비용	메모
cache/curl	cache/curl 1	캐시 응답 또는 경량 fetch/browse 성공
browser	browser 10	브라우저 기반 fallback 성공
json	구조화 추출 +5	`extract: "json"` 구조화 결과가 성공한 경우
watch	browse 정책 승계	snapshot과 diff는 내부 browse 호출 비용을 따릅니다.

요청 실패, 클라이언트 취소, 브라우저 작업 완료 시점에 따라 실제 차감 여부가 달라질 수 있습니다. 응답의 cost_credits를 기준으로 처리하세요.

MCP 클라이언트

Karon MCP는 Karon API를 Claude Code, Cursor, Codex 같은 MCP 호스트에서 바로 쓸 수 있게 해주는 연결 레이어입니다. REST API가 정본 계약이고, MCP는 그 계약을 작은 도구 surface로 감쌉니다.

공개 MCP 도구는 두 개입니다.

browse: /v1/agent/browse를 호출해 단일 URL을 markdown, text, html로 가져옵니다.
credits: /v1/credits를 호출해 계정 크레딧과 tier 정보를 확인합니다.

KARON_API_KEY=__YOUR_API_KEY__ uvx --refresh karon-mcp

오류와 제한

Status	의미	대응
401	API 키 누락 또는 오류	Authorization Bearer 값을 확인합니다.
403	계정 또는 edge 정책 제한	계정 상태, API 키 권한, 호출 대상 엔드포인트를 확인합니다.
422	요청 스키마 오류	URL, `extract` 값, timeout 범위를 확인합니다.
429	rate limit 또는 크레딧 제한	짧은 backoff 후 재시도하거나 요금제를 조정합니다.
5xx	상류 접근 또는 처리 실패	응답 본문의 일반화된 오류 타입을 기록하고 재시도 정책을 적용합니다.