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

# Panoramica dell'API

> URL di base, autenticazione, errori, nuovi tentativi, limiti di frequenza e header dell'API Conare.

L'API Conare è JSON su HTTPS. Ogni endpoint ha una pagina in questa scheda, con un playground.

| | |
| - | - |
| URL di base | `https://api.conare.ai` |
| Autenticazione | `Authorization: Bearer $CONARE_API_KEY` |
| Chiavi | Create nella [console](https://docs.conare.ai/it/console.md#chiavi); tienile sul tuo server |
| Body | JSON, snake\_case; i campi sconosciuti danno `400` |
| Specifica | [api.conare.ai/openapi.yaml](https://api.conare.ai/openapi.yaml) |

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

Le route compatibili con OpenAI e Cohere (`/v1`, `/v2`) ignorano i campi sconosciuti.

## Errori

```json theme={null}
{
  "error": {
    "code": "invalid_request",
    "message": "documents[0].text is required",
    "request_id": "45ea7c7353368cb646e5cc2303008072"
  }
}
```

| Stato | Significato |
| - | - |
| 400 | La richiesta non è valida; `message` spiega perché |
| 401 | La chiave è mancante, errata o revocata |
| 403 | La chiave non può accedere a questo namespace o a questa route |
| 404 | Non trovato |
| 409 | Un conflitto di versione, oppure ha prevalso una scrittura concorrente |
| 413 | Il body, un documento o un file è troppo grande |
| 415 | Il tipo di [file](https://docs.conare.ai/it/files.md) non è supportato |
| 422 | Il file non può essere letto, oppure un `Idempotency-Key` è stato riutilizzato per un'altra richiesta |
| 429 | Superato un [limite di frequenza](#limiti-di-frequenza) |
| 5xx | Un problema da parte nostra |

## Nuovi tentativi

| Caso | Cosa fare |
| - | - |
| `429`, `503` | Riprova dopo i secondi indicati dall'header `Retry-After` |
| Altri 5xx | Riprova con backoff |
| Scritture ed eliminazioni | Invia un `Idempotency-Key` (un UUID); una ripetizione entro 24 ore restituisce la prima risposta con `Idempotent-Replayed: true` e non modifica nulla |

L'[SDK](https://docs.conare.ai/it/sdk.md) ritenta e invia `Idempotency-Key` per te.

## Limiti di frequenza

Per organizzazione. Sono ammessi picchi fino all'equivalente di 10 secondi; oltre un limite l'API restituisce `429` con `Retry-After`.

| Chiamate | Al secondo | In corso contemporaneamente |
| - | - | - |
| Ricerca | 100 | 128 |
| Scrittura | 100 documenti | 64 |
| Embed | 100 testi | 16 |
| Rerank | 20 | 16 |
| Query dell'[API turbopuffer](https://docs.conare.ai/it/turbopuffer.md) | 1.000 | |
| Tutto il resto | 100 | |

## Header

| Header | Direzione | Significato |
| - | - | - |
| `Authorization` | Richiesta | `Bearer` e la tua chiave |
| `Idempotency-Key` | Richiesta | Rende sicuro ritentare una scrittura |
| `X-Conare-Org` | Richiesta | L'organizzazione per cui agire, con una chiave multi-organizzazione ([elencale](https://docs.conare.ai/it/api-reference/organizations/list-organizations.md)) |
| `Content-Encoding: gzip` | Richiesta | Un body compresso; i limiti lo contano decompresso |
| `X-Request-Id` | Risposta | In ogni risposta; includilo quando contatti il supporto |
| `Retry-After` | Risposta | Secondi da attendere, con `429` e `503` |
| `Conare-Degraded` | Risposta | La richiesta è riuscita senza una parte del suo lavoro, come il reranking ([valori](https://docs.conare.ai/it/query.md#risultati-degradati)) |
| `Idempotent-Replayed` | Risposta | `true` quando un nuovo tentativo ha ricevuto la prima risposta |

## Stato del servizio

`GET /health/deep` non richiede una chiave: `status` è `ok`, `degraded` (entrambi HTTP 200) o `down` (HTTP 503).

```json Response theme={null}
{ "status": "ok", "checkedAt": "2026-10-21T21:39:16.729996745Z" }
```


## Related topics

- [API turbopuffer](https://docs.conare.ai/it/turbopuffer.md)
- [Ricerca](https://docs.conare.ai/it/query.md)
- [Tipi di file e Markdown](https://docs.conare.ai/it/file-types.md)
- [Sorgenti](https://docs.conare.ai/it/sources.md)
- [File](https://docs.conare.ai/it/files.md)


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