Integrate ClickAI via RESTful API
Complete guide to integrate AI applications built on ClickAI into any system through API.
Table of Contents
· [How API Integration Works](#how-api-integration-works)
· [Getting Started](#getting-started)
· [Authentication](#authentication)
· [List Assistants API](#list-assistants-api)
· [Text Generation App API](#text-generation-app-api)
· [Conversational App API](#conversational-app-api)
· [Workflow App API](#workflow-app-api)
· [Managing conversation_id](#managing-conversation_id)
· [Streaming vs Blocking Response](#streaming-vs-blocking-response)
· [File Upload API](#file-upload-api)
· [Feedback API](#feedback-api)
· [Conversations API](#conversations-api)
· [Error Handling](#error-handling)
· [Rate Limits](#rate-limits)
· [SDK & Libraries](#sdk--libraries)
How API Integration Works
1. Build your AI app in ClickAI Studio
2. Generate API credentials (Secret Key)
3. Call the API from your application
4. Users interact through your custom interface — ClickAI handles AI processing behind the scenes
Getting Started
Step 1: Access API Settings
5. Open your app in ClickAI Studio
6. Click "Publish" → Select "API" tab
7. View auto-generated API documentation for your app
Step 2: Create API Key
8. In the API tab, click "+ Create API Key"
9. Set a descriptive name (e.g., production-backend)
10. Copy Secret Key — store securely, shown only once
Step 3: Identify the right endpoint
ClickAI has two base URLs depending on the API type:
Base URL
Used for
https://clickai.io
Studio / Console APIs (manage apps, workspace)
https://api.clickai.io
App Runtime APIs (chat, workflow, files)
App Type
Base
Endpoint
List Assistants
clickai.io
GET /assistant/api/assistant/my-assistants
Text Generation
api.clickai.io
POST /v1/completion-messages
Chatbot / Agent
api.clickai.io
POST /v1/chat-messages
Workflow
api.clickai.io
POST /v1/workflows/run
Authentication
All API requests require a Bearer Token in the header:
Authorization: Bearer {YOUR_SECRET_KEY} Content-Type: application/json
🛑 CAUTION: **API Key Security:** NEVER place API Keys in client-side code. NEVER commit API Keys to Git. Always call API from backend servers. Store keys in environment variables.
List Assistants API
Retrieve the list of assistants (apps) in your workspace.
Endpoint
GET https://clickai.io/assistant/api/assistant/my-assistants
Query Parameters
Parameter
Type
Required
Description
page
integer
❌
Current page (default: 1)
page_size
integer
❌
Items per page (default: 10)
mode
string
❌
App type: workflow, agent-chat, chat, completion
workspace_id
string
✅
Your workspace ID
Example — List Workflow Apps
curl -G 'https://clickai.io/assistant/api/assistant/my-assistants' \ -d 'page=1' \ -d 'page_size=10' \ -d 'mode=workflow' \ -d 'workspace_id=<YOUR_WORKSPACE_ID>' \ -H 'accept: application/json' \ -H 'authorization: Bearer <YOUR_ACCESS_TOKEN>'
Example — List Agent Chat Apps
curl -G 'https://clickai.io/assistant/api/assistant/my-assistants' \ -d 'page=1' \ -d 'page_size=10' \ -d 'mode=agent-chat' \ -d 'workspace_id=<YOUR_WORKSPACE_ID>' \ -H 'accept: application/json' \ -H 'authorization: Bearer <YOUR_ACCESS_TOKEN>'
Example — Python
import requests url = "https://clickai.io/assistant/api/assistant/my-assistants" headers = { 'accept': 'application/json', 'authorization': 'Bearer YOUR_ACCESS_TOKEN', } params = { 'page': 1, 'page_size': 10, 'mode': 'workflow', 'workspace_id': 'YOUR_WORKSPACE_ID' } response = requests.get(url, headers=headers, params=params) data = response.json() for app in data.get('data', []): print(f"App: {app['name']} (ID: {app['id']})")
💡 TIP: Use this API to automatically list apps in your workspace, useful for MCP integration or managing apps via scripts.
Text Generation App API
For single-turn content generation apps without conversation history.
Endpoint
POST https://api.clickai.io/v1/completion-messages
Request Body
Field
Type
Required
Description
inputs
object
✅
Input variables as configured in app
response_mode
string
✅
"streaming" or "blocking"
user
string
✅
Unique user ID for tracking
files
array
❌
Attached files (if app supports)
Example — cURL
curl --location --request POST 'https://api.clickai.io/v1/completion-messages' \ --header 'Authorization: Bearer YOUR-SECRET-KEY' \ --header 'Content-Type: application/json' \ --data-raw '{ "inputs": { "text": "Write a thank-you email to a customer" }, "response_mode": "streaming", "user": "user-abc-123" }'
Example — Python
import requests import json url = "https://api.clickai.io/v1/completion-messages" headers = { 'Authorization': 'Bearer YOUR-SECRET-KEY', 'Content-Type': 'application/json', } data = { "inputs": {"text": "Write a thank-you email"}, "response_mode": "streaming", "user": "user-abc-123" } response = requests.post(url, headers=headers, data=json.dumps(data)) print(response.text)
Example — JavaScript (Node.js)
const axios = require('axios'); const response = await axios.post( 'https://api.clickai.io/v1/completion-messages', { inputs: { text: 'Write a thank-you email' }, response_mode: 'streaming', user: 'user-abc-123' }, { headers: { 'Authorization': 'Bearer YOUR-SECRET-KEY', 'Content-Type': 'application/json' } } ); console.log(response.data);
Response (Blocking Mode)
{ "id": "msg-abc123", "answer": "Dear valued customer...", "created_at": 1705395332, "metadata": { "usage": { "prompt_tokens": 45, "completion_tokens": 128, "total_tokens": 173, "total_price": "0.000346", "currency": "USD" } } }
Conversational App API
For Chatbot and Agent — supports multi-turn conversation.
Endpoint
POST https://api.clickai.io/v1/chat-messages
Request Body
Field
Type
Required
Description
inputs
object
❌
Input variables (only for new conversations)
query
string
✅
User's message
response_mode
string
✅
"streaming" or "blocking"
conversation_id
string
❌
Conversation ID (empty = create new)
user
string
✅
Unique user ID
files
array
❌
Attached files
Example — cURL
curl --location --request POST 'https://api.clickai.io/v1/chat-messages' \ --header 'Authorization: Bearer YOUR-SECRET-KEY' \ --header 'Content-Type: application/json' \ --data-raw '{ "inputs": {}, "query": "Hello, I need product support", "response_mode": "streaming", "conversation_id": "", "user": "user-abc-123" }'
Example — Python
import requests import json url = "https://api.clickai.io/v1/chat-messages" headers = { 'Authorization': 'Bearer YOUR-SECRET-KEY', 'Content-Type': 'application/json', } data = { "inputs": {}, "query": "Hello, I need product support", "response_mode": "streaming", "conversation_id": "", "user": "user-abc-123" } response = requests.post(url, headers=headers, data=json.dumps(data)) print(response.text)
Workflow App API
For Workflow — batch processing, pipeline execution.
Endpoint
POST https://api.clickai.io/v1/workflows/run
Example — cURL
curl --location --request POST 'https://api.clickai.io/v1/workflows/run' \ --header 'Authorization: Bearer YOUR-SECRET-KEY' \ --header 'Content-Type: application/json' \ --data-raw '{ "inputs": { "input_text": "Analyze Q4 2024 sales data" }, "response_mode": "streaming", "user": "user-abc-123" }'
Managing conversation_id
Rules
Scenario
Action
Notes
New conversation
conversation_id: "" (empty)
System creates new ID, returned in response
Continue conversation
conversation_id: "conv-xyz789"
Use ID from previous response
Change variables mid-session
Use Conversation Variables
inputs ignored when conversation_id exists
Complete Flow Example
import requests import json BASE_URL = "https://api.clickai.io/v1" HEADERS = { 'Authorization': 'Bearer YOUR-SECRET-KEY', 'Content-Type': 'application/json', } # Turn 1: Start new conversation resp1 = requests.post(f"{BASE_URL}/chat-messages", headers=HEADERS, data=json.dumps({ "inputs": {"language": "en"}, "query": "I need help with warranty", "response_mode": "blocking", "conversation_id": "", "user": "user-001" }) ).json() conv_id = resp1["conversation_id"] print(f"Bot: {resp1['answer']}") # Turn 2: Continue conversation resp2 = requests.post(f"{BASE_URL}/chat-messages", headers=HEADERS, data=json.dumps({ "inputs": {}, "query": "How long is the warranty for product XYZ?", "response_mode": "blocking", "conversation_id": conv_id, "user": "user-001" }) ).json() print(f"Bot: {resp2['answer']}")
🚨 WARNING: When passing an existing `conversation_id`, all `inputs` values are ignored. Only `query` is processed. Use **Conversation Variables** to change variables mid-session.
Streaming vs Blocking Response
Blocking Mode
· Returns complete result when processing finishes
· Suitable for: Backend processing, batch jobs
· Default timeout: 60 seconds
Streaming Mode (Recommended)
· Returns incremental chunks via Server-Sent Events (SSE)
· Suitable for: Real-time chat, better UX
· No processing time limit
SSE Event Types
Event
Description
message
Response content (text chunk)
agent_message
Response from Agent mode
agent_thought
Agent reasoning process
message_file
File generated by AI
message_end
End of message, includes metadata
error
Error occurred during stream
ping
Keep-alive signal
Processing SSE in JavaScript
const response = await fetch('https://api.clickai.io/v1/chat-messages', { method: 'POST', headers: { 'Authorization': 'Bearer YOUR-SECRET-KEY', 'Content-Type': 'application/json' }, body: JSON.stringify({ inputs: {}, query: 'Hello', response_mode: 'streaming', conversation_id: '', user: 'user-001' }) }); const reader = response.body.getReader(); const decoder = new TextDecoder(); while (true) { const { done, value } = await reader.read(); if (done) break; const chunk = decoder.decode(value); const lines = chunk.split('\n'); for (const line of lines) { if (line.startsWith('data: ')) { const data = JSON.parse(line.slice(6)); if (data.event === 'message') { process.stdout.write(data.answer); } } } }
File Upload API
POST https://api.clickai.io/v1/files/upload
curl --location --request POST 'https://api.clickai.io/v1/files/upload' \ --header 'Authorization: Bearer YOUR-SECRET-KEY' \ --form 'file=@"/path/to/document.pdf"' \ --form 'user="user-abc-123"'
Use in chat with "files": [{"type": "document", "transfer_method": "local_file", "upload_file_id": "file-abc123"}]
Feedback API
POST https://api.clickai.io/v1/messages/{message_id}/feedbacks
{ "rating": "like", "user": "user-abc-123", "content": "Very helpful answer!" }
Conversations API
Action
Method
Endpoint
List conversations
GET
/v1/conversations?user=user-id&limit=20
Get messages
GET
/v1/messages?conversation_id=conv-id&user=user-id
Rename
POST
/v1/conversations/{id}/name
Delete
DELETE
/v1/conversations/{id}
Error Handling
Code
Description
200
Success
400
Bad Request
401
Unauthorized — Invalid API Key
403
Forbidden
404
Not Found
429
Rate limit exceeded
500
Internal Server Error
Rate Limits
Plan
Requests/min
Requests/day
Sandbox
100
10,000
Professional
500
100,000
Team
1,000
500,000
Enterprise
Custom
Custom
SDK & Libraries
Python SDK
from clickai import ClickAI client = ClickAI(api_key="YOUR-SECRET-KEY") response = client.chat.create(query="Hello", user="user-001") print(response.answer)
JavaScript SDK
import { ClickAI } from '@clickai/sdk'; const client = new ClickAI({ apiKey: 'YOUR-SECRET-KEY' }); const response = await client.chat.create({ query: 'Hello', user: 'user-001' }); console.log(response.answer);
📖 See also: [MCP Server](./02-mcp-server-en.md) · [Build](../en/01-build-en.md)
Last updated