API v1

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

Open the interactive API reference to browse every public operation by domain. Download the current OpenAPI contract there as JSON or YAML.

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.

Authenticate a request

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.

Response errors

Errors use one JSON envelope:

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

Common status codes are:

Pagination

Use the pagination parameters shown on each operation. Cursor-based lists return nextCursor. Pass it as cursor on the next request.

Safe retries

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

Common domains

These are examples. The API reference lists the complete, current operation set.

• 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.
• Memories: inspect settings and perform 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.
• Projects: manage the Projects that Teammates attach to, and their Project documents.
• Reviews: list, read, and decide Human review requests.
• 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.
• Usage: read the plan's meters and who spent a window's credits. Read-only. The spender breakdown keeps its dimensions apart. One answer names both the teammate that ran and the colleague who asked, so adding the dimensions together counts it twice. Buying credits has no endpoint: a purchase belongs on a screen where a person confirms an amount.

Use the OpenAPI document for request fields, authentication, and documented response status codes.