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

# Suche

> Finden Sie die Passagen, die eine Frage beantworten, nach Bedeutung und Schlüsselwort, mit Reranking.

`POST /namespaces/:namespace/query`

Durchsuchen Sie einen Namespace nach Bedeutung und nach Schlüsselwort; Conare rerankt die besten Treffer und gibt für jedes Dokument die Passagen zurück, die antworten.

```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
}
```

## Optionen

| Option | Typ | Funktion |
| - | - | - |
| `query` | string, erforderlich | Die Frage, bis zu 8.000 Zeichen |
| `top_k` | integer, Standard 10 | Zurückzugebende Ergebnisse, 1–500 |
| `filter` | object | Ein [Metadatenfilter](https://docs.conare.ai/de/filters.md) |
| `user` | string | Nur die Dokumente dieses [Benutzers](https://docs.conare.ai/de/write.md#nutzer) |
| `user_prefix` | string | Nur Benutzer, die damit beginnen, etwa `tenant-7:` |
| `answer` | boolean, Standard `false` | Zusätzlich [eine Antwort schreiben](#antworten) |
| `rerank` | boolean, Standard `true` | Die besten Treffer reranken; `false` ist schneller |
| `rerank_depth` | integer, Standard 20 | Zu rerankende Top-Passagen, 1–1.000 |
| `hops` | integer, Standard 1 | `2` sucht erneut ausgehend von den besten Ergebnissen ([zwei Hops](#zwei-hops)) |
| `retrievers` | array, Standard `["vector", "keyword"]` | 1 oder 2 aus `vector` (Bedeutung) und `keyword` |
| `exclude_ids` | array | Bis zu 10.000 auszuschließende Dokument-IDs |
| `max_results` | integer | Bis zu 1.000 Ergebnisse [seitenweise](#seiten) abrufen, oder 5.000 mit einem eigenen Modell |
| `cursor` | string | Der `next_cursor` der vorherigen Seite |

Vollständiges Schema: [Einen Namespace abfragen](https://docs.conare.ai/de/api-reference/query/query-a-namespace.md).

## Antwort

| Feld | Bedeutung |
| - | - |
| `results` | Das beste zuerst, eines pro Dokument |
| `results[].id`, `metadata`, `user` | Die des Dokuments |
| `results[].text` | Seine Passagen, die antworten, die beste zuerst: die beste und bis zu zwei weitere, die fast genauso gut passen, jeweils bis zu etwa 3.000 Bytes, mit einer Zeile nur mit `…` zwischen Passagen, die nicht aufeinander folgen; [rufen Sie das Dokument ab](https://docs.conare.ai/de/documents.md), um alles zu erhalten |
| `results[].score` | Höher ist besser; nur innerhalb einer Anfrage vergleichen |
| `results[].reranked` | Ob der Reranker es bewertet hat; nicht gererankte Ergebnisse kommen zuletzt |
| `answer` | Die Antwort, mit `answer: true` |
| `next_cursor` | Mit `max_results` der `cursor` der nächsten Seite; fehlt auf der letzten Seite |
| `took_ms` | Suchdauer in Millisekunden |

## Antworten

`"answer": true` fügt eine aus den besten Passagen geschriebene Antwort hinzu, in etwa 2 Sekunden zusätzlich.

```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
}
```

* Ein Sprachmodell schreibt sie aus den gefundenen Passagen; siehe die [Datenschutzerklärung](https://conare.ai/privacy).
* Ist dieses Modell nicht verfügbar, erhalten Sie die Ergebnisse ohne `answer`.

## Zwei Hops

`"hops": 2` sucht erneut ausgehend von den besten Ergebnissen, für Fragen, deren Antwort Fakten aus zwei Dokumenten braucht.

```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}'
```

* Es kostet etwa 0,3 Sekunden mehr: Nutzen Sie es für Fragen, die Fakten verketten.
* Es gibt `400 invalid_request` zurück mit `rerank: false`, mit `max_results` und bei Namespaces eines eigenen Modells.

## Seiten

| Schritt | Senden |
| - | - |
| Erste Seite | `query`, `max_results` (wie viele einmalig gerankt werden) und `top_k` (Seitengröße) |
| Nächste Seiten | Nur `cursor` (der letzte `next_cursor`) und `top_k` |
| Letzte Seite | Hat keinen `next_cursor` |

Ein Cursor gilt 15 Minuten. `queryPages()` im SDK liest jede Seite.

## Alle Namespaces durchsuchen

`POST /query`

Dieselbe Anfrage über bis zu 100 Namespaces, gemeinsam gererankt; `prefix` beschränkt sie auf Namespaces, deren Namen damit beginnen.

```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
}
```

| Option oder Feld | Hier |
| - | - |
| `prefix` | Nur Namespaces, deren Namen damit beginnen |
| `rerank_depth` | Standard 60, 1–1.000 |
| `exclude_ids` | Geschrieben als `namespace/id` |
| `results[].namespace` | Der Namespace des Ergebnisses |
| `namespaces`, `skipped_namespaces` | Die durchsuchten und die über die ersten 100 hinaus |

`hops` funktioniert auch hier. Vollständiges Schema: [Alle Namespaces abfragen](https://docs.conare.ai/de/api-reference/query/query-every-namespace.md).

## Eingeschränkte Ergebnisse

Schlägt ein Teil einer Suche fehl, gelingt die Anfrage trotzdem, und der Header `Conare-Degraded` gibt an, was übersprungen wurde.

| Wert | Bedeutung |
| - | - |
| `rerank`, `rerank-partial` | Einige oder alle Ergebnisse wurden nicht gererankt (`reranked: false`) |
| `embed` | Nur nach Schlüsselwort gesucht |
| `keyword`, `keyword-terms` | Die Anfrage war zu lang, als dass die Schlüsselwortsuche sie vollständig lesen konnte |
| `embed-next` | Ein Teil des Namespace konnte nicht durchsucht werden |
| `cursor` | Kein `next_cursor`; suchen Sie erneut für weitere Seiten |
| `embed-busy`, `embed-fallback` | Langsamer als üblich; die Ergebnisse sind nicht betroffen |
| `answer` | Keine Antwort, nur Ergebnisse |

Konnte gar nichts suchen, gibt die Anfrage `503` zurück.


## Related topics

- [Query a namespace](https://docs.conare.ai/de/api-reference/query/query-a-namespace.md)
- [Query every namespace](https://docs.conare.ai/de/api-reference/query/query-every-namespace.md)
- [TypeScript SDK](https://docs.conare.ai/de/sdk.md)
- [Filter](https://docs.conare.ai/de/filters.md)
- [Schnellstart](https://docs.conare.ai/de/quickstart.md)


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