> ## 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 أو CSV أو نص أو صورة كمستند واحد قابل للبحث، أو حلّله إلى Markdown دون تخزين أي شيء.

يقرأ مساران الملفات بمحلّل واحد، وبالخيارات نفسها والنتيجة نفسها:

| المسار | الوظيفة | الحجم |
| - | - | - |
| [`POST /namespaces/:namespace/files`](#رفع-ملف) | يخزّن الملف كمستند واحد قابل للبحث؛ ويذكر البحث الصفحة أو الشريحة أو الصفوف التي تجيب | حتى 512 MiB و5,000 صفحة |
| [`POST /parse`](#تحليل-ملف) | يعيد الملف بصيغة Markdown؛ لا يخزّن شيئًا | حتى 20 MiB |

تُقرأ المسوحات الضوئية والصور بتقنية OCR، مهما بلغ عدد الصفحات. الصيغ المدعومة: [أنواع الملفات](https://docs.conare.ai/ar/file-types.md).

## رفع ملف

`POST /namespaces/:namespace/files`

أرسل بايتات الملف كجسم الطلب، أو كجزء ملف في نموذج multipart، أو كـ JSON `{"url": "https://..."}` ليجلبه Conare.

```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` ثانية لقراءة الملف: `200` عندما يكون `ready` أو `failed`، وإلا `202` أثناء قراءته.

### الخيارات

معاملات الاستعلام، على المسارين ما لم يُذكر خلاف ذلك.

| الخيار | النوع | الوظيفة |
| - | - | - |
| `name` | string | اسم الملف، حتى 4,096 حرفًا؛ امتداده يميّز `.csv` و`.tsv` و`.md` عن النص |
| `id` | string | للرفع فقط. معرّف الملف، وهو نهاية معرّف مستنده؛ القيمة الافتراضية `name` مع استبدال الأحرف الأخرى بـ `-` |
| `type` | string | `pdf` و`docx` و`pptx` و`xlsx` و`csv` و`png` و... ([الكل](https://docs.conare.ai/ar/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/ar/file-types.md#كتل-التخطيط)) |
| `wait` | ثوانٍ، الافتراضي 60 | مدة انتظار القراءة قبل `202`، حتى 300؛ `0` يجيب فورًا |

* يحدّد `Content-Type` مثل `application/pdf` النوع أيضًا.
* `wait`: القيمة `true` تساوي 60؛ تصل الإجابة دائمًا خلال 105 ثوانٍ. عند الرفع، يجيب `false` بمجرد تخزين النص، مع `ocr_pending`.
* الصفحة خارج `pages` لا تُقرأ ولا تمر عبر OCR؛ واستخدام `pages` على ملف بلا صفحات يعيد `400`.

المخطط الكامل: [رفع ملف](https://docs.conare.ai/ar/api-reference/files/upload-a-file.md).

### الاستجابة

| الحقل | المعنى |
| - | - |
| `file_id`، `name`، `type` | المعرّف المستخدم، والاسم، والنوع المقروء (`image` لكل صيغ الصور) |
| `state` | `queued` أو `parsing` أو `ocr` (لا يزال OCR يقرأ `ocr_pending`) أو `ready` أو `failed` مع `error` |
| `source_id` | مصدر الملفات في مساحة الأسماء؛ يبدأ به معرّف المستند |
| `ids` | مستند الملف الوحيد، `["<source_id>:<file_id>"]`، بمجرد `ready` |
| `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/ar/api-reference/files/read-a-file.md).

## المستندات المخزّنة

الملف مستند واحد، `<source_id>:<file_id>`؛ وصفحاته وشرائحه وصفوف أوراقه وأقسامه وصوره هي أجزاؤه.

| أين | ما تحصل عليه |
| - | - |
| [البحث](https://docs.conare.ai/ar/query.md) | صفحة ملف PDF أو صورة، أو شريحة، أو نطاق صفوف في ورقة، نتيجةٌ مستقلة بالمعرّف `<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/ar/documents#جلب-مستند) | بمعرّف الملف، نص الملف كاملًا مع سطر فارغ بين الصفحات؛ وبمعرّف جزء، ذلك الجزء وحده |

### موضع الجزء

| الملف | الموقع في البيانات الوصفية |
| - | - |
| 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: true` عندما قرأه OCR. وقد يبقى الملف المرفوع سابقًا مستندًا لكل جزء، مثل `<source_id>:<file_id>:page-1`، حتى يُرفع مجددًا.

| لكي | افعل |
| - | - |
| تستبدل ملفًا | ارفعه مجددًا بالمعرّف نفسه |
| تعيد المحاولة بأمان | الملف نفسه بالاسم والبيانات الوصفية والخيارات نفسها يجيب `unchanged`، دون الحاجة إلى `Idempotency-Key` |
| تبحث في ملف واحد | [صفِّ](https://docs.conare.ai/ar/filters.md) على `{ "file_id": "report.pdf" }` |
| تبحث في صفحة واحدة | صفِّ على `{ "file_id": "report.pdf", "page": 3 }` |
| تفصل بين المستخدمين | ارفع مع `user`، و[ابحث](https://docs.conare.ai/ar/query.md) مع `user` |
| تحذف الأصل | يُحتفظ به حتى تُحذف مساحة الأسماء أو مستخدمه |

## تحليل ملف

`POST /parse`

يعيد الملف بصيغة Markdown ولا يخزّن شيئًا؛ يمكن لأي مفتاح التحليل، حتى مفتاح Models فقط.

```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: عنوان URL بـ `https` على عنوان عام، يُجلب خلال 60 ثانية، حتى 20 MiB |
| `name`، `type`، `pages`، `password`، `layout`، `wait` | | كما في [الرفع](#الخيارات) |

* يصل جسم الطلب حتى 20 MiB، ويقرأ OCR حتى 100 صفحة؛ تحتفظ الصفحات اللاحقة بطبقة نصها.
* لتحليل ملف JSON، أرسله كـ `text/plain`.

المخطط الكامل: [تحليل ملف](https://docs.conare.ai/ar/api-reference/parse/parse-a-file-to-markdown.md).

### جلب تحليل

`GET /parse/:id`

يُحتفظ بالتحليل الذي أجاب بـ `202` (`state: "parsing"`) لمدة 24 ساعة: اجلبه حتى يصبح `state` هو `done`، أو `failed` مع `error` الخاص به.

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

المخطط الكامل: [قراءة تحليل](https://docs.conare.ai/ar/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؛ `null` عندما لم يقدّم OCR قيمة (معظم الصفحات الرقمية الأصل) |
| `without_text` | `pages` و`slides` و`images` التي لا تحتوي نصًا، وكل صورة مع [`reason`](https://docs.conare.ai/ar/file-types#الصور-في-word-وpowerpoint) الخاص بها |

قواعد Markdown موجودة في [أنواع الملفات](https://docs.conare.ai/ar/file-types.md#markdown).

## الأخطاء

| الخطأ | متى |
| - | - |
| `400 invalid_request` | خيار غير صالح: `pages` على ملف بلا صفحات، أو `wait` أكبر من 300، أو `metadata` ليس كائن JSON، أو عنوان URL ليس `https` على عنوان عام |
| `400 fetch_failed` | لم يُجب عنوان URL بـ `200` مع الملف |
| `404 parse_not_found` | لا يوجد تحليل بهذا المعرّف أجاب بـ `202` خلال آخر 24 ساعة |
| `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 صفحة أو ورقة أو شريحة بحالة `failed` مع `too_large`.


## Related topics

- [أنواع الملفات وMarkdown](https://docs.conare.ai/ar/file-types.md)
- [Google Cloud Storage](https://docs.conare.ai/ar/gcs.md)
- [Read a file](https://docs.conare.ai/ar/api-reference/files/read-a-file.md)
- [Upload a file](https://docs.conare.ai/ar/api-reference/files/upload-a-file.md)
- [البدء السريع](https://docs.conare.ai/ar/quickstart.md)


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