> ## 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、画像を 1 つの検索可能なドキュメントとしてアップロードするか、保存せずに Markdown へ解析します。

2 つのルートが、同じパーサー、同じオプション、同じ結果でファイルを読み取ります。

| ルート | 処理 | サイズ |
| - | - | - |
| [`POST /namespaces/:namespace/files`](#ファイルをアップロードする) | ファイルを 1 つの検索可能なドキュメントとして保存します。検索は、答えるページ、スライド、行を示します | 最大 512 MiB、5,000 ページ |
| [`POST /parse`](#ファイルを解析する) | ファイルを Markdown として返します。何も保存しません | 最大 20 MiB |

スキャンや画像は、ページ数にかかわらず OCR で読み取ります。対応形式：[ファイル形式](https://docs.conare.ai/ja/file-types.md)。

## ファイルをアップロードする

`POST /namespaces/:namespace/files`

ファイルのバイトをボディとして、マルチパートフォームのファイルパートとして、または 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/ja/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/ja/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/ja/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` | namespace のファイルソース。ドキュメント id はこれで始まります |
| `ids` | `ready` になった後の、ファイルの 1 つのドキュメント `["<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/ja/api-reference/files/read-a-file.md)。

## 保存されるドキュメント

ファイルは 1 つのドキュメント `<source_id>:<file_id>` です。ページ、スライド、シートの行、セクション、画像はその部分です。

| 場所 | 得られるもの |
| - | - |
| [検索](https://docs.conare.ai/ja/query.md) | PDF や画像のページ、スライド、シートの行範囲はそれぞれ 1 つの結果で、id は `<source_id>:<file_id>$<part>` です（`$page-3`, `$slide-4`, `$<sheet>-1`） |
| テキスト、Markdown、Word ファイルの検索 | 結果は 1 つ、ファイル `<source_id>:<file_id>` で、ファイル内のどこからでもパッセージが付きます |
| 結果の `metadata` | その部分、または最初のパッセージの位置。キーは下の表のとおりです |
| [`GET /namespaces/:namespace/documents/:id`](https://docs.conare.ai/ja/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` もあります。以前にアップロードしたファイルは、再度アップロードするまで部分ごとに 1 つのドキュメント（`<source_id>:<file_id>:page-1` など）のままの場合があります。

| 目的 | 方法 |
| - | - |
| ファイルを置き換える | 同じ id で再度アップロードします |
| 安全に再試行する | 同じファイル、名前、メタデータ、オプションなら `unchanged` が返ります。`Idempotency-Key` は不要です |
| 1 つのファイルを検索する | `{ "file_id": "report.pdf" }` で[フィルター](https://docs.conare.ai/ja/filters.md)します |
| 1 ページを検索する | `{ "file_id": "report.pdf", "page": 3 }` でフィルターします |
| ユーザーを分離する | `user` 付きでアップロードし、`user` 付きで[検索](https://docs.conare.ai/ja/query.md)します |
| 元のファイルを削除する | namespace またはそのユーザーが削除されるまで保持されます |

## ファイルを解析する

`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/ja/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/ja/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/ja/file-types#word-と-powerpoint-内の画像) が付きます |

Markdown のルールは[ファイル形式](https://docs.conare.ai/ja/file-types.md#markdown)にあります。

## エラー

| エラー | 発生条件 |
| - | - |
| `400 invalid_request` | オプションが無効です。ページのないファイルへの `pages`、300 を超える `wait`、JSON オブジェクトでない `metadata`、公開アドレス上の `https` でない URL など |
| `400 fetch_failed` | URL がファイル付きの `200` を返しませんでした |
| `404 parse_not_found` | その id で過去 24 時間以内に `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/ja/file-types.md)
- [Google Cloud Storage](https://docs.conare.ai/ja/gcs.md)
- [API の概要](https://docs.conare.ai/ja/api.md)
- [フィルター](https://docs.conare.ai/ja/filters.md)
- [TypeScript SDK](https://docs.conare.ai/ja/sdk.md)


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