# Felo 웹 읽기

POST /api/v1/data/web/read

애플리케이션이 소비할 수 있는 형식으로 특정 웹 페이지를 읽습니다.

모든 예시는 [개요](https://openapi.felo.ai/ko/docs/data-api/guides/felo-overview.md)의 `FELO_API_KEY`를 사용합니다. 호출은 Felo Pro 크레딧이 아니라 **플랫폼 잔액**을 사용합니다. 응답 예시는 설명용이며, 실제 콘텐츠와 선택적 필드는 달라질 수 있습니다.

## 엔드포인트

`POST /api/v1/data/web/read`

## 요청

| 필드 | 유형 | 필수 | 의미 |
|---|---|---|---|
| `url` | string | 예 | HTTP 또는 HTTPS 페이지 URL |
| `formats` | string array | 아니오 | `MARKDOWN`, `TEXT`, `HTML`, `SCREENSHOT` 중 정확히 하나; 기본값은 Markdown |
| `mode` | string | 아니오 | `quality`(기본값), `fast` 또는 `auto` |
| `timeout` | integer | 아니오 | 밀리초 단위 타임아웃, 1–60,000; 기본값 30,000 |
| `totalTimeout` | integer | 아니오 | 밀리초 단위 총 타임아웃, 1–60,000; 기본값은 `timeout` |

요청당 출력 형식은 하나만 선택하세요. 네 가지를 같은 배열에 모두 보내지 마세요.

```bash
curl -sS --request POST "https://openapi.felo.ai/api/v1/data/web/read" \
  -H "Authorization: Bearer $FELO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com","formats":["MARKDOWN"],"mode":"quality","timeout":30000}'
```

## 응답

HTTP 200은 JSON 루트에서 선택한 콘텐츠 필드를 반환합니다. Markdown 응답은 다음과 같을 수 있습니다:

```json
{
  "title": "Example Domain",
  "markdown": "# Example Domain\n\nThis domain is for use in documentation examples.",
  "metadata": {}
}
```

요청한 형식에 따라 `markdown`, `text`, `html` 또는 `screenshot`을 읽으세요. 다른 메타데이터는 선택 사항이므로 모든 형식 필드가 반드시 존재한다고 가정하지 마세요. 전체 응답은 [OpenAPI 정의](https://openapi.felo.ai/api/v1/data/openapi.json)의 `WebReadResponse` 스키마를 참조하세요.

## 청구 및 실패

`web.read`는 요청당 과금됩니다. 타임아웃은 빈 페이지가 아닙니다. 본문을 사용하기 전에 HTTP 상태를 확인하세요. 타임아웃 후 반복적인 빠른 요청으로 전환하지 마세요. [청구 및 오류](https://openapi.felo.ai/ko/docs/data-api/guides/felo-billing.md)를 따르세요.