> For the complete documentation index, see [llms.txt](https://docs.clickai.vn/clickai-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.clickai.vn/clickai-docs/clickai-docs-en/developer/integrate-clickai-via-restful-api.md). # Integrate ClickAI via RESTful 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 ### 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 '' \\\ -d 'page=1' \\\ -d 'page\_size=10' \\\ -d 'mode=workflow' \\\ -d 'workspace\_id=\' \\\ -H 'accept: application/json' \\\ -H 'authorization: Bearer \' ### Example — List Agent Chat Apps curl -G '' \\\ -d 'page=1' \\\ -d 'page\_size=10' \\\ -d 'mode=agent-chat' \\\ -d 'workspace\_id=\' \\\ -H 'accept: application/json' \\\ -H 'authorization: Bearer \' ### Example — Python import requests\ \ url = " 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 ### 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 '' \\\ \--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 = " 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(\ ' {\ 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 ### 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 '' \\\ \--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 = " 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 ### Example — cURL curl --location --request POST '' \\\ \--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 = " 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('', {\ 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 curl --location --request POST '' \\\ \--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 {\ "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)*