Developer documentation

Clero API

Connect partner backends, provision customer workspaces, install agent templates, and send messages into Clero automation agents with stable server-side credentials.

OpenAPI JSON Markdown docs

Base URL

https://clero.so/api/v1

Auth: Bearer partner token
Transport: HTTPS JSON and multipart
Runtime: Accepted now, replies later

Overview

What this API is for

The public API is designed for backend-to-backend integrations. Keep tokens on your server, use stable external identifiers for retries, and let Clero handle agent runtime work inside each space.

Provision customer spaces

Create or reuse a Clero space and install approved agent templates from your backend.

Reuse existing agents

Discover spaces and agents, then create API chat sources for selected automation agents.

Send runtime messages

Thread messages by session_id, dedupe by external_message_id, then poll or receive replies.

Quick start

From token to first agent message

Most partner integrations follow the same path: authenticate, locate or provision a workspace, connect an API chat source, then send messages with a durable session key.

Create a partner token

Generate a token in the organization admin surface and scope it to the minimum permissions required.

Authorization: Bearer <PARTNER_TOKEN>

Find or provision the workspace

List spaces for existing customers or use external_space_id to create/reuse a customer workspace.

GET /automation/spaces/ or POST /automation/agent-templates/provision-space/

Attach an API chat source

Create or reuse the source that accepts messages for a specific agent.

POST /automation/spaces/<SPACE_ID>/agents/<AGENT_ID>/api-chat/

Send a message

Use source_id, session_id, and external_message_id so conversations thread correctly and retries stay safe.

POST /integrations/api-chat/message/

Authentication

Partner tokens stay server-side

Send partner tokens in the Authorization header. Scope each token to the permissions the integration actually needs, then restrict it with IP allowlists when production egress IPs are stable.

Token handling

Partner token values are shown once during creation. Store them in your backend secret manager and never expose them to browser clients.

Permission scopes

Grant only the scopes needed for the integration, such as spaces.read, agents.read, cron_jobs.write, or API chat setup/runtime scopes.

IP allowlists

An empty allowed_ip_cidrs list allows any caller IP. In production, restrict tokens to known partner egress IPs or CIDR ranges when possible.

Minimum balance

Public API calls require at least $1 USD in organization pay-as-you-go balance. Low-balance calls return 402 and are not processed.

Authorization header

Use the same header on read, write, setup, and runtime calls.

curl -sS "https://clero.so/api/v1/automation/spaces/" \
  -H "Authorization: Bearer <PARTNER_TOKEN>" \
  -H "Accept: application/json"

Resources

Endpoint groups

Use this map to understand the surface area quickly. The OpenAPI files remain the source of truth for exact request and response schemas.

Spaces and provisioning

Create customer workspaces, list accessible spaces, and install approved agent templates.

spaces.read / spaces.write

GET/automation/spaces/

List spaces available to the partner token.

POST/automation/agent-templates/provision-space/

Create or reuse a space and install agent templates.

Agents

Discover existing agents inside a space before creating runtime integrations.

agents.read

GET/automation/spaces/<SPACE_ID>/agents/

List space-scoped agents and their public integration metadata.

POST/automation/spaces/<SPACE_ID>/agents/<AGENT_ID>/api-chat/

Create or reuse an API chat source for an existing agent.

API chat runtime

Send messages into Clero and retrieve assistant output after processing completes.

api_chat.write

POST/integrations/api-chat/message/

POST/integrations/api-chat/history/

Poll session history and assistant replies after a message cursor.

Documents and files

Upload documents or file attachments, then reference returned identifiers from agent workflows.

files.write

POST/automation/documents/

Upload or create document resources for automation workflows.

POST/automation/file-attachments/

Upload file attachments through multipart requests.

Cron jobs

Schedule recurring work for a selected agent and retain returned job ids for support.

cron_jobs.write

POST/automation/partner-cron-jobs/

Create a scheduled automation job for an existing agent.

GET/automation/partner-cron-jobs/

Review scheduled jobs available to the partner token.

Runtime

How API chat works

API chat registers inbound messages immediately. Assistant replies are delivered later through polling or configured webhooks, which keeps request latency predictable.

Message is accepted

The message endpoint acknowledges registration and returns the internal message id.

Agent processing starts

The source routing mode decides whether the message enters an agent inbox or launches an independent session workflow.

Replies are retrieved

Poll history with after_message_id or use configured webhooks to receive completed assistant messages.

Send an API chat message

Use source_id plus session_id to preserve conversation context.

curl -sS "https://clero.so/api/v1/integrations/api-chat/message/" \
  -X POST \
  -H "Authorization: Bearer <PARTNER_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "source_id": "<API_CHAT_SOURCE_ID>",
    "session_id": "customer-123",
    "text": "Can you check the latest booking details?",
    "external_message_id": "msg-123",
    "response_mode": "accepted"
  }'

Examples

Copyable curl templates

These snippets use placeholder values by design. Keep real partner tokens, API chat tokens, and customer identifiers out of browser code.

List spaces

Discover existing Clero spaces available to this organization token.

curl -sS "https://clero.so/api/v1/automation/spaces/" \
  -H "Authorization: Bearer <PARTNER_TOKEN>" \
  -H "Accept: application/json"

List agents in a space

Discover existing agents inside a selected Clero space.

curl -sS "https://clero.so/api/v1/automation/spaces/<SPACE_ID>/agents/" \
  -H "Authorization: Bearer <PARTNER_TOKEN>" \
  -H "Accept: application/json"

Create or reuse API chat

Create the API chat source used to send messages to an existing agent.

curl -sS "https://clero.so/api/v1/automation/spaces/<SPACE_ID>/agents/<AGENT_ID>/api-chat/" \
  -X POST \
  -H "Authorization: Bearer <PARTNER_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Customer API Chat",
    "reply_capable": true,
    "routing_mode": "agent_inbox"
  }'

Provision a space

Create or reuse a space, then install one or more approved agent templates.

curl -sS "https://clero.so/api/v1/automation/agent-templates/provision-space/" \
  -X POST \
  -H "Authorization: Bearer <PARTNER_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "external_space_id": "customer-123",
    "space": {
      "name": "Customer workspace",
      "description": "Workspace created by partner backend",
      "is_org_wide": true
    },
    "agents": [
      {
        "template_id": "<TEMPLATE_ID>",
        "name": "Customer agent",
        "auto_create_api_chat": true,
        "api_chat_routing_mode": "agent_inbox"
      }
    ]
  }'

Create a cron job

Schedule recurring work on an existing agent.

curl -sS "https://clero.so/api/v1/automation/partner-cron-jobs/" \
  -X POST \
  -H "Authorization: Bearer <PARTNER_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "<AGENT_ID>",
    "name": "Daily partner sync",
    "instructions": "Review new documents and summarize open risks.",
    "schedule": {
      "type": "cron",
      "data": {
        "minute": "0",
        "hour": "9",
        "day_of_week": "1-5"
      },
      "timezone": "UTC"
    }
  }'

Reliability

Retries, idempotency, and limits

The integration should be safe to retry where the API exposes an external identifier. Store Clero identifiers returned by successful calls and use backoff for retryable failures.

Space provisioning

external_space_id

Pass the same external_space_id for retries so repeated requests reuse the existing customer workspace.

API chat messages

external_message_id

Use a stable external_message_id per source/session message. Retrying the same id returns the existing message instead of creating a duplicate.

Polling history

after_message_id

Use the internal message_id returned by the API as a cursor when polling for new assistant replies.

Rate limits

429 / Retry-After

Respect Retry-After when present. Otherwise use exponential backoff and avoid repeated non-idempotent creation calls.

Minimum balance

402 / organization_balance_too_low

Top up the organization balance before retrying. Low-balance API calls are rejected before messages, sessions, files, or jobs are processed.

Cron job creation

returned cron job id

Store the returned job id. Do not blindly retry cron job creation unless your backend adds its own dedupe guard.

Reference

Canonical docs and schemas

Use the Markdown guide for humans, the llms files for AI coding agents, and OpenAPI for schema validation or SDK generation.

Markdown docs

Human-readable endpoint guide for the latest public API version.

AI docs index

Small index file for agents that need to discover API docs quickly.

Full AI-readable docs

Complete plain-text API reference optimized for AI coding agents.

OpenAPI JSON

Machine-readable schema for SDK generators and validators.

OpenAPI YAML

YAML schema for review, import, and local tooling.

Q&A

Common integration questions

Practical answers for production backends, message threading, and credential handling.

How should we handle idempotency?

Use external_space_id when creating or reusing a space with agent templates. Retrying with the same external_space_id reuses the existing space instead of creating another customer workspace.

Use external_message_id when sending API chat messages. Retrying the same external_message_id in the same API chat session returns the existing message with created=false.

Creating API chat for an existing agent is safe to repeat. Clero reuses the auto-managed API chat source for that agent instead of creating duplicate sources.

Cron job creation is not an idempotent POST today. Store the returned cron job id and avoid blind retries unless your backend guards the request.

Do we send messages directly to an agent endpoint?

No. For public API usage, create or reuse an API chat source for the agent, then send messages to /integrations/api-chat/message/.

This keeps runtime messaging consistent across inbox mode, workflow mode, history polling, webhooks, and file attachments.

When should we use agent_inbox vs session_workflow?

Use agent_inbox when the agent should behave like one inbox worker and can process multiple related messages in the same thread.

Use session_workflow when every API chat message should start an independent workflow run through an auto-managed trigger.

Which identifiers should our backend store?

Store your own external_space_id, Clero space_id, agent_id, API chat source_id, cron job id, and the internal message_id returned by API chat.

Keep external_message_id in your own request log so failed network calls can be retried without creating duplicate chat messages.

Treat API chat tokens and partner tokens as backend secrets. Never expose them in browser code.

What should we retry?

Retry network errors and 5xx responses with the same idempotency identifiers. For 429 responses, respect Retry-After when it is present and use exponential backoff.

Do not retry non-idempotent creation calls repeatedly unless your backend has its own dedupe key or stores the result from the first successful request.

What happens when organization balance is below $1 USD?

Public API calls are rejected with 402 and code organization_balance_too_low.

Top up the organization balance before retrying; do not keep retrying low-balance 402 responses.

Can AI coding agents use these docs?

Yes. Use /docs/api/latest/llms.txt for discovery, /docs/api/latest/llms-full.txt for the full plain-text guide, and /docs/api/latest/openapi.json for schemas.

The public page and docs intentionally use the PARTNER_TOKEN placeholder and do not require a logged-in Clero session.

What happens when allowed_ip_cidrs is empty?

An empty IP allowlist means the token can be used from any caller IP. A non-empty allowlist restricts that token to the configured public egress IPs or CIDR ranges.

For production partner backends, configure allowed_ip_cidrs when the partner has stable outbound IPs.