> ## 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. # Query a namespace > Hybrid search over one namespace, reranked: one result per document, its text the passages of it that answer. - The body is at most 4 MiB (4,194,304 bytes). - To page, set `max_results` above `top_k`, then send `{"cursor": next_cursor}` until no `next_cursor` comes back. - Pages come from one ranking kept 15 minutes; the search counts as one query, its pages as none. ## OpenAPI ````yaml /openapi.yaml post /namespaces/{namespace}/query openapi: 3.1.0 info: title: Conare API version: '1' summary: Store your data, keep it in sync, and return the right context to your AI. description: > Write documents into namespaces, search them, and sync apps into them. - Base URL `https://api.conare.ai`; send `Authorization: Bearer sk-conare-…` (keys at conare.ai/dashboard/keys). - A multi-organization key sends `X-Conare-Org: ` on every request (`GET /organizations` lists them). - Bodies are JSON in snake_case; an unknown field is 400 `invalid_json` (`/v1` and `/v2` ignore it). Errors are `{"error": {"code", "message", "request_id"}}`. - Send every write with an `Idempotency-Key` and retry with the same key: a repeat within 24 hours replays the first answer. - 429 and 503 carry `Retry-After` (seconds). - `Conare-Degraded` marks a success that skipped or slowed part of search, e.g. `rerank` or `embed-busy`. contact: name: Conare url: https://conare.ai servers: - url: https://api.conare.ai security: - apiKey: [] tags: - name: Namespaces description: >- A namespace is a named set of documents, e.g. `docs` or `user-42`; the first write creates it. - name: Documents description: >- A document is `{ id, text, metadata }`, chunked and embedded on write; writing the same id replaces it. - name: Query description: >- Hybrid search (vector and keyword) over your namespaces, filtered by metadata and reranked. - name: Models description: >- Embed and rerank text with Conare's models, through Conare's own routes or OpenAI- and Cohere-compatible ones. - name: Sources description: Apps, buckets and custom sources, each kept in sync into one namespace. - name: Custom sources description: >- Documents you push from your own system, keyed by your `external_id`, with snapshot runs to mirror a whole set. - name: Parse description: Parse a file to Markdown without storing it. - name: Files description: >- Upload a file and Conare stores it as one document, each hit citing its page, slide, sheet rows or section. - name: Users description: >- Delete everything Conare holds of one of your users, across every namespace and source. - name: Events description: What changed, in order (`seq`), to read from a cursor. - name: Health description: Service health. - name: Organizations description: The organizations a key acts for. paths: /namespaces/{namespace}/query: parameters: - $ref: '#/components/parameters/Namespace' post: tags: - Query summary: Query a namespace description: > Hybrid search over one namespace, reranked: one result per document, its text the passages of it that answer. - The body is at most 4 MiB (4,194,304 bytes). - To page, set `max_results` above `top_k`, then send `{"cursor": next_cursor}` until no `next_cursor` comes back. - Pages come from one ranking kept 15 minutes; the search counts as one query, its pages as none. operationId: query requestBody: required: true content: application/json: schema: type: object properties: query: type: string minLength: 1 maxLength: 8000 description: >- What to search for, in plain language; required unless `cursor` is set. top_k: type: integer minimum: 1 maximum: 500 default: 10 description: How many results to return; with `cursor`, the page size. max_results: type: integer minimum: 1 maximum: 5000 description: >- Rank this many documents and return them `top_k` at a time; at most 1,000 (5,000 on a custom model's engine). cursor: type: string description: >- A previous page's `next_cursor`; only `top_k` may be sent beside it. exclude_ids: type: array maxItems: 10000 items: $ref: '#/components/schemas/DocumentId' description: >- Documents no result may be (e.g. ones already seen); a long list can return fewer results. filter: $ref: '#/components/schemas/Filter' rerank: type: boolean default: true description: Rerank the candidates with the reranking model. rerank_depth: type: integer minimum: 1 maximum: 1000 description: How many top passages to rerank (default 100). hops: type: integer minimum: 1 maximum: 2 default: 1 description: >- `2`: the best two results seed a second search, for answers that span documents; needs `rerank`, adds about 0.3 s. retrievers: type: array minItems: 1 maxItems: 2 items: type: string enum: - vector - keyword default: - vector - keyword description: >- Which retrievers to fuse: `vector` (embeddings) and `keyword` (BM25); one the namespace can't run is 400. user: $ref: '#/components/schemas/User' description: >- Only this user's documents. Combines with `filter` and `user_prefix`. user_prefix: $ref: '#/components/schemas/UserPrefix' answer: type: boolean default: false description: >- Also answer `query` in prose; a language model writes the answer from the best passages, adding about 2 s. example: query: how do refunds work? top_k: 5 filter: team: support responses: '200': description: Results, best first. headers: Conare-Degraded: $ref: '#/components/headers/ConareDegraded' Conare-Embed-Busy-Ms: $ref: '#/components/headers/ConareEmbedBusyMs' content: application/json: schema: type: object required: - results - took_ms properties: answer: type: string description: >- With `answer: true`, the answer; missing when nothing matched or with `Conare-Degraded: answer`. results: type: array items: $ref: '#/components/schemas/QueryResult' next_cursor: type: string description: >- With `max_results`, the cursor to the next page; missing on the last page. took_ms: type: integer description: Time spent in Conare, in milliseconds. example: results: - id: refunds text: Refunds are available for 30 days after purchase. score: 0.91 reranked: true metadata: team: support took_ms: 42 '400': $ref: '#/components/responses/Error' '401': $ref: '#/components/responses/Error' '404': $ref: '#/components/responses/Error' '413': $ref: '#/components/responses/Error' '429': $ref: '#/components/responses/Error' '503': $ref: '#/components/responses/Error' components: parameters: Namespace: name: namespace in: path required: true description: The namespace name. schema: $ref: '#/components/schemas/NamespaceName' schemas: DocumentId: type: string pattern: ^[A-Za-z0-9][A-Za-z0-9._:-]{0,255}$ description: >- 1-256 characters of `A-Z a-z 0-9 . _ : -`, starting with a letter or digit. examples: - refunds - hubspot:contacts:1042 Filter: type: object description: > `{"key": value}` matches equal values (or arrays holding it); `$eq`, `$ne`, `$in`, `$nin`, `$gt`, `$gte`, `$lt` and `$lte` compare, `$and` and `$or` combine. - A filter holds at most 256 conditions (each value, `$in` item, range and join counts one), else 400 `invalid_filter`. - Ranges compare numbers with numbers and strings by UTF-8 bytes: write dates alike (`2025-06-01`) to sort them. - `$ne` and `$nin` work in queries, not deletes, and match documents without the key. properties: $and: type: array items: $ref: '#/components/schemas/Filter' $or: type: array items: $ref: '#/components/schemas/Filter' additionalProperties: oneOf: - $ref: '#/components/schemas/FilterValue' - $ref: '#/components/schemas/FilterOperators' examples: - team: support - $or: - team: support - year: $in: - 2024 - 2025 - year: $gte: 2020 $lt: 2025 - published_at: $gte: '2025-06-01' - company: $nin: - acme - globex User: type: string pattern: ^[A-Za-z0-9][A-Za-z0-9._:@-]{0,127}$ description: >- A user id of yours, with at most 8 `:`; group users with `:` (`tenant-7:u_42`) and query a group by `user_prefix`. examples: - tenant-7:u_42 UserPrefix: type: string pattern: ^[A-Za-z0-9][A-Za-z0-9._:@-]{0,127}$ description: >- Only the documents of users starting with this; it ends in `:`, e.g. `tenant-7:`. examples: - 'tenant-7:' QueryResult: type: object required: - id - text - score - reranked - metadata properties: id: $ref: '#/components/schemas/DocumentId' text: type: string description: >- The passages of the document that answer, best first: its best matching passage and up to two more that match nearly as well. Passages that do not follow each other in the document are joined by a line holding only `…`. score: type: number description: >- Higher is better. Reranked and unreranked scores are on different scales. reranked: type: boolean description: >- The reranker scored this result; false past `rerank_depth`, with `rerank: false`, or if reranking failed. metadata: $ref: '#/components/schemas/Metadata' user: $ref: '#/components/schemas/User' NamespaceName: type: string pattern: ^[a-z0-9][a-z0-9_-]{0,63}$ description: 1-64 characters of `a-z 0-9 _ -`, starting with a letter or digit. examples: - docs - user-42 FilterValue: oneOf: - type: string - type: number - type: boolean FilterOperators: type: object minProperties: 1 additionalProperties: false properties: $eq: $ref: '#/components/schemas/FilterValue' $ne: $ref: '#/components/schemas/FilterValue' $in: type: array minItems: 1 maxItems: 255 description: >- The values to match; with the `$in` itself they fill the 256-condition budget. items: $ref: '#/components/schemas/FilterValue' $nin: type: array minItems: 1 maxItems: 255 description: The values to rule out, counted as `$in`'s. items: $ref: '#/components/schemas/FilterValue' $gt: $ref: '#/components/schemas/RangeBound' $gte: $ref: '#/components/schemas/RangeBound' $lt: $ref: '#/components/schemas/RangeBound' $lte: $ref: '#/components/schemas/RangeBound' Metadata: type: object maxProperties: 32 description: > Strings, numbers, booleans or string arrays, for filtering; else 400 `invalid_metadata`. - At most 256 indexed values: an array item or a boolean counts one, a number or a string up to 222 bytes two. propertyNames: pattern: ^[A-Za-z][A-Za-z0-9_.-]{0,63}$ not: enum: - id - text - vector - ttl_at_ms additionalProperties: oneOf: - type: string maxLength: 4096 description: At most 4,096 bytes of UTF-8. - type: number description: Within a 64-bit float's range (`1e309` is 400 `invalid_metadata`). - type: boolean - type: array maxItems: 256 items: type: string maxLength: 4096 description: At most 4,096 bytes of UTF-8. Error: type: object required: - error properties: error: type: object required: - code - message - request_id properties: code: type: string description: > Stable, machine-readable, by status: - 400: `invalid_request`, `fetch_failed`, `invalid_json`, `invalid_namespace`, `invalid_id`, `invalid_metadata`, `invalid_filter`, `invalid_cursor`, `invalid`, `md5_mismatch`, `idempotency_key_required`, `invalid_path` - 401: `unauthorized`, `invalid_upload` - 402 (billed calls only): `credits_exhausted`, `spend_cap_reached`, `monthly_limit_reached`, `payment_failed` - 403: `forbidden`, `namespace_forbidden`, `key_scope_models_only`, `namespace_not_allowed` - 404: `namespace_not_found`, `document_not_found`, `source_not_found`, `model_not_found`, `key_not_found`, `file_not_found`, `parse_not_found`, `not_found` - 405: `method_not_allowed` - 409: `version_conflict`, `conflict`, `idempotency_in_progress`, `run_active`, `run_not_receiving`, `source_deleting`, `user_purging`, `upload_incomplete`, `namespace_has_sources`, `too_many_exclusions`, `push_source`, `pull_source`, `files_source`, `no_original`, `file_replaced`, `gcs_bucket_claimed`, `limit_reached` - 410: `upload_expired`, `model_retired` - 413: `payload_too_large`, `too_large` - 415: `unsupported_file`, `type_mismatch`, `unsupported_encoding` - 422: `idempotency_key_reused`, `no_text`, `unreadable_file`, `password_protected`, `gcs_access_denied`, `gcs_not_verified`, `gcs_bucket_not_found` - 429: `rate_limited` - 500: `internal_error`; 502: `upstream_error`; 501: `models_only` - 503: `unavailable`, `sources_unavailable`, `timeout`, `embed_unavailable`, `sync_storage_unavailable`, `sync_unconfigured`, `files_unconfigured`, `files_unavailable`, `gcs_unconfigured`, `gcs_unavailable`, `gcs_auth_failed` message: type: string request_id: type: string RangeBound: description: >- A number, or a string of at most 222 bytes of UTF-8 (a longer bound is 400 `invalid_filter`). oneOf: - type: number - type: string headers: ConareDegraded: description: > Set when a request succeeded without part of search, or slower; comma-separated values: - `rerank`: results not reranked. `rerank-partial`: the rerank partly finished under load; usable, and a retry adds load. - `embed`: no vector retrieval. `embed-busy`: waited on a full embedding queue (`Conare-Embed-Busy-Ms`). `embed-fallback`: a backup served identical vectors. - `keyword`: no keyword retrieval. `keyword-terms`: keyword retrieval read only a long query's first words. - `cursor`: a paged search's first page came without `next_cursor`; search again for the rest. - `answer`: the answer model was unavailable; results only. schema: type: string example: rerank,embed-fallback ConareEmbedBusyMs: description: >- With `Conare-Degraded: embed-busy`, the milliseconds spent waiting; on writes, lower your concurrency until it goes away. schema: type: integer minimum: 1 example: 8400 responses: Error: description: An error. `X-Request-Id` is also in the response headers. headers: X-Request-Id: schema: type: string Retry-After: description: Seconds to wait before retrying (429, 503). schema: type: integer content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: invalid_request message: text is required request_id: 7d0f4c1e-2b8a-4e39-9a61-3c5e8b2f9d04 securitySchemes: apiKey: type: http scheme: bearer bearerFormat: sk-conare-… description: >- A key from conare.ai/dashboard/keys with full access, some namespaces, or models only (`/embed`, `/rerank`, `/v1`, `/v2/rerank`, `/parse`). ```` ## Related topics - [Búsqueda](https://docs.conare.ai/es/query.md) - [Query every namespace](https://docs.conare.ai/es/api-reference/query/query-every-namespace.md) - [Namespaces](https://docs.conare.ai/es/namespaces.md) - [List namespaces](https://docs.conare.ai/es/api-reference/namespaces/list-namespaces.md) - [SDK de TypeScript](https://docs.conare.ai/es/sdk.md) This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.