> ## Documentation Index
> Fetch the complete documentation index at: https://docs.conare.ai/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Conare's API is at https://api.conare.ai. Authenticate with `Authorization: Bearer $CONARE_API_KEY`.
> The full OpenAPI spec is at https://api.conare.ai/openapi.yaml; each endpoint has a page under /api-reference, and appending .md to any page URL returns its Markdown.
> Embed with model conare-embed-1; send input_type "query" for search queries. Rerank with conare-rerank-1.
> Prefer the TypeScript SDK (`npm install conare`) or plain HTTP in examples.
> Install the Conare skill with `npx skills add https://docs.conare.ai`; search these docs over MCP at https://docs.conare.ai/mcp; the whole site is at https://docs.conare.ai/llms-full.txt.

# 파일

> PDF, Word, PowerPoint, Excel, 이미지를 하나의 검색 가능한 문서로 업로드하거나 저장 없이 Markdown으로 파싱합니다.

두 라우트가 하나의 파서, 같은 옵션, 같은 결과로 파일을 읽습니다:

| 라우트 | 동작 | 크기 |
| - | - | - |
| [`POST /namespaces/:namespace/files`](#파일-업로드) | 파일을 하나의 검색 가능한 문서로 저장합니다. 검색은 답하는 페이지, 슬라이드 또는 행을 알려 줍니다 | 최대 512 MiB, 5,000페이지 |
| [`POST /parse`](#파일-파싱) | 파일을 Markdown으로 반환하며, 아무것도 저장하지 않습니다 | 최대 20 MiB |

스캔과 이미지는 페이지 수와 관계없이 OCR로 읽습니다. 지원 형식: [파일 형식](https://docs.conare.ai/ko/file-types.md).

## 파일 업로드

`POST /namespaces/:namespace/files`

파일 바이트를 본문으로 보내거나, multipart 폼의 파일 부분으로 보내거나, Conare가 가져오도록 JSON `{"url": "https://..."}`로 보내세요.

```bash curl theme={null}
curl "https://api.conare.ai/namespaces/reports/files?name=report.pdf" \
  -H "Authorization: Bearer $CONARE_API_KEY" \
  -H "Content-Type: application/pdf" \
  --data-binary @report.pdf
```

```bash curl (form) theme={null}
curl https://api.conare.ai/namespaces/reports/files \
  -H "Authorization: Bearer $CONARE_API_KEY" \
  -F file=@report.pdf
```

```bash curl (URL) theme={null}
curl https://api.conare.ai/namespaces/reports/files \
  -H "Authorization: Bearer $CONARE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/report.pdf"}'
```

```ts TypeScript theme={null}
import { readFile } from "node:fs/promises";

const reports = conare.namespace("reports");
const file = await reports.uploadFile(await readFile("report.pdf"), "report.pdf", {
  metadata: { site: "north-pit" },
});
```

```json Response theme={null}
{
  "file_id": "report.pdf",
  "name": "report.pdf",
  "type": "pdf",
  "state": "ready",
  "source_id": "src_01139ca8ca59f2556f65b60e",
  "uploaded_at": 1792618822534,
  "pages": 2,
  "ids": ["src_01139ca8ca59f2556f65b60e:report.pdf"],
  "ocr_failed": [],
  "ocr_pending": [],
  "markdown": "<!-- page 1 -->\n\n# Q3 report\n\nRevenue grew 12 percent in EMEA.\n\n<!-- page 2 -->\n\n# Outlook\n\nWe expect Q4 revenue to grow again.",
  "parts": [
    { "locator": { "page": 1 }, "markdown": "# Q3 report\n\nRevenue grew 12 percent in EMEA.", "ocr": true, "confidence": null },
    { "locator": { "page": 2 }, "markdown": "# Outlook\n\nWe expect Q4 revenue to grow again.", "ocr": true, "confidence": null }
  ],
  "without_text": { "pages": [], "slides": [], "images": [] }
}
```

응답은 파일을 읽을 때까지 최대 `wait`초 기다립니다. `ready` 또는 `failed`이면 `200`, 아직 읽는 중이면 `202`를 반환합니다.

### 옵션

쿼리 파라미터이며, 별도 표기가 없으면 두 라우트 모두에 적용됩니다.

| 옵션 | 타입 | 기능 |
| - | - | - |
| `name` | string | 최대 4,096자의 파일 이름. 확장자로 `.csv`, `.tsv`, `.md`를 텍스트와 구분합니다 |
| `id` | string | 업로드 전용. 파일 id로, 문서 id의 끝부분이 됩니다. 기본값은 다른 문자를 `-`로 바꾼 `name`입니다 |
| `type` | string | `pdf`, `docx`, `pptx`, `xlsx`, `csv`, `png`, ... ([전체](https://docs.conare.ai/ko/file-types.md)). 없으면 바이트, 그다음 이름에서 판단합니다 |
| `user` | string | 업로드 전용. 파일 소유자. 사용자를 삭제하면 파일도 삭제됩니다 |
| `metadata` | string | 업로드 전용. 문서의 메타데이터에 복사되는 JSON 객체 |
| `pages` | string | 읽을 페이지, 슬라이드 또는 프레임. 예: `1-20,25` 또는 `5-` |
| `password` | string | 보호된 PDF, Word, PowerPoint, Excel 파일(최대 20 MiB)을 엽니다 |
| `layout` | boolean, 기본값 `false` | OCR로 읽은 각 부분에 페이지 영역인 `blocks`도 포함됩니다([필드](https://docs.conare.ai/ko/file-types.md#레이아웃-블록)) |
| `wait` | 초, 기본값 60 | `202` 전에 읽기를 기다리는 시간, 최대 300. `0`은 즉시 응답합니다 |

* `application/pdf` 같은 `Content-Type`으로도 타입을 지정할 수 있습니다.
* `wait`: `true`는 60입니다. 응답은 항상 105초 이내에 옵니다. 업로드에서 `false`는 텍스트가 저장되는 즉시 `ocr_pending`과 함께 응답합니다.
* `pages` 밖의 페이지는 읽거나 OCR하지 않습니다. 페이지가 없는 파일에 `pages`를 쓰면 `400`입니다.

전체 스키마: [파일 업로드](https://docs.conare.ai/ko/api-reference/files/upload-a-file.md).

### 응답

| 필드 | 의미 |
| - | - |
| `file_id`, `name`, `type` | 사용된 id, 이름, 판별된 타입(모든 이미지 형식은 `image`) |
| `state` | `queued`, `parsing`, `ocr`(OCR이 아직 `ocr_pending`을 읽는 중), `ready`, 또는 `error`와 함께 `failed` |
| `source_id` | 네임스페이스의 파일 소스. 문서 id가 이것으로 시작합니다 |
| `ids` | `ready`가 되면 파일의 단일 문서 `["<source_id>:<file_id>"]` |
| `uploaded_at` | Unix 밀리초 |
| `result` | 같은 파일, 이름, 메타데이터, 옵션이 이전에 업로드된 경우 `unchanged`. 다시 읽지 않습니다 |
| `pages` | PDF의 페이지 또는 이미지의 프레임 |
| `ocr_failed` | 여러 번 시도해도 OCR이 읽지 못한 페이지. 다시 업로드하면 재시도합니다 |
| `markdown`, `parts`, `without_text` | [결과](#결과) |

`images_without_text`, `pages_without_text`, `pages_ocr`, `images_ocr`, `sheets`, `slides`, `slides_without_text`는 지원 중단되었습니다. `parts`와 `without_text`가 같은 정보를 제공합니다.

## 파일 확인

`GET /namespaces/:namespace/files/:id`

파일의 최신 업로드를 같은 필드로 반환합니다. `202` 이후에 폴링하세요.

```bash curl theme={null}
curl https://api.conare.ai/namespaces/reports/files/report.pdf \
  -H "Authorization: Bearer $CONARE_API_KEY"
```

```ts TypeScript theme={null}
const file = await reports.getFile("report.pdf");
```

| 옵션 | 타입 | 기능 |
| - | - | - |
| `user` | string | `user`와 함께 업로드한 파일의 사용자 |

전체 스키마: [파일 읽기](https://docs.conare.ai/ko/api-reference/files/read-a-file.md).

## 저장된 문서

파일 하나는 문서 하나, `<source_id>:<file_id>`입니다. 페이지, 슬라이드, 시트 행, 섹션, 그림은 그 문서의 부분입니다.

| 어디서 | 받는 것 |
| - | - |
| [검색](https://docs.conare.ai/ko/query.md) | PDF나 이미지의 페이지, 슬라이드, 시트의 행 범위는 각각 하나의 결과이며, id는 `<source_id>:<file_id>$<part>`입니다(`$page-3`, `$slide-4`, `$<sheet>-1`) |
| 텍스트, Markdown, Word 파일 검색 | 결과 하나, 즉 파일 `<source_id>:<file_id>`이며, 파일 어디에서든 나온 구절이 함께 옵니다 |
| 결과의 `metadata` | 그 부분 또는 첫 구절의 위치. 키는 아래 표와 같습니다 |
| [`GET /namespaces/:namespace/documents/:id`](https://docs.conare.ai/ko/documents#문서-조회) | 파일 id로는 파일 전체의 텍스트(페이지 사이에 빈 줄), 부분 id로는 그 부분만 |

### 부분의 위치

| 파일 | 메타데이터의 위치 |
| - | - |
| PDF | `page` |
| Word, 텍스트, Markdown | `part`, `heading`, 텍스트는 `lines` |
| PowerPoint | `slide` |
| Excel, CSV, TSV | `sheet`, `rows` |
| 이미지 | `page`, `frame` |
| Word 안의 그림 | `image`, `heading` |
| 슬라이드의 그림 | `slide`, `image` |
| 시트의 차트 | `sheet` |

문서에는 `file`, `file_id`, `file_type`, `uploaded_at`, 업로드의 `metadata`도 있으며, OCR로 읽었으면 `ocr: true`가 있습니다. 이전에 업로드한 파일은 다시 업로드할 때까지 부분마다 문서 하나(`<source_id>:<file_id>:page-1` 등)로 남아 있을 수 있습니다.

| 목적 | 방법 |
| - | - |
| 파일 교체 | 같은 id로 다시 업로드하세요 |
| 안전한 재시도 | 같은 파일, 이름, 메타데이터, 옵션이면 `unchanged`로 응답하며 `Idempotency-Key`가 필요 없습니다 |
| 파일 하나 검색 | `{ "file_id": "report.pdf" }`로 [필터](https://docs.conare.ai/ko/filters.md)하세요 |
| 페이지 하나 검색 | `{ "file_id": "report.pdf", "page": 3 }`로 필터하세요 |
| 사용자 분리 | `user`로 업로드하고 `user`로 [검색](https://docs.conare.ai/ko/query.md)하세요 |
| 원본 삭제 | 네임스페이스나 해당 사용자가 삭제될 때까지 보관됩니다 |

## 파일 파싱

`POST /parse`

파일을 Markdown으로 반환하고 아무것도 저장하지 않습니다. Models only 키를 포함해 모든 키로 파싱할 수 있습니다.

```bash curl theme={null}
curl "https://api.conare.ai/parse?name=report.pdf" \
  -H "Authorization: Bearer $CONARE_API_KEY" \
  -H "Content-Type: application/pdf" \
  --data-binary @report.pdf
```

```bash curl (URL) theme={null}
curl https://api.conare.ai/parse \
  -H "Authorization: Bearer $CONARE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/report.pdf"}'
```

```ts TypeScript theme={null}
import { readFile } from "node:fs/promises";

const out = await conare.parse(await readFile("report.pdf"), { name: "report.pdf" });
if (out.state === "parsing") console.log(await conare.getParse(out.id));
```

```json Response theme={null}
{
  "id": "prs_76149e8db2be257fa8a0ac01",
  "state": "done",
  "type": "pdf",
  "name": "report.pdf",
  "pages": 2,
  "markdown": "<!-- page 1 -->\n\n# Q3 report\n\nRevenue grew 12 percent in EMEA.\n\n<!-- page 2 -->\n\n# Outlook\n\nWe expect Q4 revenue to grow again.",
  "parts": [
    { "locator": { "page": 1 }, "markdown": "# Q3 report\n\nRevenue grew 12 percent in EMEA.", "ocr": true, "confidence": null },
    { "locator": { "page": 2 }, "markdown": "# Outlook\n\nWe expect Q4 revenue to grow again.", "ocr": true, "confidence": null }
  ],
  "without_text": { "pages": [], "slides": [], "images": [] }
}
```

| 옵션 | 타입 | 기능 |
| - | - | - |
| `url` | string | JSON 본문에서: 공개 주소의 `https` URL. 60초 이내에 가져오며 최대 20 MiB |
| `name`, `type`, `pages`, `password`, `layout`, `wait` | | [업로드](#옵션)와 같습니다 |

* 본문은 최대 20 MiB이며, OCR은 최대 100페이지를 읽습니다. 이후 페이지는 텍스트 레이어를 유지합니다.
* JSON 파일을 파싱하려면 `text/plain`으로 보내세요.

전체 스키마: [파일 파싱](https://docs.conare.ai/ko/api-reference/parse/parse-a-file-to-markdown.md).

### 파싱 결과 가져오기

`GET /parse/:id`

`202`(`state: "parsing"`)로 응답한 파싱은 24시간 보관됩니다. `state`가 `done`이 되거나 `error`와 함께 `failed`가 될 때까지 가져오세요.

```bash curl theme={null}
curl https://api.conare.ai/parse/prs_0e631c59528ac4f7424dc776 \
  -H "Authorization: Bearer $CONARE_API_KEY"
```

전체 스키마: [파싱 결과 읽기](https://docs.conare.ai/ko/api-reference/parse/get-a-parse-result.md).

## 결과

| 필드 | 의미 |
| - | - |
| `markdown` | 파일 전체. 각 페이지, 슬라이드, 시트는 `<!-- page 3 -->`, `<!-- slide 4 -->` 또는 `<!-- sheet "Q3" -->`로 시작합니다 |
| `parts` | 읽기 순서대로, 각각 `locator`, `markdown`, `ocr`, `confidence`를 가집니다 |
| `parts[].locator` | `{"page": 3}`, `{"slide": 4, "image": 1}`, `{"sheet": "Q3", "rows": "2-41"}` 또는 `{"part": 2, "heading": "..."}` |
| `parts[].ocr` | 텍스트 레이어가 아니라 페이지 이미지에서 OCR로 읽음 |
| `parts[].confidence` | OCR의 확신도, 0에서 1. OCR이 값을 주지 않으면 `null`(대부분의 디지털 원본 페이지) |
| `without_text` | 텍스트가 없는 `pages`, `slides`, `images`. 각 그림에는 [`reason`](https://docs.conare.ai/ko/file-types#word와-powerpoint의-그림)이 있습니다 |

Markdown 규칙은 [파일 형식](https://docs.conare.ai/ko/file-types.md#markdown)에 있습니다.

## 오류

| 오류 | 발생 시점 |
| - | - |
| `400 invalid_request` | 옵션이 유효하지 않음: 페이지가 없는 파일의 `pages`, 300을 넘는 `wait`, JSON 객체가 아닌 `metadata`, 공개 주소의 `https`가 아닌 URL |
| `400 fetch_failed` | URL이 파일과 함께 `200`으로 응답하지 않음 |
| `404 parse_not_found` | 지난 24시간 동안 해당 id로 `202`를 응답한 파싱이 없음 |
| `409 file_replaced` | 응답을 기다리는 동안 파일이 삭제됨 |
| `409 user_purging` | 사용자가 삭제되는 중 |
| `413 payload_too_large` | 512 MiB 초과(업로드) 또는 20 MiB 초과(파싱 또는 `password` 사용 시) |
| `415 unsupported_file` | 지원되지 않는 타입이거나 선언한 `type`과 다름. 메시지에 저장할 형식이 안내됩니다 |
| `422 password_protected` | 파일에 비밀번호가 있음: `password`로 보내세요 |
| `422 unreadable_file` | 파일이 손상됨 |
| `422 no_text` | 텍스트가 있는 페이지, 시트, 슬라이드, 단락, 그림이 없음 |
| `503 files_unavailable` | 지금은 파일을 저장할 수 없음. 나중에 다시 시도하세요 |

5,000개를 넘는 페이지, 시트 또는 슬라이드가 있는 파일은 `too_large`와 함께 `failed`로 끝납니다.


## Related topics

- [파일 유형과 Markdown](https://docs.conare.ai/ko/file-types.md)
- [Google Cloud Storage](https://docs.conare.ai/ko/gcs.md)
- [API 개요](https://docs.conare.ai/ko/api.md)
- [필터](https://docs.conare.ai/ko/filters.md)
- [Read a file](https://docs.conare.ai/ko/api-reference/files/read-a-file.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.