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'origin pubblico di Ciele.

La risposta include capabilities: le funzionalità della chiave. Una chiave può eseguire solo le operazioni consentite sia dal suo Role che dal suo creatore.

In un'operazione relativa a un singolo Assistente, si applica il Role del creatore su quell'Assistente. Se solo quel Role dell'Assistente rifiuta l'operazione, l'API restituisce 404, come nel caso di un Assistente che non esiste.

Errori di risposta

Gli errori utilizzano un unico envelope JSON:

{
  "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 ciascuna 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.
• Flows: list, read, create, update, reorder e delete.
• Knowledge: gestisci Collections, Sources, FAQs 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.
• Memories: controlla le impostazioni ed esegui la cancellazione della memoria con ambito definito.
• SSO: gestisci le attestazioni di identità, le impostazioni di connessione, la convalida e la disconnessione.
• Help Desks: gestisci i desk, i canali di escalation, l'ordinamento e il ticketing target.
• Teammates: gestisci gli AI Teammates e leggi le tue conversazioni con i Teammates.
• Projects: gestisci i Projects, le loro milestone e i documenti di progetto che i Teammate leggono.
• Tasks: elenca, leggi, crea, modifica, archivia ed elimina le Tasks, commentale e gestisci le Labels delle Tasks. L'elenco applica filtri per Project, assignee, status, Label, date di scadenza, testo e Improvement, e utilizza un cursore per ogni pagina. Una chiave legge solo i Projects che il suo membro può leggere. Un commento indica quel membro come autore.
• Reviews: elenca, leggi e prendi decisioni sulle richieste di Human review.
• Channels: leggi e modella i canali dei colleghi del team a cui partecipi e i loro roster. Non esiste un endpoint per inviare un messaggio: un messaggio avvia una catena di risposte dei colleghi del team, 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. Limita un Member agli Assistant selezionati.
• Integrations: gestisci le integrazioni dell'API dell'Assistente e le connessioni ai provider di modelli.
• Utilizzo: 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 in una schermata in cui una persona conferma un importo.
• Audit log: consulta chi ha modificato cosa, da quale interfaccia, con il valore precedente e successivo per le modifiche a role, invitation, key, access e settings. Sola lettura. Filtra per action, actor e date. Per consultare dati più vecchi, invia createdAt e id dell'ultima voce che hai come before e beforeId.

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