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

# API overview

> Authentication, errors and limits.

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

```bash theme={null}
curl https://api.conare.ai/namespaces \
  -H "Authorization: Bearer $CONARE_API_KEY"
```

Create keys in the [console](/console#keys), and keep them on your server.

TypeScript examples use the [SDK](/sdk), which returns the useful part of each response:

```ts theme={null}
import { Conare } from "conare";

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

## Errors

Errors are JSON in this shape:

```json theme={null}
{
  "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](/files) 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](/write#metadata)) |
| 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](/query#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](https://api.conare.ai/openapi.yaml).


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