> ## 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. # Query a namespace > Hybrid search (vector and keyword) over one namespace, optionally filtered by metadata, reranked. Returns one result per document: its best matching passage. ## OpenAPI ````yaml /api/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, query them with hybrid search, and connect apps that keep syncing into a namespace. Authenticate with an API key from conare.ai/console/keys: `Authorization: Bearer sk-conare-…`. Bodies are JSON with snake_case keys; timestamps are RFC 3339 strings. Every response carries `X-Request-Id`, and every error has the shape `{"error": {"code", "message", "request_id"}}`. A 429, and a 503 that clears on its own, carry `Retry-After` (seconds). Conare is also an MCP server at `https://api.conare.ai/mcp` (streamable HTTP, same bearer key) with the tools `search`, `fetch`, `save`, `delete` and `list_namespaces`. 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`. It is created by its first write. - name: Documents description: >- A document is `{ id, text, metadata }`. Conare chunks and embeds it. Writing the same id replaces it. - name: Query description: >- Hybrid search (vector and keyword) over one namespace, with an optional metadata filter, reranked. - name: Models description: The embedding and reranking models Conare searches with. - name: Sources description: > Apps connected to Conare. Each keeps syncing into one namespace. While sources are not available, every sources route answers 503 with code `sources_unavailable`. - name: Health description: Service health. paths: /namespaces/{namespace}/query: parameters: - $ref: '#/components/parameters/Namespace' post: tags: - Query summary: Query a namespace description: > Hybrid search (vector and keyword) over one namespace, optionally filtered by metadata, reranked. Returns one result per document: its best matching passage. operationId: query requestBody: required: true content: application/json: schema: type: object required: - query properties: query: type: string minLength: 1 description: What to search for, in plain language. top_k: type: integer minimum: 1 maximum: 100 default: 10 description: How many results to return. filter: $ref: '#/components/schemas/Filter' rerank: type: boolean default: true description: Rerank the candidates with the reranking model. example: query: how do refunds work? top_k: 5 filter: team: support responses: '200': description: Results, best first. content: application/json: schema: type: object required: - results - took_ms properties: results: type: array items: $ref: '#/components/schemas/QueryResult' 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 metadata: team: support took_ms: 42 '400': $ref: '#/components/responses/Error' '401': $ref: '#/components/responses/Error' '404': $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: Filter: type: object description: > A metadata filter. `{"key": value}` means equals. Operators: `$eq $ne $gt $gte $lt $lte $in $nin`. Combine filters with `$and` and `$or` arrays. 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: $gte: 2024 QueryResult: type: object required: - id - text - score - metadata properties: id: $ref: '#/components/schemas/DocumentId' text: type: string description: The document's best matching passage. score: type: number description: Higher is better. metadata: $ref: '#/components/schemas/Metadata' 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' $gt: type: - number - string $gte: type: - number - string $lt: type: - number - string $lte: type: - number - string $in: type: array items: $ref: '#/components/schemas/FilterValue' $nin: type: array items: $ref: '#/components/schemas/FilterValue' 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 Metadata: type: object maxProperties: 32 description: >- Up to 32 keys. Values are strings, numbers, booleans or arrays of strings. additionalProperties: oneOf: - type: string - type: number - type: boolean - type: array items: type: string Error: type: object required: - error properties: error: type: object required: - code - message - request_id properties: code: type: string description: > Stable and machine-readable. 400: `invalid_request`, `invalid_json`, `invalid_namespace`, `invalid_id`, `invalid_metadata`, `invalid_filter`, `invalid_cursor`. 401: `unauthorized`. 403: `forbidden`. 404: `namespace_not_found`, `document_not_found`, `source_not_found`, `not_found`. 413: `payload_too_large`. 429: `rate_limited`. 500: `internal_error`. 502: `upstream_error`. 503: `unavailable`, `sources_unavailable`. 504: `timeout`. message: type: string request_id: type: string responses: Error: description: An error. `X-Request-Id` is also in the response headers. headers: X-Request-Id: schema: type: string Retry-After: description: >- On 429, and on a 503 that clears on its own, seconds to wait before retrying. schema: type: integer content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: invalid_request message: text is required request_id: req_8f3a2c securitySchemes: apiKey: type: http scheme: bearer bearerFormat: sk-conare-… description: >- An API key from conare.ai/console/keys. It can read and write every namespace in its organization. ````