> ## 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.

# كتابة المستندات

> أضف ما يصل إلى 100 مستند أو استبدلها في مساحة أسماء؛ تصبح قابلة للبحث عند عودة الاستدعاء.

`POST /namespaces/:namespace/documents`

اكتب المستندات في مساحة أسماء: يقسّمها Conare إلى مقاطع ويضمّنها ويفهرسها، وأول كتابة تُنشئ مساحة الأسماء.

```bash curl theme={null}
curl https://api.conare.ai/namespaces/docs/documents \
  -H "Authorization: Bearer $CONARE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "documents": [
      { "id": "refunds", "text": "Refunds are available for 30 days.", "metadata": { "team": "support" } },
      { "id": "shipping", "text": "Orders ship within two days.", "metadata": { "team": "ops" } }
    ]
  }'
```

```ts TypeScript theme={null}
await docs.write([
  { id: "refunds", text: "Refunds are available for 30 days.", metadata: { team: "support" } },
  { id: "shipping", text: "Orders ship within two days.", metadata: { team: "ops" } },
]);
```

```json Response theme={null}
{
  "ids": ["refunds", "shipping"],
  "results": [
    { "id": "refunds", "result": "created", "version": 1, "chunks": 1, "chunks_embedded": 1 },
    { "id": "shipping", "result": "created", "version": 1, "chunks": 1, "chunks_embedded": 1 }
  ],
  "versions": [1, 1]
}
```

## الخيارات

| الخيار | النوع | ما يفعله |
| - | - | - |
| `documents` | array، مطلوب | من 1 إلى 100 مستند |
| `id` | string | حتى 256 حرفًا من `A-Z a-z 0-9 . _ : -`؛ يُولَّد إذا لم يُحدَّد. كتابة معرّف موجود تستبدله |
| `text` | string، مطلوب | أي طول ضمن جسم الطلب البالغ 32 MiB؛ ويبقى النص الطويل مستندًا واحدًا |
| `metadata` | object | قيم [للتصفية](https://docs.conare.ai/ar/filters.md) بها ([القواعد](#البيانات-الوصفية)) |
| `user` | string | المستخدم الذي ينتمي إليه المستند ([المستخدمون](#المستخدمون)) |
| `seq` | integer | رقم الإصدار الخاص بك، من 0 إلى 2^53؛ يُتخطّى `seq` الأقل من المخزَّن |
| `if_version` | integer | الكتابة فقط إذا طابق `version` المخزَّن؛ `0` يكتب مستندًا جديدًا فقط |

المخطط الكامل: [إضافة المستندات](https://docs.conare.ai/ar/api-reference/documents/add-documents.md).

## الاستجابة

| الحقل | المعنى |
| - | - |
| `ids`، `versions` | معرّف كل مستند وإصداره، بترتيب الطلب |
| `results[].result` | `created` أو `updated` أو `unchanged` (النص والبيانات الوصفية والمستخدم نفسها) أو `stale` (مخزَّن `seq` أعلى) |
| `results[].chunks` | المقاطع التي يحتويها المستند |
| `results[].chunks_embedded` | المقاطع التي ضمّنتها هذه الكتابة؛ لا يُعاد تضمين المقاطع غير المتغيّرة |
| `results[].stored_seq` | مع `stale`، قيمة `seq` المخزَّنة |

عدم تطابق `if_version` يُرجع `409 version_conflict`.

## البيانات الوصفية

```json theme={null}
{ "team": "support", "year": 2025, "public": true, "tags": ["billing", "refunds"] }
```

| القاعدة | الحد |
| - | - |
| القيم | سلاسل نصية أو أرقام أو قيم منطقية أو مصفوفات من السلاسل النصية |
| المفاتيح | حتى 32، كلٌّ منها من 1 إلى 64 حرفًا من `A-Z a-z 0-9 _ . -`، ويبدأ بحرف |
| المفاتيح المحجوزة | `id`، `text`، `vector`، `ttl_at_ms` |
| السلسلة النصية | حتى 4 KiB |
| المصفوفة | حتى 256 سلسلة نصية |
| القيم المميّزة لكل مستند | 256 إجمالًا: الرقم أو السلسلة النصية حتى 222 بايت تُحتسب اثنتين؛ وعنصر المصفوفة أو القيمة المنطقية أو السلسلة الأطول واحدة؛ و`user` واحدة، زائد واحدة لكل `:` |

## المستخدمون

عيّن `user` عندما تحتوي مساحة أسماء واحدة على مستندات مستخدمين كثيرين، ثم [ابحث](https://docs.conare.ai/ar/query.md) باستخدام `user` أو `user_prefix`.

| القاعدة | |
| - | - |
| الصيغة | حتى 128 حرفًا من `A-Z a-z 0-9 . _ : @ -`، تبدأ بحرف أو رقم، وبحد أقصى 8 من `:` |
| المجموعات | اكتب `tenant-7:u_42`، وابحث بـ `user_prefix: "tenant-7:"` للمستأجر كله |
| عوامل التصفية | لا يمكن [لعامل التصفية](https://docs.conare.ai/ar/filters.md) مطابقة `user`؛ استخدم `user` و`user_prefix` |

## الإنتاجية

* عندما يكون التضمين مشغولًا، تنتظر الكتابة وتُرجع `Conare-Degraded: embed-busy`: أرسل عددًا أقل من الكتابات في آنٍ واحد.
* بعد نحو 30 ثانية، تُرجع `503` مع `Retry-After`.
* قد يكون الطلب الفاشل قد كتب بعض المستندات: أعد محاولته باستخدام [`Idempotency-Key`](https://docs.conare.ai/ar/api#إعادة-المحاولات) نفسه.


## Related topics

- [مقدمة](https://docs.conare.ai/ar/index.md)
- [مساحات الأسماء](https://docs.conare.ai/ar/namespaces.md)
- [جلب المستندات وسردها وحذفها](https://docs.conare.ai/ar/documents.md)
- [نظرة عامة على الواجهة البرمجية](https://docs.conare.ai/ar/api.md)
- [المرشّحات](https://docs.conare.ai/ar/filters.md)


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