Agent API Creation and External Invocation

Objective: Generate an API Key for a published Agent so it can be called by external systems, and obtain the official API documentation for integration.

Create an API Key

Enter the Agent's API Console

On the Agent orchestration page, click API Console in the upper-right corner.
After entering, you will see the API channels list page.

Create an API Channel

Click Add a new channel.
In the pop-up window, fill in:
- Name: for example API
- Description: for example API
Click Save to save.

Enter the Channel's key page

Find the record you just created in the channel list.
Click Learn More to enter the API Keys page.

Generate an API Key

Click Add a key.
In the pop-up window, set:
- Name: for example API
- Deadline: select the validity period as needed (for example, 3 Months)
Click Save to generate the key.
Copy and securely save the Key immediately (it is usually no longer fully displayed after the page is closed).

Obtain the API documentation and integrate

On the API Keys page, click Access Document.
In the documentation, copy the following information for external system integration:
- Request URL (Endpoint)
- Authentication method (usually Authorization: Bearer <API_KEY>)
- Request body example (input parameters)
- Response body example (output fields)
The external system can call the Agent by sending an HTTP request according to the examples in the documentation.

Call the API and Chat with the Agent

API Key Authentication

Method: POST
Endpoint: https://{host}/webapi/lite_api/v2/api/chat-with-bot/chat
Header: api-key: YOUR_API_KEY

Key fields in the request body (JSON):

messages (required): an array of conversation messages; role supports user/ai/system/human/assistant
stream (optional, default false): whether to return a streaming response
show_tool_result (optional, default false): whether to return tool results or references
file_id (optional): file ID (string or array of strings)
workspace_id (optional): workspace ID (string or array of strings)
layout_mode (optional, default 0): 1 returns knowledge retrieval content, 0 for normal chat
skip_hint (optional, default false): whether to skip the PII prompt

Notes:

It is recommended that the role of the last message be human or user
For image input, you must first call the "Upload Image API" to obtain image_ids

Minimal request example:

{
	"messages": [
		{"role": "system", "content": "Today is Monday"},
		{
			"role": "user",
			"content": [
				{"type": "text", "text": "Please describe the following images"},
				{"type": "image_ids", "image_ids": ["uuid1", "uuid2"]}
			]
		}
	],
	"stream": false,
	"show_tool_result": false
}

Successful response highlights:

Non-streaming: data.full_output is the final answer, and data.tool_result is the optional tool result
Streaming: the event stream includes stream, tool_result, and end

Get Access Token

An Access Token is obtained in three steps: Create a Client → Query the Client to get credentials → Generate the Token.

1. Create a Client

Method: POST
Endpoint: https://{host}/webapi/lite_api/v1/admin/clients
Header: Authorization: Bearer YOUR_ADMIN_TOKEN

Key fields in the request body (JSON):

name (required): Client name
description (optional): Description
trusted domains (optional): List of trusted domains, defaults to an empty array

curl --location 'https://{host}/webapi/lite_api/v1/admin/clients' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer YOUR_ADMIN_TOKEN' \
  --data '{
    "name": "test",
    "description": "test",
    "trusted domains": []
  }'

The successful response will return client_id and client_secret. Save them securely.

2. Query Client List (Optional)

To view existing Clients and their client_id, use the following endpoint:

Method: GET
Endpoint: https://{host}/webapi/lite_api/v1/admin/clients?page=1&page_size=10
Header: Authorization: Bearer YOUR_ADMIN_TOKEN

curl --location 'https://{host}/webapi/lite_api/v1/admin/clients?page=1&page_size=10' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer YOUR_ADMIN_TOKEN'

3. Generate Access Token

Use the client_id and client_secret obtained in step 1 to generate an access token:

Method: POST
Endpoint: https://{host}/webapi/lite_api/v1/iam/client_token

Key fields in the request body (JSON):

client_id (required): The ID obtained when creating the Client
client_secret (required): The secret obtained when creating the Client
username (required): The associated username

curl --location 'https://{host}/webapi/lite_api/v1/iam/client_token' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --data '{
    "client_id": "YOUR_CLIENT_ID",
    "client_secret": "YOUR_CLIENT_SECRET",
    "username": "YOUR_USERNAME"
  }'

Successful response example:

{
  "code": 200,
  "data": {
    "access_token": "eyJhbGci...",
    "token_type": "Bearer",
    "expires_in": 3600
  },
  "message": "success"
}

Use the access_token value from the response as YOUR_ACCESS_TOKEN in the API below.

Access Token Authentication

Method: POST
Endpoint: https://{host}/webapi/lite_api/v2/api/chat-with-bot/{agent_id}
Header: Authorization: Bearer YOUR_ACCESS_TOKEN

Path parameters:

agent_id: the UUID of the target Agent (can be obtained from the Agent page URL)

Key fields in the request body (JSON):

messages (required): role is limited to user/human, and the maximum array length is 1
stream, show_tool_result, file_id, workspace_id, layout_mode, skip_hint (same as above)
conversation_id (optional): multi-turn conversation session ID; if not provided, the system creates one and returns it in the response

Minimal request example:

{
	"messages": [
		{
			"role": "user",
			"content": [
				{"type": "text", "text": "Please describe the following images"},
				{"type": "image_ids", "image_ids": ["uuid1", "uuid2"]}
			]
		}
	],
	"stream": false,
	"show_tool_result": false,
	"layout_mode": 0,
	"conversation_id": null
}

Successful response highlights:

data.conversation_id: used for reuse in subsequent multi-turn conversations
data.full_output: the final answer

Upload Images

Method: POST
New Endpoint (recommended): https://{host}/webapi/lite_api/v2/api/chat-with-bot/upload-images
Old Endpoint (to be deprecated soon): https://{host}/webapi/lite_api/v2/api/chat-with-bot/{agent_id}/upload-images
Header (example): api-key: YOUR_API_KEY
Content-Type: multipart/form-data

Request parameters:

files (required): one or more image files

Successful response example:

{
	"code": 201,
	"data": {
		"ids": ["2973a321-905d-4f07-9ad4-ff0ef47a174f"]
	},
	"message": "success"
}

Description:

Fill the returned ids into the image_ids field in messages[].content of the chat API to complete image-based Q&A.

Retrieving Images and Files from Chat Messages

After a chat message returns an image or file ID, additional API calls are required to obtain an accessible link or preview. The following explains the complete flow from "ID returned" to "final preview/download".

Image Retrieval Flow

Step 1: Extract the Image ID from the Message

In chat messages, images are returned using Markdown image syntax, with the temporary file ID embedded in the link:

![](/api/workspace/file/TemporaryFile/7485579177907720192)

Here, 7485579177907720192 is the file_id, used in the next step to obtain an accessible temporary link.

Step 2: Exchange the file_id for a Temporary Link

Method: POST
Endpoint: https://{host}/webapi/knowledge/v1/file/ekb-temporary
Header: authorization: Bearer YOUR_TOKEN

Key fields in the request body (JSON):

file_id (required): array of file IDs; supports multiple IDs in a single request

curl 'https://{host}/webapi/knowledge/v1/file/ekb-temporary' \
  -H 'accept: application/json, text/plain, */*' \
  -H 'authorization: Bearer YOUR_TOKEN' \
  -H 'content-type: application/json' \
  --data-raw '{"file_id":["7485579177907720192"]}'

The successful response returns a real accessible temporary file link:

https://{host}/webapi/knowledge/v1/file/ekb-temporary-file/<signed temporary file identifier>

Step 3: Access the Temporary Link

Send a GET request to the temporary link returned in the previous step to retrieve the image. The authorization header must be included, otherwise the request will return 401/403.

GET https://{host}/webapi/knowledge/v1/file/ekb-temporary-file/<signed temporary file identifier>
Header: authorization: Bearer YOUR_TOKEN

Notes:

The numeric ID in the message is only a file_id and cannot be accessed directly; you must first call ekb-temporary to obtain the real temporary link
The temporary link still requires authentication; the authorization header must be included when accessing it
If an image fails to load, check: ① whether the file_id is correct ② whether the Token has expired ③ whether the temporary link has expired and needs to be refreshed

File Retrieval Flow

Step 1: Identify File Messages

When a chat message has a category field of "tool", it indicates the message is file-related and will contain the corresponding document_id.

Step 2: Get File Details

Method: GET
Endpoint: https://{host}/webapi/knowledge/v1/rag/get_detail?document_id={document_id}
Header: authorization: Bearer YOUR_TOKEN

Request parameters:

document_id (Query String, required): the document ID obtained from the message

curl 'https://{host}/webapi/knowledge/v1/rag/get_detail?document_id=7485164512316755968' \
  -H 'accept: application/json, text/plain, */*' \
  -H 'authorization: Bearer YOUR_TOKEN' \
  -H 'content-type: application/json' \
  --data-raw '{}'

The response includes the id, objectType, filetype, and other fields needed for the preview API.

Step 3: Preview the File

Method: POST
Endpoint: https://{host}/webapi/knowledge/v1/file/ekb-preview
Header: authorization: Bearer YOUR_TOKEN

Key fields in the request body (JSON):

Parameter	Description
`id`	File ID (obtained from the `get_detail` response; may differ from `document_id`)
`objectType`	Object type (obtained from the `get_detail` response)
`filetype`	File type identifier (obtained from the `get_detail` response)

curl 'https://{host}/webapi/knowledge/v1/file/ekb-preview' \
  -H 'accept: application/json, text/plain, */*' \
  -H 'authorization: Bearer YOUR_TOKEN' \
  -H 'content-type: application/json' \
  --data-raw '{"id":"7485164641157386241","objectType":"2","filetype":1}'

Notes:

File messages are identified by category: "tool"
Call get_detail first to obtain the complete details (including objectType, filetype, etc. required by the preview API), then call ekb-preview to complete the preview
An expired Token will cause all APIs to return 401

Image vs. File API Comparison

Scenario	Message Identifier	Key APIs	Requires authorization
Image	Markdown image syntax `![](/api/workspace/file/TemporaryFile/{file_id})`	`ekb-temporary` → access temporary link	Yes (both steps)
File	`category: "tool"`	`get_detail` → `ekb-preview`	Yes (both steps)

Note: All API calls require a valid Bearer Token. An expired Token is the most common starting point for troubleshooting.

Create an API Key​

Enter the Agent's API Console​

Create an API Channel​

Enter the Channel's key page​

Generate an API Key​

Obtain the API documentation and integrate​

Call the API and Chat with the Agent​

API Key Authentication​

Get Access Token​

1. Create a Client​

2. Query Client List (Optional)​

3. Generate Access Token​

Access Token Authentication​

Upload Images​

Retrieving Images and Files from Chat Messages​

Image Retrieval Flow​

Step 1: Extract the Image ID from the Message​

Step 2: Exchange the file_id for a Temporary Link​

Step 3: Access the Temporary Link​

File Retrieval Flow​

Step 1: Identify File Messages​

Step 2: Get File Details​

Step 3: Preview the File​

Image vs. File API Comparison​

Create an API Key

Enter the Agent's API Console

Create an API Channel

Enter the Channel's key page

Generate an API Key

Obtain the API documentation and integrate

Call the API and Chat with the Agent

API Key Authentication

Get Access Token

1. Create a Client

2. Query Client List (Optional)

3. Generate Access Token

Access Token Authentication

Upload Images

Retrieving Images and Files from Chat Messages

Image Retrieval Flow

Step 1: Extract the Image ID from the Message

Step 2: Exchange the file_id for a Temporary Link

Step 3: Access the Temporary Link

File Retrieval Flow

Step 1: Identify File Messages

Step 2: Get File Details

Step 3: Preview the File

Image vs. File API Comparison