Embed Integration API

The Embed Integration API enables embedding Clouisle Agent conversations and workflow executions into third-party portals, iframe widgets, or cookie-less client applications. The base path is /api/v1/embed.

Authentication & Security Policies

All embed endpoints exclusively require API Key authentication (prefixed with clou_). Cookie sessions are not accepted. Credentials can be passed using either of the following mechanisms:

• Header: Authorization: Bearer clou_...
• Query Parameter: ?token=clou_...

Resolution order is the token query parameter first, then the Authorization header; both must start with clou_, otherwise the request is treated as missing credentials and returns 401 (code 2000, embed_api_key_required).

Beyond authentication, the target must be usable for embedding: an Agent or Workflow must be in published status and have embed_config.enabled = true, otherwise the API returns 404 (agent_not_found / workflow_not_found) or 403 (embed_not_enabled).

Browser Embed Pages

Alongside the REST namespace, the product ships two pages you can drop straight into an <iframe> (these do not use the /api/v1 prefix):

<iframe
  src="https://your-domain.com/embed/agent/550e8400-e29b-41d4-a716-446655440000?token=clou_xxx&mode=bubble"
  style="width: 420px; height: 640px; border: 0"
></iframe>

The iframe also emits two events so the host page can react: { "type": "clouisle:conversation", "conversationId": "..." } when a conversation is created/switched, and { "type": "clouisle:close" } when the user clicks close.

Domain Whitelist Verification (allowed_domains)

When an Agent or Workflow has allowed_domains configured in its embed_config:

1. The server checks the Origin or Referer request header against the allowed domains list (supports wildcard subdomains such as *.example.com).
2. If the request origin does not match the whitelist, the server returns 403 Forbidden (code: 3000, embed_domain_not_allowed).
3. Direct requests with no origin header or items with empty whitelists are allowed.
4. Workflow event streams (GET /workflows/runs/{run_id}/stream) are exempt from origin verification.

Agent Embed Endpoints

1. Get Embed Agent Info

GET /api/v1/embed/agents/{agent_id}/info HTTP/1.1
Authorization: Bearer clou_api_key

Response (200 OK)

{
  "code": 0,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Support Assistant",
    "description": "Answers customer questions regarding returns and billing",
    "icon": "🤖",
    "avatar_url": null,
    "opening_message": "Hello! How can I assist you today?",
    "suggested_questions": [
      "How do I request a refund?",
      "Where can I find my invoice?"
    ],
    "variables": [],
    "enable_attachments": true,
    "attachment_config": {
      "max_file_count": 5,
      "max_file_size_mb": 10
    },
    "hide_tool_calls": false,
    "hide_message_actions": false,
    "hide_reasoning": false,
    "embed_config": {
      "enabled": true,
      "allowed_domains": ["https://example.com"]
    }
  },
  "msg": "success"
}

2. Stream Chat Message

POST /api/v1/embed/agents/{agent_id}/chat/stream HTTP/1.1
Authorization: Bearer clou_api_key
Content-Type: application/json

{
  "message": "What is the return window?",
  "conversation_id": "conv-uuid-optional",
  "variables": {}
}

Returns a text/event-stream SSE response whose events are identical to the main chat stream endpoint (message_start, content_delta, rag_start/rag_context, reasoning_start/reasoning_delta/reasoning_end, tool_call/tool_result, media_result, compression_start/compression_end, output_truncated, iteration_cap_reached, message_end, error) — see SSE Streaming Events.

3. Create Durable Run

For disconnected resilience and long-running tools, use the durable run workflow:

POST /api/v1/embed/agents/{agent_id}/chat/runs HTTP/1.1
Authorization: Bearer clou_api_key
Content-Type: application/json

{
  "message": "Generate Q3 sales analysis",
  "conversation_id": null,
  "variables": {}
}

Response (202 Accepted)

{
  "code": 0,
  "data": {
    "run_id": "run-uuid-1234",
    "conversation_id": "conv-uuid-5678",
    "status": "queued",
    "stream_url": "/embed/agents/550e8400-e29b-41d4-a716-446655440000/chat/runs/run-uuid-1234/stream"
  },
  "msg": "success"
}

Clients subscribe to GET /api/v1/embed/agents/{agent_id}/chat/runs/{run_id}/stream?after_sequence=N to stream events with deduplication and reconnection capability.

4. Run Control and Query Parameters

Workflow Embed Endpoints

1. Run Workflow

POST /api/v1/embed/workflows/{workflow_id}/run HTTP/1.1
Authorization: Bearer clou_api_key
Content-Type: application/json

{
  "inputs": {
    "query": "Summarize customer feedback",
    "format": "markdown"
  }
}

Response (200 OK)

{
  "code": 0,
  "data": {
    "run_id": "wf-run-uuid-1234",
    "stream_url": "/api/v1/workflows/runs/wf-run-uuid-1234/stream"
  },
  "msg": "success"
}

2. Stream Workflow Run Progress

GET /api/v1/embed/workflows/runs/{run_id}/stream?from_sequence=0

Note the naming difference from Agent runs: workflow streams use from_sequence, Agent runs use after_sequence. This route does not perform the domain whitelist check (every other workflow embed endpoint does), but it does require the run to have been triggered by the API key's user, otherwise it returns 404 (workflow_run_not_found).

3. Workflow Embed Info

GET /api/v1/embed/workflows/{workflow_id}/info

Returns id, name, description, icon, variables (input parameter definitions), and embed_config. The workflow must be published with embedding enabled, otherwise the call returns 404 (workflow_not_found) or 403 (embed_not_enabled).

Error Codes