API overview

The API is JSON over HTTPS at https://api.conare.ai. Send your API key as a bearer token:

curl https://api.conare.ai/namespaces \
  -H "Authorization: Bearer $CONARE_API_KEY"

Create keys in the console, and keep them on your server. TypeScript examples use the SDK, which returns the useful part of each response:

import { Conare } from "conare";

const conare = new Conare(); // reads CONARE_API_KEY
const docs = conare.namespace("docs");

Errors

Errors are JSON in this shape:

{
  "error": {
    "code": "invalid_request",
    "message": "documents[0].text is required",
    "request_id": "b3200326-610a-4ea7-aa30-31fe9d13bfef"
  }
}

Status	Code	Meaning
400	`invalid_request`, `invalid_json`, `invalid_filter`, …	The request is wrong. `message` says why.
401	`unauthorized`	The key is missing, wrong or revoked.
403	`namespace_forbidden`, `key_scope_models_only`, `forbidden`	The key can’t reach this namespace or route.
404	`namespace_not_found`, `document_not_found`, …	It doesn’t exist.
409	`version_conflict`, `conflict`	An `if_version` didn’t match, or a concurrent write won.
413	`payload_too_large`	The body, a document or a file is too large.
415, 422	`unsupported_file`, `unreadable_file`, `no_text`	The file can’t be read.
429	`rate_limited`	Too many requests.
5xx	`unavailable`, `timeout`, `upstream_error`, …	Busy or failed on our side.

Retry 429 and 503 after the Retry-After header’s seconds, and other 5xx with backoff.
A failed write may be partly applied. Retry it with the same document ids, which replace rather than duplicate, and with if_version if a newer write may have landed in between.
A 502 or 504 can arrive as plain text instead of JSON.
Bodies are strict: an unknown field returns 400 invalid_json. The /v1 routes ignore unknown fields.

Limits

	Limit
Requests	50 a second per organization, bursts of 500. A write of n documents counts as n.
Requests at once	16 queries and 4 writes per organization. More wait briefly, then return `429`.
Namespace name	1-64 characters of `a-z 0-9 _ -`, starting with a letter or digit
Document id	1-256 characters of `A-Z a-z 0-9 . _ : -`, starting with a letter or digit
Document text	256 KiB
Documents per write	100
Metadata	32 keys and 256 values (details)
Ids per delete	1,000
Documents per list page	100
Query	8,000 characters, 100 results
Filter	256 conditions, 8 levels deep, 255 values per `$in`
File	20 MiB, 2,000 pages or sheets
Embed	128 texts per request
Rerank	100 documents of up to 24,000 characters, 256,000 characters in all

Headers

Every response has an X-Request-Id. To trace a request, send your own: 1-128 characters of A-Z a-z 0-9 . _ : -, starting with a letter or digit.
Conare-Degraded is set when a request succeeded without part of search, or on a backup. See degraded results.

Health

GET /health/deep needs no key. Its status is ok, degraded (HTTP 200, still serving) or down (HTTP 503).

OpenAPI

The spec is at api.conare.ai/openapi.yaml.

Get started

API

Tools

Errors

Limits

Headers

Health

OpenAPI

​Errors

​Limits

​Headers

​Health

​OpenAPI

Errors

Limits

Headers

Health

OpenAPI