PAI-RAG Service API Reference (v0.4.x) - Platform For AI

This topic describes the API operations for PAI-RAG service v0.4.x, including request examples and core concepts to help you integrate PAI-RAG into your applications.

Preparations: Obtain the service endpoint and token

Before you call the RAG service API, you must obtain the service endpoint and authentication token. All API requests must include the EAS_TOKEN in the HTTP Authorization header.

The $EAS_SERVICE_URL and $EAS_TOKEN used in this topic are environment variables. Set them before use. To obtain them, perform the following steps:

Log on to the PAI console. Select a region on the top of the page. Then, select the desired workspace and click Elastic Algorithm Service (EAS).
Click the name of the service. In the Basic Information section, click View Endpoint Information.
On the Invocation Method page, obtain the Internet Endpoint (EAS_SERVICE_URL) and Token (EAS_TOKEN).
Important
- Remove the trailing slash (/) from the EAS_SERVICE_URL.
- Use the Internet Endpoint if the client can access the Internet.
- Use the VPC endpoint if the client is in the same virtual private cloud (VPC) as the RAG service.

After you obtain the values, set them as environment variables to simplify subsequent API calls:

export EAS_SERVICE_URL="your_service_endpoint"
export EAS_TOKEN="your_token"

You can then use $EAS_SERVICE_URL and $EAS_TOKEN to reference these values in subsequent curl commands.

Chat API

The Chat API is a streaming chat interface that supports intelligent agents and retrieval-augmented generation (RAG). It extends the OpenAI-compatible chat protocol to support advanced features such as knowledge base retrieval, multi-step reasoning, and external tool calling. It is suitable for building intelligent conversational systems, Q&A chatbots, and other similar scenarios.

Important

To call the Chat API, you must configure your own chat application. For example, you can name the application my_assistant and select the appropriate knowledge base and web search configurations.

POST $EAS_SERVICE_URL/v1/chat/completions

Description: Initiates a chat request. You can call a pre-configured chat application by specifying the model parameter. The application can be associated with a knowledge base, search tools, and other resources.

Request body (application/json)

Field	Type	Required	Description
`model`	String	Yes	The name of the chat application you created.
`messages`	Array	Yes	A list of conversation history messages in OpenAI format.
`stream`	Boolean	No	Specifies whether to return the response in streaming mode. The default value is `false`.

Request body example

{
    "model": "my_assistant",
    "messages": [
        {
            "role": "user",
            "content": "What are the core features of PAI-RAG?"
        }
    ],
    "stream": true
}

Response body

The response format is compatible with the OpenAI chat.completions API.

OpenAI client call example:

from openai import OpenAI

import os
EAS_ENDPOINT = os.getenv("EAS_SERVICE_URL")
EAS_TOKEN = os.getenv("EAS_TOKEN")
client = OpenAI(
    base_url=EAS_ENDPOINT,
    api_key=EAS_TOKEN
)

response = client.chat.completions.create(
    model="my_assistant",  # Replace with the actual name of your chat application.
    messages=[
        {"role": "user", "content": "Hello"}
    ],
    stream=True
)

for chunk in response:
    print(chunk.choices[0].delta.content)

Knowledge base management

Create a knowledge base

Creates a new knowledge base. You can specify its configurations for data chunking, embedding, and retrieval.

POST $EAS_SERVICE_URL/v1/config/knowledgebases

Request	curl -X POST "$EAS_SERVICE_URL/v1/config/knowledgebases" \ --header "Authorization: Bearer $EAS_TOKEN" \ --header 'Content-Type: application/json' \ --data '{ "name": "example_kb", "description": "This is an example knowledge base", "chunk_config": { "parser_type": "structure", "separator": "\n\n", "chunk_size": 1000, "chunk_overlap": 50 }, "embedding_model": "BAAI/bge-m3", "retrieval_config": { "retrieval_mode": "hybrid", "top_k": 5, "similarity_threshold": 0.2, "enable_rerank": true, "rerank_model": "qwen3-reranker", "vector_weight": 0.7 } }'
Headers
Content-Type `string` (required) The content type of the request. This parameter must be set to `application/json`.
Authorization `string` (required) The authentication token for the request. Use your EAS_TOKEN.
Request Body
name `string` (required) The name of the knowledge base.
description `string` (optional) The description of the knowledge base.
embedding_model `string` (required) The name or path of the embedding model. Local and remote models are supported.
chunk_config `object` (optional) The data chunking configuration. Properties parser_type `string` (optional) The parser type. Valid values: `structure`, `table`, `token`, and `paragraph`. separator `string` (optional) A custom separator. chunk_size `int` (optional) The maximum length of each data chunk, in characters. chunk_overlap `int` (optional) The overlap length between adjacent data chunks, in characters. image_caption_model `string` (optional) The image understanding model.
retrieval_config `object` (optional) The retrieval policy configuration. Properties retrieval_mode `string` (optional) The retrieval mode. Valid values: `hybrid` (hybrid retrieval) and `vector` (vector retrieval). top_k `int` (optional) The number of most relevant data chunks to return. similarity_threshold `float` (optional) The similarity score threshold. Results with scores below this threshold are filtered out. enable_rerank `bool` (optional) Specifies whether to enable a reranker model to optimize retrieval results. Important You must configure the reranker model in the PAI-RAG Web UI before you can use it. rerank_model `string` (optional) The name or path of the reranker model. vector_weight `float` (optional) The weight of vector retrieval in hybrid retrieval.

Response example

{
    "code": 200,
    "message": "Knowledge base created successfully.",
    "data": {
        "name": "example_kb",
        "tenant_id": "__default_tenant_id__",
        "created_at": "2026-02-27T02:35:01.121035Z",
        "description": "This is an example knowledge base",
        "updated_at": "2026-02-27T02:35:01.121046Z",
        "chunk_config": {
            "chunk_size": 1000,
            "chunk_overlap": 50,
            "parser_type": "structure",
            "separator": "\n\n",
            "image_caption_model": null,
            "image_caption_provider_name": "openai_like",
            "table_config": {
                "concat_rows": false,
                "row_joiner": "\n",
                "header_index_max": 0,
                "format_sheet_data_to_json": false,
                "sheet_column_filters": null,
                "question_column_index": 0,
                "answer_column_index": 1
            }
        },
        "id": "a4815ee728a64e9c83a3d891dbc1c956",
        "embedding_model": "BAAI/bge-m3",
        "embedding_provider_name": "openai_like",
        "retrieval_config": {
            "retrieval_mode": "hybrid",
            "top_k": 5,
            "similarity_threshold": 0.2,
            "vector_weight": 0.7,
            "enable_rerank": true,
            "rerank_model": "qwen3-reranker",
            "rerank_provider_name": "openai_like",
            "rerank_top_k": 5
        }
    }
}

Get a list of knowledge bases

Retrieves a list of knowledge bases for the current service. Paging is supported.

GET $EAS_SERVICE_URL/v1/config/knowledgebases?page=1&size=10

Request	`curl -X GET "$EAS_SERVICE_URL/v1/config/knowledgebases?page=1&size=10" \ --header "Authorization: Bearer $EAS_TOKEN"`
Headers
Authorization `string` (required) The authentication token for the request. Use your EAS_TOKEN.
URL query parameters
page `int` (optional) The page number. Default value: `1`.
size `int` (optional) The number of entries to return on each page. Default value: `10`. Maximum value: `1000`.

Response example

{
    "code": 200,
    "message": "Successfully retrieved the list of knowledge bases.",
    "data": {
        "items": [
            {
                "name": "example_kb",
                "tenant_id": "__default_tenant_id__",
                "created_at": "2026-02-27T02:35:01.121035Z",
                "description": "This is an example knowledge base",
                "updated_at": "2026-02-27T02:35:01.121046Z",
                "chunk_config": {
                    "chunk_size": 1000,
                    "chunk_overlap": 50,
                    "parser_type": "structure",
                    "separator": "\n\n",
                    "image_caption_model": null,
                    "image_caption_provider_name": "openai_like",
                    "table_config": {
                        "concat_rows": false,
                        "row_joiner": "\n",
                        "header_index_max": 0,
                        "format_sheet_data_to_json": false,
                        "sheet_column_filters": null,
                        "question_column_index": 0,
                        "answer_column_index": 1
                    }
                },
                "id": "a4815ee728a64e9c83a3d891dbc1c956",
                "embedding_model": "BAAI/bge-m3",
                "embedding_provider_name": "openai_like",
                "retrieval_config": {
                    "retrieval_mode": "hybrid",
                    "top_k": 5,
                    "similarity_threshold": 0.2,
                    "vector_weight": 0.7,
                    "enable_rerank": true,
                    "rerank_model": "qwen3-reranker",
                    "rerank_provider_name": "openai_like",
                    "rerank_top_k": 5
                },
                "file_count": 0
            },
            {
                "name": "iPhone16",
                "tenant_id": "__default_tenant_id__",
                "created_at": "2026-02-25T08:57:07.085859Z",
                "description": "",
                "updated_at": "2026-02-25T09:01:40.035292Z",
                "chunk_config": {
                    "chunk_size": 1000,
                    "chunk_overlap": 50,
                    "parser_type": "structure",
                    "separator": "\n\n",
                    "image_caption_model": null,
                    "image_caption_provider_name": "openai_like",
                    "table_config": {
                        "concat_rows": false,
                        "row_joiner": "\n",
                        "header_index_max": 0,
                        "format_sheet_data_to_json": false,
                        "sheet_column_filters": null,
                        "question_column_index": 0,
                        "answer_column_index": 1
                    }
                },
                "id": "08f6bb77fd3441099fb5b19e4f10d67b",
                "embedding_model": "BAAI/bge-m3",
                "embedding_provider_name": "openai_like",
                "retrieval_config": {
                    "retrieval_mode": "vector",
                    "top_k": 5,
                    "similarity_threshold": 0.2,
                    "vector_weight": 0.7,
                    "enable_rerank": false,
                    "rerank_model": "",
                    "rerank_provider_name": "openai_like",
                    "rerank_top_k": 5
                },
                "file_count": 2
            }
        ],
        "total": 2,
        "pages": 1,
        "page": 1,
        "size": 10
    }
}

Get a specific knowledge base

Retrieves the details of a specified knowledge base.

GET $EAS_SERVICE_URL/v1/config/knowledgebases/{kb_id}

Request	`curl -X GET "$EAS_SERVICE_URL/v1/config/knowledgebases/{kb_id}" \ --header "Authorization: Bearer $EAS_TOKEN"`
Headers
Authorization `string` (required) The authentication token for the request. Use your EAS_TOKEN.
URL path parameters
kb_id `string` (required) The unique identifier of the knowledge base.

Response example

{
    "code": 200,
    "message": "Knowledge base queried successfully.",
    "data": {
        "id": "a4815ee728a64e9c83a3d891dbc1c956",
        "tenant_id": "__default_tenant_id__",
        "name": "example_kb",
        "description": "This is an example knowledge base",
        "created_at": "2026-02-27T02:35:01.121035+00:00",
        "updated_at": "2026-02-27T02:35:01.121046+00:00",
        "embedding_model": "BAAI/bge-m3",
        "embedding_provider_name": "openai_like",
        "chunk_config": {
            "chunk_size": 1000,
            "chunk_overlap": 50,
            "parser_type": "structure",
            "separator": "\n\n",
            "image_caption_model": null,
            "image_caption_provider_name": "openai_like",
            "table_config": {
                "concat_rows": false,
                "row_joiner": "\n",
                "header_index_max": 0,
                "format_sheet_data_to_json": false,
                "sheet_column_filters": null,
                "question_column_index": 0,
                "answer_column_index": 1
            }
        },
        "retrieval_config": {
            "retrieval_mode": "hybrid",
            "top_k": 5,
            "similarity_threshold": 0.2,
            "vector_weight": 0.7,
            "enable_rerank": true,
            "rerank_model": "qwen3-reranker",
            "rerank_provider_name": "openai_like",
            "rerank_top_k": 5
        }
    }
}

Update a knowledge base

Updates an existing knowledge base.

PUT $EAS_SERVICE_URL/v1/config/knowledgebases/{kb_id}

Request	curl -X PUT "$EAS_SERVICE_URL/v1/config/knowledgebases/{kb_id}" \ --header "Authorization: Bearer $EAS_TOKEN" \ --header 'Content-Type: application/json' \ --data '{ "name": "example_kb", "description": "Example", "id": "kb4451867a6d0f4166babddb7a048a311d", "embedding_model": "BAAI/bge-m3", "chunk_config": { "chunk_size": 1000, "chunk_overlap": 50, "parser_type": "structure", "separator": "\n\n" }, "retrieval_config": { "retrieval_mode": "hybrid", "top_k": 6, "similarity_threshold": 0.2, "vector_weight": 0.7, "enable_rerank": true, "rerank_model": "qwen3-reranker" } }'
Headers
Content-Type `string` (required) The content type of the request. This parameter must be set to `application/json`.
Authorization `string` (required) The authentication token for the request. Use your EAS_TOKEN.
URL path parameters
kb_id `string` (required) The unique identifier of the knowledge base.
Request Body
The request body parameters are the same as those for the create knowledge base operation, including name, description, embedding_model, chunk_config, and retrieval_config.

Response example

{
    "code": 200,
    "message": "Knowledge base updated successfully.",
    "data": {
        "name": "example_kb",
        "tenant_id": "__default_tenant_id__",
        "created_at": "2026-02-27T02:35:01.121035Z",
        "description": "Example",
        "updated_at": "2026-02-27T07:26:55.543217Z",
        "chunk_config": {
            "chunk_size": 1000,
            "chunk_overlap": 50,
            "parser_type": "structure",
            "separator": "\n\n",
            "image_caption_model": null,
            "image_caption_provider_name": "openai_like",
            "table_config": {
                "concat_rows": false,
                "row_joiner": "\n",
                "header_index_max": 0,
                "format_sheet_data_to_json": false,
                "sheet_column_filters": null,
                "question_column_index": 0,
                "answer_column_index": 1
            }
        },
        "id": "a4815ee728a64e9c83a3d891dbc1c956",
        "embedding_model": "BAAI/bge-m3",
        "embedding_provider_name": "openai_like",
        "retrieval_config": {
            "retrieval_mode": "hybrid",
            "top_k": 6,
            "similarity_threshold": 0.2,
            "vector_weight": 0.7,
            "enable_rerank": true,
            "rerank_model": "qwen3-reranker",
            "rerank_provider_name": "openai_like",
            "rerank_top_k": 5
        }
    }
}

Delete a specific knowledge base

Deletes a specified knowledge base and all its files and indexes. This operation is irreversible and should be used with caution.

DELETE $EAS_SERVICE_URL/v1/config/knowledgebases/{kb_id}

Request	`curl -X DELETE "$EAS_SERVICE_URL/v1/config/knowledgebases/{kb_id}" \ --header "Authorization: Bearer $EAS_TOKEN"`
Headers
Authorization `string` (required) The authentication token for the request. Use your EAS_TOKEN.
URL path parameters
kb_id `string` (required) The unique identifier of the knowledge base.

Response example

{"code":200,"message":"Knowledge base deleted successfully.","data":null}

File management

Upload files

Uploads one or more files to a specified knowledge base. This is an asynchronous operation that immediately returns file information while parsing and indexing are performed in the background. Supported file formats include PDF, DOCX, and TXT.

POST $EAS_SERVICE_URL/v1/config/knowledgebases/{kb_id}/files

Request	`curl -X POST "$EAS_SERVICE_URL/v1/config/knowledgebases/{kb_id}/files" \ --header "Authorization: Bearer $EAS_TOKEN" \ --header 'Content-Type: multipart/form-data' \ --form 'files=@"/path/to/your/file.pdf"'`
Headers
Content-Type `string` (required) The content type of the request. This parameter must be set to `multipart/form-data`.
Authorization `string` (required) The authentication token for the request. Use your EAS_TOKEN.
URL path parameters
kb_id `string` (required) The unique identifier of the knowledge base.
Request Body parameters
files `file` (required) The file or files to upload. PDF, DOCX, and TXT are supported. You can upload multiple files at once.

Response example

{
    "code": 200,
    "message": "File upload successful",
    "data": [
        {
            "file_content_length": 0,
            "status": "pending",
            "file_source": null,
            "failed_reason": null,
            "file_name": "EAS_model_service_overview.pdf",
            "active": true,
            "tenant_id": "__default_tenant_id__",
            "file_path": "a4815ee728a64e9c83a3d891dbc1c956/docs/EAS_model_service_overview.pdf",
            "created_at": "2026-02-27T07:30:10.875488Z",
            "id": "2540b5414f2d422291cea3162eb8e1e0",
            "file_extension": ".pdf",
            "updated_at": "2026-02-27T07:30:10.875503Z",
            "kb_id": "a4815ee728a64e9c83a3d891dbc1c956",
            "file_size": 889027,
            "file_metadata": {
                "file_path": "a4815ee728a64e9c83a3d891dbc1c956/docs/EAS_model_service_overview.pdf",
                "file_name": "EAS_model_service_overview.pdf",
                "file_size": 889027,
                "file_extension": ".pdf"
            },
            "message_id": "tmp-1772177410",
            "file_md5": "f4b60d2b9fd9edec06649ce7b5d65cb0",
            "chunk_config": {
                "chunk_size": 1000,
                "chunk_overlap": 50,
                "parser_type": "structure",
                "separator": "\n\n",
                "image_caption_model": null,
                "image_caption_provider_name": "openai_like",
                "table_config": {
                    "concat_rows": false,
                    "row_joiner": "\n",
                    "header_index_max": 0,
                    "format_sheet_data_to_json": false,
                    "sheet_column_filters": null,
                    "question_column_index": 0,
                    "answer_column_index": 1
                }
            },
            "file_content": "",
            "file_version": 1772177410
        }
    ]
}

List files

Lists the files in a specified knowledge base. You can filter the files by name and status, and use paging.

GET $EAS_SERVICE_URL/v1/config/knowledgebases/{kb_id}/files

Request	`curl -X GET "$EAS_SERVICE_URL/v1/config/knowledgebases/{kb_id}/files?query=EAS&status=succeeded&page=1&size=10" \ --header "Authorization: Bearer $EAS_TOKEN"`
Headers
Authorization `string` (required) The authentication token for the request. Use your EAS_TOKEN.
URL path parameters
kb_id `string` (required) The unique identifier of the knowledge base.
URL query parameters
query `string` (optional) Performs a fuzzy match on the file name.
status `string` (optional) Filters files by processing status. If you do not specify this parameter, files in all statuses are returned. Valid values: `pending`, `succeeded`, `failed`, `persisting` (indexing), and `parsing`.
page `int` (optional) The page number. Default value: 1.
size `int` (optional) The number of entries to return on each page. Default value: 10.

Response example

{
    "code": 200,
    "message": "File list queried successfully",
    "data": {
        "items": [
            {
                "file_content_length": 0,
                "status": "succeeded",
                "file_source": null,
                "failed_reason": null,
                "file_name": "EAS_model_service_overview.pdf",
                "active": true,
                "tenant_id": "__default_tenant_id__",
                "file_path": "a4815ee728a64e9c83a3d891dbc1c956/docs/EAS_model_service_overview.pdf",
                "created_at": "2026-02-27T07:30:10.875488Z",
                "id": "2540b5414f2d422291cea3162eb8e1e0",
                "file_extension": ".pdf",
                "updated_at": "2026-02-27T07:30:10.875503Z",
                "kb_id": "a4815ee728a64e9c83a3d891dbc1c956",
                "file_size": 889027,
                "file_metadata": {
                    "file_path": "a4815ee728a64e9c83a3d891dbc1c956/docs/EAS_model_service_overview.pdf",
                    "file_name": "EAS_model_service_overview.pdf",
                    "file_size": 889027,
                    "file_extension": ".pdf"
                },
                "message_id": "tmp-1772177410",
                "file_md5": "f4b60d2b9fd9edec06649ce7b5d65cb0",
                "chunk_config": null,
                "file_content": "",
                "file_version": 1772177410
            }
        ],
        "total": 1,
        "pages": 1,
        "page": 1,
        "size": 10
    }
}

Get file details

Retrieves the details of a file. This operation is often used to poll the file processing status.

GET $EAS_SERVICE_URL/v1/config/knowledgebases/{kb_id}/files/{file_id}

Request	`curl -X GET "$EAS_SERVICE_URL/v1/config/knowledgebases/{kb_id}/files/{file_id}" \ --header "Authorization: Bearer $EAS_TOKEN"`
Headers
Authorization `string` (required) The authentication token for the request. Use your EAS_TOKEN.
URL path parameters
kb_id `string` (required) The unique identifier of the knowledge base.
file_id `string` (required) The unique identifier of the file.

Response example

{
    "code": 200,
    "message": "File query successful",
    "data": {
        "file_content_length": 0,
        "status": "succeeded",
        "file_source": null,
        "failed_reason": null,
        "file_name": "EAS_model_service_overview.pdf",
        "active": true,
        "tenant_id": "__default_tenant_id__",
        "file_path": "a4815ee728a64e9c83a3d891dbc1c956/docs/EAS_model_service_overview.pdf",
        "created_at": "2026-02-27T07:30:10.875488Z",
        "id": "2540b5414f2d422291cea3162eb8e1e0",
        "file_extension": ".pdf",
        "updated_at": "2026-02-27T07:30:10.875503Z",
        "kb_id": "a4815ee728a64e9c83a3d891dbc1c956",
        "file_size": 889027,
        "file_metadata": {
            "file_path": "a4815ee728a64e9c83a3d891dbc1c956/docs/EAS_model_service_overview.pdf",
            "file_name": "EAS_model_service_overview.pdf",
            "file_size": 889027,
            "file_extension": ".pdf",
            "file_url": "http://rag-test-****.oss-cn-hangzhou.aliyuncs.com/pairag_knowledgebases%2Fa4815ee728a64e9c83a3d891dbc1c956%2Fdocs%2FEAS%E6%A8%A1%E5%9E%8B%E6%9C%8D%E5%8A%A1%E6%A6%82%E8%BF%B0.pdf?OSSAccessKeyId=******&Expires=1772181413&Signature=IME****MxJ7Ys2%2BMwckrZsNfg%3D"
        },
        "message_id": "tmp-1772177410",
        "file_md5": "f4b60d2b9fd9edec06649ce7b5d65cb0",
        "chunk_config": null,
        "file_content": "",
        "file_version": 1772177410
    }
}

Reprocess a file

Triggers reprocessing for a file, such as a file that failed to process or whose content has been updated. This is an asynchronous operation that creates a new processing task and resets the file status to pending.

PUT $EAS_SERVICE_URL/v1/config/knowledgebases/{kb_id}/files/{file_id}

Request	`curl -X PUT "$EAS_SERVICE_URL/v1/config/knowledgebases/{kb_id}/files/{file_id}" \ --header "Authorization: Bearer $EAS_TOKEN" \ --header 'Content-Type: application/json' \`
Headers
Content-Type `string` (required) The content type of the request. This parameter must be set to `application/json`.
Authorization `string` (required) The authentication token for the request. Use your EAS_TOKEN.
URL path parameters
kb_id `string` (required) The unique identifier of the knowledge base.
file_id `string` (required) The unique identifier of the file.

Response example

{
    "code": 200,
    "message": "Successfully added 1 files to the reprocessing queue.",
    "data": 1
}

Delete a file

Deletes a specified file and its associated data chunks and indexes from a knowledge base.

DELETE $EAS_SERVICE_URL/v1/config/knowledgebases/{kb_id}/files/{file_id}

Request	`curl -X DELETE "$EAS_SERVICE_URL/v1/config/knowledgebases/{kb_id}/files/{file_id}" \ --header "Authorization: Bearer $EAS_TOKEN"`
Headers
Authorization `string` (required) The authentication token for the request. Use your EAS_TOKEN.
URL path parameters
kb_id `string` (required) The unique identifier of the knowledge base.
file_id `string` (required) The unique identifier of the file.

Response example

{
    "code": 200,
    "message": "Knowledge base file deleted successfully.",
    "data": null
}

Data chunk management

View file chunks

Retrieves the list of data chunks for a specified file after it has been processed. Paging is supported.

GET $EAS_SERVICE_URL/v1/config/knowledgebases/{kb_id}/files/{file_id}/chunks?page=1&size=10

Request	`curl -X GET "$EAS_SERVICE_URL/v1/config/knowledgebases/{kb_id}/files/{file_id}/chunks?page=1&size=10" \ --header "Authorization: Bearer $EAS_TOKEN"`
Headers
Authorization `string` (required) The authentication token for the request. Use your EAS_TOKEN.
URL path parameters
kb_id `string` (required) The unique identifier of the knowledge base.
file_id `string` (required) The unique identifier of the file.
URL query parameters
page `int` (optional) The page number. Default value: 1.
size `int` (optional) The number of entries to return on each page. Default value: 10.

Response example

{
    "code": 200,
    "message": "Chunk list retrieval successful",
    "data": {
        "items": [
            {
                "active": true,
                "text": "EAS Model Service Overview****** and other capabilities.\n\n",
                "chunk_metadata": {
                    "file_path": "a4815ee728a64e9c83a3d891dbc1c956/docs/EAS_model_service_overview.pdf",
                    "file_name": "EAS_model_service_overview.pdf",
                    "file_size": 889027,
                    "file_extension": ".pdf",
                    "page_bbox": "[{\"page_idx\":1, \"bbox\":[77.600088, 73.57552407360004, 551.0441759999999, 239.87664000000007]}]",
                    "token_count": 196,
                    "doc_id": "2540b5414f2d422291cea3162eb8e1e0",
                    "images_info": []
                },
                "file_id": "2540b5414f2d422291cea3162eb8e1e0",
                "file_version": 0,
                "index": 0,
                "updated_at": "2026-02-27T07:42:00.167502Z",
                "status": "succeeded",
                "tenant_id": "__default_tenant_id__",
                "id": "e2b0d936158f4656a6cacb5ab639de6d",
                "file_part": 0,
                "kb_id": "a4815ee728a64e9c83a3d891dbc1c956",
                "created_at": "2026-02-27T07:42:00.167488Z"
            }
        ],
        "total": 1,
        "pages": 1,
        "page": 1,
        "size": 10
    }
}

Update a single chunk

Updates the content or status of a single data chunk. For example, you can manually correct poorly chunked text or disable a data chunk to prevent it from being retrieved.

PUT $EAS_SERVICE_URL/v1/config/knowledgebases/{kb_id}/files/{file_id}/chunks/{chunk_id}

Request	`curl -X PUT "$EAS_SERVICE_URL/v1/config/knowledgebases/{kb_id}/files/{file_id}/chunks/{chunk_id}" \ --header "Authorization: Bearer $EAS_TOKEN" \ --header "Content-Type: application/json" \ --data '{ "text": "Updated data chunk text content...", "active": true }'`
Headers
Authorization `string` (required) The authentication token for the request. Use your EAS_TOKEN.
Content-Type `string` (required) application/json
URL path parameters
kb_id `string` (required) The unique identifier of the knowledge base.
file_id `string` (required) The unique identifier of the file.
chunk_id `string` (required) The unique identifier of the data chunk.
Request Body
text `string` (optional) The updated text content of the data chunk.
active `bool` (optional) Specifies whether to enable the data chunk. If set to false, the data chunk will not be retrieved.

Response example

{
    "code": 200,
    "message": "Chunk update successful",
    "data": {
        "active": true,
        "text": "Updated data chunk text content...",
        "chunk_metadata": {
            "file_path": "a4815ee728a64e9c83a3d891dbc1c956/docs/EAS_model_service_overview.pdf",
            "file_name": "EAS_model_service_overview.pdf",
            "file_size": 889027,
            "file_extension": ".pdf",
            "page_bbox": "[{\"page_idx\":1, \"bbox\":[77.600088, 73.57552407360004, 551.0441759999999, 239.87664000000007]}]",
            "token_count": 196,
            "doc_id": "2540b5414f2d422291cea3162eb8e1e0"
        },
        "file_id": "2540b5414f2d422291cea3162eb8e1e0",
        "file_version": 0,
        "index": 0,
        "updated_at": "2026-02-27T07:42:00.167502Z",
        "status": "succeeded",
        "tenant_id": "__default_tenant_id__",
        "id": "e2b0d936158f4656a6cacb5ab639de6d",
        "file_part": 0,
        "kb_id": "a4815ee728a64e9c83a3d891dbc1c956",
        "created_at": "2026-02-27T07:42:00.167488Z"
    }
}

Disable a chunk

Use the update chunk operation and set the active field to false.

Metadata management

Metadata adds structured information to your documents, which allows for more precise filtering during retrieval. For example, you can retrieve only documents published by the IT department after 2024.

Define metadata fields

Defines a metadata field schema for a knowledge base, including the field ID, name, and value type.

POST $EAS_SERVICE_URL/v1/config/knowledgebases/{kb_id}/metadata

Request	`curl -X POST "$EAS_SERVICE_URL/v1/config/knowledgebases/{kb_id}/metadata" \ --header "Authorization: Bearer $EAS_TOKEN" \ --header "Content-Type: application/json" \ --data '{ "kb_id": "kb9594e2d2d2744bf1acd4227a9202b90b", "name": "expire_period", "value_type": "datetime", "description": "Product expiration date" }'`
Headers
Authorization `string` (required) The authentication token for the request. Use your EAS_TOKEN.
Content-Type `string` (required) application/json
URL path parameters
kb_id `string` (required) The unique identifier of the knowledge base.
Request Body
kb_id `string` (required) The unique identifier of the knowledge base.
name `string` (required) The display name of the field. It must be 3 to 50 characters in length.
value_type `string` (required) The value type of the field. Valid values: `string`, `number`, and `datetime`.
description `string` (optional) The description of the field.

Response example

{
    "code": 200,
    "message": "Metadata created successfully.",
    "data": {
        "value_type": "datetime",
        "kb_id": "a4815ee728a64e9c83a3d891dbc1c956",
        "created_at": "2026-02-27T07:49:19.964621Z",
        "name": "expire_period",
        "id": "d2b5ef3cf07d459da7b91b83dbb0a533",
        "tenant_id": "__default_tenant_id__",
        "description": "Product expiration date",
        "updated_at": "2026-02-27T07:49:19.964632Z"
    }
}

List metadata

Lists all defined metadata fields for the knowledge base.

GET $EAS_SERVICE_URL/v1/config/knowledgebases/{kb_id}/metadata

Request	`curl -X GET "$EAS_SERVICE_URL/v1/config/knowledgebases/{kb_id}/metadata" \ --header "Authorization: Bearer $EAS_TOKEN"`
Headers
Authorization `string` (required) The authentication token for the request. Use your EAS_TOKEN.
URL path parameters
kb_id `string` (required) The unique identifier of the knowledge base.

Response example

{
    "code": 200,
    "message": "List metadata success.",
    "data": {
        "items": [
            {
                "value_type": "datetime",
                "kb_id": "a4815ee728a64e9c83a3d891dbc1c956",
                "created_at": "2026-02-27T07:49:19.964621Z",
                "name": "expire_period",
                "id": "d2b5ef3cf07d459da7b91b83dbb0a533",
                "tenant_id": "__default_tenant_id__",
                "description": "Product expiration date",
                "updated_at": "2026-02-27T07:49:19.964632Z",
                "count": 0
            }
        ],
        "total": 1,
        "pages": 1,
        "page": 1,
        "size": 20
    }
}

Delete metadata

Deletes a specified metadata field from the knowledge base.

DELETE $EAS_SERVICE_URL/v1/config/knowledgebases/{kb_id}/metadata/{metadata_id}

Request	`curl -X DELETE "$EAS_SERVICE_URL/v1/config/knowledgebases/{kb_id}/metadata/{metadata_id}" \ --header "Authorization: Bearer $EAS_TOKEN"`
Headers
Authorization `string` (required) The authentication token for the request. Use your EAS_TOKEN.
URL path parameters
kb_id `string` (required) The unique identifier of the knowledge base.
metadata_id `string` (required) The metadata ID.

Response example

{
    "code": 200,
    "message": "Delete metadata success.",
    "data": null
}

Bind file-level metadata

Binds metadata values to a file. Note: This operation overwrites existing data. Each call completely replaces all metadata for the file. To avoid data loss, first use a GET request to retrieve the existing metadata, modify it locally, and then submit the complete list using this operation.

POST $EAS_SERVICE_URL/v1/config/knowledgebases/{kb_id}/files/{file_id}/metadata

Request	`curl -X POST "$EAS_SERVICE_URL/v1/config/knowledgebases/{kb_id}/files/{file_id}/metadata" \ --header "Authorization: Bearer $EAS_TOKEN" \ --header "Content-Type: application/json" \ --data '{ "entries": [ {"name": "expire_period", "value": 1764574102000}, {"name": "category", "value": "food"}, {"name": "price", "value": 12} ] }'`
Headers
Authorization `string` (required) The authentication token for the request. Use your EAS_TOKEN.
Content-Type `string` (required) application/json
URL path parameters
kb_id `string` (required) The unique identifier of the knowledge base.
file_id `string` (required) The unique identifier of the file.
Request Body
entries `array` (required) A list of metadata entries. Properties name `string` (required) The display name of the metadata field. It must be defined at the knowledge base level. value `string/number` (required) The specific value for the field. The type must match the definition.

Response example

{
    "code": 200,
    "message": "Set file metadata success.",
    "data": {
        "file_content_length": 0,
        "status": "succeeded",
        "file_source": null,
        "failed_reason": null,
        "file_name": "EAS_model_service_overview.pdf",
        "active": true,
        "tenant_id": "__default_tenant_id__",
        "file_path": "a4815ee728a64e9c83a3d891dbc1c956/docs/EAS_model_service_overview.pdf",
        "created_at": "2026-02-27T07:30:10.875488Z",
        "id": "2540b5414f2d422291cea3162eb8e1e0",
        "file_extension": ".pdf",
        "updated_at": "2026-02-27T07:41:59.360291Z",
        "kb_id": "a4815ee728a64e9c83a3d891dbc1c956",
        "file_size": 889027,
        "file_metadata": {
            "file_path": "a4815ee728a64e9c83a3d891dbc1c956/docs/EAS_model_service_overview.pdf",
            "file_name": "EAS_model_service_overview.pdf",
            "file_size": 889027,
            "file_extension": ".pdf",
            "expire_period": 1764574102000,
            "category": "food"
        },
        "message_id": "tmp-1772177410",
        "file_md5": "f4b60d2b9fd9edec06649ce7b5d65cb0",
        "chunk_config": null,
        "file_content": "",
        "file_version": 1772178119
    }
}

Retrieval API

Hybrid retrieval (text + vector + metadata filtering)

Performs a retrieval operation on a specified knowledge base. Supports hybrid retrieval with text, vectors, and metadata filtering.

POST $EAS_SERVICE_URL/v1/retrieval

Request	curl -X POST "$EAS_SERVICE_URL/v1/retrieval" \ --header "Authorization: Bearer $EAS_TOKEN" \ --header "Content-Type: application/json" \ --data '{ "query": "recommendation system", "knowledge_id": "kbdeec6a87e7b342b6a0da7e67a171fbb4", "metadata_condition": { "conditions": [ {"name": "department", "value": "i", "comparison_operator": "start with"}, {"name": "age", "value": "23", "comparison_operator": "<"} ], "logical_operator": "and" }, "retrieval_setting": { "top_k": 2, "score_threshold": 0.4 } }'
Headers
Authorization `string` (required) The authentication token for the request. Use your EAS_TOKEN.
Content-Type `string` (required) application/json
Request Body
query `string` (required) The query text for retrieval.
knowledge_id `string` (required) The ID of the target knowledge base to retrieve from.
user_id `string` (optional) The unique identifier for the user, used for personalization or log tracking.
metadata_condition `object` (optional) The metadata filter conditions. Includes `logical_operator` (`and` or `or`) and `conditions` (a list of filter conditions). Properties logical_operator `string` (optional) The logical relationship between multiple conditions. The default value is `and`. Valid values are `and` and `or`. conditions `array` (optional) A list of conditions. Properties name `string` (required) The ID of the metadata field. value `string/number` (required) The value to use for comparison. comparison_operator `string` (required) The comparison operator. Valid values empty: The value is not configured or is empty. not empty: The value is configured and not empty. contains: Contains a specific value. This operator applies to the string type. not contains: Does not contain a specific value. This operator applies to the string type. start with: Starts with a specific value. This operator applies to the string type. end with: Ends with a specific value. This operator applies to the string type. =: Equal to. This operator applies to number and datetime types. ≠: Not equal to. This operator applies to number and datetime types. ≥: Greater than or equal to. This operator applies to number and datetime types. ≤: Less than or equal to. This operator applies to number and datetime types. >: Greater than. This operator applies to number and datetime types. <: Less than. This operator applies to number and datetime types.
retrieval_setting `object` (optional) Per-request retrieval settings that override the knowledge base defaults. Properties top_k `int` (optional) The number of most relevant data chunks to return. score_threshold `float` (optional) The similarity score threshold.

Response example

{
    "records": [
        {
            "content": "EasyRec is an easy-to-use recommendation framework...",
            "score": 0.5892808330916407,
            "title": "EasyRec.txt",
            "metadata": {
                "file_name": "EasyRec.txt",
                "department": "it"
            }
        }
    ]
}

Configure a code sandbox

Create or update a sandbox

Request	`curl -X POST "$EAS_SERVICE_URL/api/config/code_sandbox" \ -H "Authorization: Bearer $EAS_TOKEN" \ -H 'Content-Type: application/json' \ -d '{ "type": "aliyun-fc", "aliyun_id": "your-aliyun-id", "interpreter_id": "your-interpreter-id", "enabled": true }'`
Headers
Content-Type `string` (required) The content type of the request. This parameter must be set to `application/json`.
Authorization `string` (required) The authentication token for the request. Use your EAS_TOKEN.
Request Body
type `string` (required) The sandbox type. Currently, only Alibaba Cloud FC sandboxes are supported. The value must be `aliyun-fc`.
aliyun_id `string` (required) Your Alibaba Cloud account ID.
interpreter_id `string` (required) The code interpreter ID.
enabled `bool` (required) Specifies whether to enable the sandbox feature.

Query the current sandbox configuration

curl -X GET "$EAS_SERVICE_URL/api/config/code_sandbox"

Configure FAQs

Base paths: /v1/config/apps (application configuration), /v1/faq-retrieval (FAQ retrieval)

All requests must include authentication, such as Authorization: Bearer YOUR_BEARER_TOKEN. You must also replace {EAS_SERVICE_URL} with the actual service endpoint.

Enable and configure FAQs

You can enable FAQs and write configurations by updating the application.

PUT {EAS_SERVICE_URL}/v1/config/apps/{id}

Request	curl -X PUT "$EAS_SERVICE_URL/v1/config/apps/{id}" \ -H "Authorization: Bearer $EAS_TOKEN" \ -H 'Content-Type: application/json' \ -d '{ "app_id": "your_app_id", "description": "Application description", "model_id": "your_model_id", "kb_ids": [], "enable_faq": true, "faq_config": { "active": true, "similarity_threshold": 0.8, "embedding_model": "BAAI/bge-m3", "enable_question_in_retrieval": true, "enable_question_in_response": true, "enable_answer_in_retrieval": false, "enable_answer_in_response": true, "return_direct": false } }'
Headers
Content-Type `string` (required) The content type of the request. This parameter must be set to `application/json`.
Authorization `string` (required) The authentication token for the request. Use your EAS_TOKEN.
URL path parameters
id `string` (required) The primary key ID of the application. You can obtain this ID using the Query Application API.
Request Body
app_id `string` (required) The app ID of the application.
description `string` (optional) The application description.
model_id `string` (required) The base model.
kb_ids `array` (optional) The knowledge bases used by the application. You can select multiple knowledge bases.
enable_faq `bool` (optional) Specifies whether to enable FAQs.
faq_config `object` (optional) The FAQ configuration. Properties active `bool` (optional) Specifies whether to enable the FAQ configuration. similarity_threshold `float` (optional) The similarity threshold. A value from 0.8 to 1.0 is recommended. embedding_model `string` (optional) The embedding model ID. enable_question_in_retrieval `bool` (optional) Specifies whether the question is included in the retrieval. enable_question_in_response `bool` (optional) Specifies whether the question is included in the response. enable_answer_in_retrieval `bool` (optional) Specifies whether the answer is included in the retrieval. enable_answer_in_response `bool` (optional) Specifies whether the answer is included in the response. return_direct `bool` (optional) Specifies whether to return the tool result directly without passing it to the large language model (LLM).

Query an application

curl -X GET "$EAS_SERVICE_URL/v1/config/apps?app_id=your_app_id" \
  -H "Authorization: Bearer $EAS_TOKEN"

You can obtain the app_id from the following figure.

Create a single FAQ

curl -X POST "$EAS_SERVICE_URL/v1/config/apps/{app_id}/faqs" \
  -H "Authorization: Bearer $EAS_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "question": "How do I reset my password?",
    "answer": "Click 'Forgot Password' on the login page and follow the prompts.",
    "active": true
  }'

Query a list of FAQs (with paging)

curl -X GET "$EAS_SERVICE_URL/v1/config/apps/{app_id}/faqs?page=1&size=100" \
  -H "Authorization: Bearer $EAS_TOKEN"

Update a single FAQ

curl -X PUT "$EAS_SERVICE_URL/v1/config/apps/{app_id}/faqs/{faq_item_id}" \
  -H "Authorization: Bearer $EAS_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "question": "How do I change my password?",
    "answer": "After you log in, go to Account Settings > Security to change it.",
    "active": true
  }'

Delete a single FAQ

curl -X DELETE "$EAS_SERVICE_URL/v1/config/apps/{app_id}/faqs/{faq_item_id}" \
  -H "Authorization: Bearer $EAS_TOKEN"

Batch upload an FAQ file (Excel)

This operation uses multipart/form-data. The upload field name is files, and multiple files are supported. The table_config parameter, which is a JSON string for table header and column mapping, is optional. .xlsx and .xls file formats are supported.

curl -X POST "$EAS_SERVICE_URL/v1/config/apps/{app_id}/faq-files" \
  -H "Authorization: Bearer $EAS_TOKEN" \
  -F 'files=@/path/to/faq.xlsx' \
  -F 'table_config={"header_index_max":0,"question_column_index":0,"answer_column_index":1}'

table_config description:

header_index_max: The number of header rows. A value of 0 indicates that the first row is the header.
question_column_index: The index of the question column, starting from 0.
answer_column_index: The index of the answer column.

FAQ retrieval (standalone call)

Retrieves FAQ results by question without initiating a chat conversation.

curl -X POST "$EAS_SERVICE_URL/v1/faq-retrieval" \
  -H "Authorization: Bearer $EAS_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "chatapp_id": "your_app_id",
    "query": "The user's input question"
  }'

The user_id and retrieval_setting (such as top_k and similarity_threshold) fields are optional. If you do not pass the retrieval_setting parameter, the default values from the application's FAQ configuration are used.

Preparations: Obtain the service endpoint and token

Chat API

Knowledge base management

Create a knowledge base

Request

Headers

Request Body

Response example

Get a list of knowledge bases

Request

Headers

URL query parameters

Response example

Get a specific knowledge base

Request

Headers

URL path parameters

Response example

Update a knowledge base

Request

Headers

URL path parameters

Request Body

Response example

Delete a specific knowledge base

Request

Headers

URL path parameters

Response example

File management

Upload files

Request

Headers

URL path parameters

Request Body parameters

Response example

List files

Request

Headers

URL path parameters

URL query parameters

Response example

Get file details

Request

Headers

URL path parameters

Response example

Reprocess a file

Request

Headers

URL path parameters

Response example

Delete a file

Request

Headers

URL path parameters

Response example

Data chunk management

View file chunks

Request

Headers

URL path parameters

URL query parameters

Response example

Update a single chunk

Request

Headers

URL path parameters

Request Body

Response example

Disable a chunk

Metadata management

Define metadata fields

Request

Headers

URL path parameters

Request Body

Response example

List metadata

Request