Panoramica dell'API

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; tienile sul tuo server
Body	JSON, snake_case; i campi sconosciuti danno `400`
Specifica	api.conare.ai/openapi.yaml

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

{
  "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 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
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 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	1.000
Tutto il resto	100

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)
`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)
`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).

Response

{ "status": "ok", "checkedAt": "2026-10-21T21:39:16.729996745Z" }

Panoramica

Namespace

Documenti

Ricerca

File

Parsing

Sorgenti

Sorgenti personalizzate

Modelli

Utenti

Eventi

Organizzazioni

Stato

Panoramica dell'API

Errori

Nuovi tentativi

Limiti di frequenza

Header

Stato del servizio

​Errori

​Nuovi tentativi

​Limiti di frequenza

​Header

​Stato del servizio

Errori

Nuovi tentativi

Limiti di frequenza

Header

Stato del servizio