API v1

L'API di Ciele utilizza JSON tramite HTTP. Tutti i percorsi della versione 1 iniziano con /api/v1.

Apri la documentazione interattiva dell'API per esplorare tutte le operazioni pubbliche per dominio. Scarica lì il contratto OpenAPI corrente in formato JSON o YAML.

Scopri il deployment

Utilizza questi endpoint pubblici prima di generare un client:

GET /api/v1/meta
GET /api/v1/openapi.json

meta elenca la versione dell'API e i domini disponibili. openapi.json restituisce il contratto leggibile a macchina per il deployment.

Autentica una richiesta

Invia la chiave API come bearer token:

curl https://ciele.app/api/v1/whoami \
  --header "Authorization: Bearer $CIELE_API_KEY"

Per l'autohosting, sostituisci https://ciele.app con l'origine pubblica di Ciele.

Errori di risposta

Gli errori utilizzano un unico JSON envelope:

{
  "error": {
    "code": "forbidden",
    "message": "This API key cannot perform this operation."
  }
}

I codici di stato più comuni sono:

Impaginazione

Usa i parametri di paginazione indicati per ogni operazione. Gli elenchi basati su cursore restituiscono nextCursor. Passalo come cursor nella richiesta successiva.

Tentativi di ripetizione sicuri

I percorsi di mutazione possono accettare un header Idempotency-Key. Riutilizza lo stesso valore solo quando ritenti la stessa operazione logica.

Domini comuni

Questi sono esempi. La API reference elenca il set completo e aggiornato delle operazioni.

• Assistenti: list, read, create, update, duplicate e delete.
• Flow: list, read, create, update, reorder e delete.
• Knowledge: gestisci Collections, Sources, FAQ e i link dell'Assistente su ciascuna Source.
• Publication: leggi lo stato, pubblica, annulla la pubblicazione e ripristina una pubblicazione.
• Inbox: rivedi, esporta, appunta, annota, valuta ed elimina le Conversations.
• Miglioramenti: elenca, leggi e aggiorna gli elementi.
• Entities and Memories: gestisci i dati dell'organizzazione tipizzati e la cancellazione delle memorie con ambito definito.
• SSO: gestisci le identity claim, le impostazioni di connessione, la convalida e la disconnessione.
• Help Desk: gestisci i desk, i canali di escalation, l'ordinamento e ServiceNow.
• Teammates: gestisci gli AI Teammates e leggi le tue conversazioni con i Teammate.
• Channels: leggi e modella i canali dei Teammate in cui sei presente e i loro roster. Non esiste un endpoint per inviare un messaggio: un messaggio avvia una catena di risposte dei Teammate, che viene eseguita nella console.
• Configuration: gestisci Skills, Assistant Goals e Alerts operativi.
• Organization: gestisci le impostazioni, i Members, gli Invites e le API keys.
• Integrations: gestisci le integrazioni dell'API dell'Assistente e le connessioni ai provider di modelli.
• Usage: consulta i contatori del piano e scopri chi ha utilizzato i crediti di una finestra. Sola lettura. La ripartizione della spesa mantiene separate le sue dimensioni. Una risposta indica sia il membro del team che ha eseguito l'operazione sia il collega che l'ha richiesta, quindi sommando le dimensioni si conta due volte. L'acquisto di crediti non ha un endpoint: un acquisto avviene su una schermata in cui una persona conferma un importo.

Utilizza il documento OpenAPI per i campi delle richieste, l'autenticazione e i codici di stato delle risposte documentati.