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

# البحث

> اعثر على المقاطع التي تجيب عن سؤال، حسب المعنى والكلمات المفتاحية، مع إعادة الترتيب.

`POST /namespaces/:namespace/query`

ابحث في مساحة أسماء حسب المعنى والكلمات المفتاحية؛ يعيد Conare ترتيب أفضل التطابقات ويعيد، لكل مستند، المقاطع التي تجيب.

```bash curl theme={null}
curl https://api.conare.ai/namespaces/docs/query \
  -H "Authorization: Bearer $CONARE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "how do refunds work?", "top_k": 5, "filter": {"team": "support"}}'
```

```ts TypeScript theme={null}
const results = await docs.query("how do refunds work?", {
  topK: 5,
  filter: { team: "support" },
});
```

```json Response theme={null}
{
  "results": [
    {
      "id": "refunds",
      "text": "Refunds are available for 30 days.",
      "score": 0.3192,
      "reranked": true,
      "metadata": { "team": "support" }
    }
  ],
  "took_ms": 62
}
```

## الخيارات

| الخيار | النوع | الوظيفة |
| - | - | - |
| `query` | string، مطلوب | السؤال، حتى 8,000 حرف |
| `top_k` | integer، الافتراضي 10 | عدد النتائج المُعادة، من 1 إلى 500 |
| `filter` | object | [مرشّح بيانات وصفية](https://docs.conare.ai/ar/filters.md) |
| `user` | string | مستندات هذا [المستخدم](https://docs.conare.ai/ar/write.md#المستخدمون) فقط |
| `user_prefix` | string | المستخدمون الذين يبدأ اسمهم بهذه القيمة فقط، مثل `tenant-7:` |
| `answer` | boolean، الافتراضي `false` | [يكتب إجابة](#الإجابات) أيضًا |
| `rerank` | boolean، الافتراضي `true` | يعيد ترتيب أفضل التطابقات؛ `false` أسرع |
| `rerank_depth` | integer، الافتراضي 20 | عدد المقاطع الأعلى المُعاد ترتيبها، من 1 إلى 1,000 |
| `hops` | integer، الافتراضي 1 | `2` يبحث مجددًا انطلاقًا من أفضل النتائج ([قفزتان](#قفزتان)) |
| `retrievers` | array، الافتراضي `["vector", "keyword"]` | واحد أو اثنان من `vector` (المعنى) و`keyword` |
| `exclude_ids` | array | حتى 10,000 معرّف مستند لاستبعادها |
| `max_results` | integer | [تصفّح](#الصفحات) حتى 1,000 نتيجة، أو 5,000 مع نموذج مخصص |
| `cursor` | string | `next_cursor` الخاص بالصفحة السابقة |

المخطط الكامل: [الاستعلام في مساحة أسماء](https://docs.conare.ai/ar/api-reference/query/query-a-namespace.md).

## الاستجابة

| الحقل | المعنى |
| - | - |
| `results` | الأفضل أولًا، نتيجة واحدة لكل مستند |
| `results[].id`، `metadata`، `user` | الخاصة بالمستند |
| `results[].text` | مقاطعه التي تجيب، الأفضل أولًا: أفضلها وحتى مقطعين آخرين يطابقان بدرجة قريبة، كل منها حتى نحو 3,000 بايت، مع سطر لا يحوي إلا `…` بين المقاطع غير المتتالية؛ [اجلب المستند](https://docs.conare.ai/ar/documents.md) للحصول عليه كاملًا |
| `results[].score` | الأعلى أفضل؛ قارن ضمن استعلام واحد فقط |
| `results[].reranked` | هل قيّمه مُعيد الترتيب؛ تأتي النتائج غير المُعاد ترتيبها في الأخير |
| `answer` | الإجابة، مع `answer: true` |
| `next_cursor` | مع `max_results`، قيمة `cursor` للصفحة التالية؛ يُحذف في الصفحة الأخيرة |
| `took_ms` | زمن البحث بالميلي ثانية |

## الإجابات

يضيف `"answer": true` إجابة مكتوبة من أفضل المقاطع، في نحو ثانيتين إضافيتين.

```json Response theme={null}
{
  "answer": "Refunds are available for 30 days (source dated 2026-10-21). No further details on the refund process, conditions, or method were found in this search.",
  "results": [ ... ],
  "took_ms": 1546
}
```

* يكتبها نموذج لغوي من المقاطع التي عُثر عليها؛ راجع [سياسة الخصوصية](https://conare.ai/privacy).
* إذا لم يكن ذلك النموذج متاحًا، تحصل على النتائج دون `answer`.

## قفزتان

يبحث `"hops": 2` مجددًا انطلاقًا من أفضل النتائج، للأسئلة التي تحتاج إجابتها إلى حقائق من مستندين.

```bash curl theme={null}
curl https://api.conare.ai/namespaces/films/query \
  -H "Authorization: Bearer $CONARE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "where was the director of The Long Harbor born?", "hops": 2}'
```

* يضيف نحو 0.3 ثانية: استخدمه للأسئلة التي تربط الحقائق ببعضها.
* يعيد `400 invalid_request` مع `rerank: false`، ومع `max_results`، وفي مساحات أسماء النماذج المخصصة.

## الصفحات

| الخطوة | أرسل |
| - | - |
| الصفحة الأولى | `query` و`max_results` (عدد النتائج المُرتَّبة مرة واحدة) و`top_k` (حجم الصفحة) |
| الصفحات التالية | `cursor` فقط (آخر `next_cursor`) و`top_k` |
| الصفحة الأخيرة | لا تحتوي على `next_cursor` |

يدوم المؤشر 15 دقيقة. تقرأ الدالة `queryPages()` في SDK كل الصفحات.

## البحث في كل مساحات الأسماء

`POST /query`

الطلب نفسه عبر ما يصل إلى 100 مساحة أسماء، مع إعادة ترتيب النتائج معًا؛ يقصر `prefix` البحث على مساحات الأسماء التي تبدأ أسماؤها به.

```bash curl theme={null}
curl https://api.conare.ai/query \
  -H "Authorization: Bearer $CONARE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "how do refunds work?", "prefix": "acme-"}'
```

```json Response theme={null}
{
  "namespaces": ["acme-docs"],
  "results": [
    {
      "namespace": "acme-docs",
      "id": "refunds",
      "text": "Refunds are available for 30 days.",
      "score": 0.3471,
      "reranked": true,
      "metadata": { "team": "support" }
    }
  ],
  "skipped_namespaces": [],
  "took_ms": 64
}
```

| الخيار أو الحقل | هنا |
| - | - |
| `prefix` | مساحات الأسماء التي تبدأ أسماؤها بهذه القيمة فقط |
| `rerank_depth` | الافتراضي 60، من 1 إلى 1,000 |
| `exclude_ids` | يُكتب بصيغة `namespace/id` |
| `results[].namespace` | مساحة أسماء النتيجة |
| `namespaces`، `skipped_namespaces` | التي بُحث فيها، والتي تجاوزت أول 100 |

يعمل `hops` هنا أيضًا. المخطط الكامل: [الاستعلام في كل مساحات الأسماء](https://docs.conare.ai/ar/api-reference/query/query-every-namespace.md).

## النتائج المنقوصة

إذا فشل جزء من البحث، يظل الاستعلام ناجحًا ويوضّح الترويسة `Conare-Degraded` ما تم تخطيه.

| القيمة | المعنى |
| - | - |
| `rerank`، `rerank-partial` | لم يُعَد ترتيب بعض النتائج أو كلها (`reranked: false`) |
| `embed` | بُحث بالكلمات المفتاحية فقط |
| `keyword`، `keyword-terms` | كان الاستعلام أطول من أن يقرأه البحث بالكلمات المفتاحية كاملًا |
| `embed-next` | تعذّر البحث في جزء من مساحة الأسماء |
| `cursor` | لا يوجد `next_cursor`؛ ابحث مجددًا للحصول على صفحات أخرى |
| `embed-busy`، `embed-fallback` | أبطأ من المعتاد؛ النتائج غير متأثرة |
| `answer` | لا إجابة، النتائج فقط |

إذا تعذّر البحث كليًا، يعيد الاستعلام `503`.


## Related topics

- [وحدة التحكم](https://docs.conare.ai/ar/console.md)
- [البدء السريع](https://docs.conare.ai/ar/quickstart.md)
- [Query a namespace](https://docs.conare.ai/ar/api-reference/query/query-a-namespace.md)
- [Query every namespace](https://docs.conare.ai/ar/api-reference/query/query-every-namespace.md)
- [التضمين وإعادة الترتيب](https://docs.conare.ai/ar/embed-rerank.md)


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