API v1

The Ciele API uses JSON over HTTP. All version 1 routes start with /api/v1.

Discover the deployment

Use these public endpoints before you generate a client:

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

meta lists the API version and the available domains. openapi.json returns the machine-readable contract for the deployment.

Send the API key as a bearer token:

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

For self-hosting, replace https://ciele.app with the public Ciele origin.

Errors use one JSON envelope:

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

Common status codes are:

Status	Meaning
`400`	The request data is not valid.
`401`	The key is missing, invalid, or revoked.
`403`	The key Role does not permit the operation.
`404`	The resource does not exist in the Organization.
`409`	The request conflicts with the current state.

List operations accept limit and cursor parameters when the endpoint supports pagination. Use the returned cursor for the next request.

Mutation routes can accept an Idempotency-Key header. Reuse the same value only when you retry the same logical operation.

Assistants: list, read, create, update, duplicate, and delete.
Flows: list, read, create, update, reorder, and delete.
Knowledge: manage Collections, Sources, FAQs, and the Assistant links on each Source.
Publication: read status, publish, unpublish, and restore a publication.
Inbox: review, export, pin, annotate, rate, and delete Conversations.
Improvements: list, read, and update items.
Entities and Memories: manage typed Organization data and scoped Memory erasure.
SSO: manage identity claims, connection settings, validation, and disconnection.
Help Desks: manage desks, escalation channels, ordering, and ServiceNow.
Teammates: manage AI Teammates and read your own Teammate conversations.
Channels: read and shape the teammate channels you are in, and their rosters. There is no endpoint to send a message: a message starts a chain of teammate replies, and that runs in the console.
Configuration: manage Skills, Assistant Goals, and operational Alerts.
Organization: manage settings, Members, Invites, and API keys.
Integrations: manage Assistant API integrations and model Provider Connections.

Use the OpenAPI document for exact request fields and response schemas.