PAI-RAG service API (v0.4.x)-Platform For AI(PAI)-阿里云帮助中心

This document covers version v0.4.x of the PAI-RAG Service, providing API definitions, request examples, and core concepts to help developers quickly and efficiently integrate PAI-RAG capabilities into their applications.

Prerequisites: Get endpoint and token

To call the RAG service via its API, you need to obtain the service endpoint and a token. All API requests must include the EAS_TOKEN in the HTTP Authorization header.

The $EAS_SERVICE_URL and $EAS_TOKEN that appear in the API descriptions below are environment variables. You must set them before use. Follow these steps to obtain them:

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 your target service, and then in the Basic Information section, click View Endpoint Information.
On the Invocation Method page, get the Internet/VPC Endpoint (EAS_SERVICE_URL) and Token (EAS_TOKEN).
Important
- Remove the trailing slash (/) from the EAS_SERVICE_URL value.
- Use the internet endpoint if your client can access the public internet.
- Use the VPC endpoint only if your client is in the same Virtual Private Cloud (VPC) as the RAG service.

After obtaining your EAS_SERVICE_URL and EAS_TOKEN, set them as environment variables to simplify subsequent API calls:

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

Once set, you can use $EAS_SERVICE_URL and $EAS_TOKEN in subsequent curl commands.

Chat API

The Chat API is a streaming chat interface that supports agents and Retrieval-Augmented Generation (RAG). It extends the OpenAI-compatible chat protocol with advanced features such as knowledge base retrieval, multi-step reasoning, and tool calling, making it suitable for building intelligent conversational systems and question-answering bots.

Important

The recommended way to call the Chat API is to configure your own chat application. For example, you can create an application named my_assistant and configure its knowledge base and web search settings.

POST $EAS_SERVICE_URL/v1/chat/completions

Description: Sends a chat request. Use the model parameter to call a pre-configured chat application that may be linked to a knowledge base, web search, or other resources.

Request body (application/json)

Parameter	Type	Required	Description
`model`	String	Yes	The name of your chat application.
`messages`	Array	Yes	The conversation history, as a list of messages in the OpenAI format.
`stream`	Boolean	No	Specifies whether to return the response in streaming mode. Defaults to `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 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 your chat application name
    messages=[
        {"role": "user", "content": "Hello"}
    ],
    stream=True
)
for chunk in response:
    print(chunk.choices[0].delta.content)

Knowledge base management

Knowledge base

Create a new knowledge base and configure its settings 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 } }'
Request 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 the EAS_TOKEN.
Request body
name `string` (Required) The name of the knowledge base.
description `string` (Optional) A description of the knowledge base.
embedding_model `string` (Required) The name or path of the embedding model. Both 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 chunk, in characters. chunk_overlap `int` (Optional) The length of the overlap between adjacent chunks, in characters. image_caption_model `string` (Optional) The image captioning model.
retrieval_config `object` (Optional) The retrieval configuration. Properties retrieval_mode `string` (Optional) The retrieval mode. Valid values: `hybrid` (hybrid search) and `vector` (vector search). top_k `int` (Optional) The number of top-ranked chunks to return. similarity_threshold `float` (Optional) Filters out results with a similarity score below this value. enable_rerank `bool` (Optional) Specifies whether to rerank the retrieval results. Important To use this feature, you must first configure the reranker model in the PAI-RAG Web UI. rerank_model `string` (Optional) The name or path of the reranker model. vector_weight `float` (Optional) The weight of the vector search component used in a hybrid search.

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
        }
    }
}

List knowledge bases

Retrieves a paginated list of knowledge bases in the current service.

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_TOKE"`
Request headers
Authorization `string` (Required) The authentication token for the request. Use the EAS_TOKEN value.
Query parameters
page `int` (Optional) The page number to retrieve. The default value is `1`.
size `int` (Optional) The number of items per page. The default value is `10`, and the maximum value is `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 knowledge base

Retrieves the details of a 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. Use your `EAS_TOKEN`.
Path parameters
kb_id `string` (Required) The unique identifier of the knowledge base.

Response example

{
    "code": 200,
    "message": "Retrieved the knowledge base 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 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" } }'
Request headers
Content-Type `string` (Required) This parameter must be set to `application/json`.
Authorization `string` (Required) The authentication token. Use the EAS_TOKEN.
Path parameters
kb_id `string` (Required) The unique identifier of the knowledge base.
Request body
The request body accepts the same parameters as the operation for creating a knowledge base, 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 knowledge base

Permanently deletes the specified knowledge base and all its files and indexes. This is an irreversible operation. Proceed 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"`
Request headers
Authorization `string` (Required) The authentication token for the request. Use the EAS_TOKEN.
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 asynchronous API immediately returns file information. Parsing and indexing occur 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"'`
Request 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.
Path parameters
kb_id `string` (Required) The unique identifier of the knowledge base.
Request body
files `file` (Required) One or more files to upload.

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

Retrieves a paginated list of files from a specified knowledge base. You can filter the results by file name and processing status.

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"`
Request headers
Authorization `string` (required) Your authentication token. Use the value of $EAS_TOKEN.
Path parameters
kb_id `string` (required) The ID of the knowledge base.
Query parameters
query `string` (optional) A search keyword for a fuzzy match on file names.
status `string` (optional) Filters files by processing status. If omitted, the API returns files of all statuses. Valid values: `pending`, `succeeded`, `failed`, `persisting`, `parsing`.
page `int` (optional) The page number. The default is 1.
size `int` (optional) The number of results to return per page. The default is 10.

Response example

{
    "code": 200,
    "message": "Successfully retrieved the file list.",
    "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

Returns detailed information about a single file. Use this endpoint to poll for 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 authorization token. Use your `EAS_TOKEN`.
Path parameters
kb_id `string` (Required) The knowledge base ID.
file_id `string` (Required) The file ID.

Response example

{
    "code": 200,
    "message": "File query successful",
    "data": {
        "file_content_length": 0,
        "status": "succeeded",
        "file_source": null,
        "failed_reason": null,
        "file_name": "EAS_overview.pdf",
        "active": true,
        "tenant_id": "__default_tenant_id__",
        "file_path": "a4815ee728a64e9c83a3d891dbc1c956/docs/EAS_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_overview.pdf",
            "file_name": "EAS_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

Reprocesses a file, for example, one that failed to process or 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' \`
Header
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 the EAS_TOKEN.
Path parameter
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 file and its associated data chunks and indexes from the 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. Use your EAS_TOKEN.
Path parameters
kb_id `string` (Required) The unique identifier for the knowledge base.
file_id `string` (Required) The unique identifier for the file.

Response example

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

Data chunk management

List file chunks

Returns a paginated list of chunks from a specified file.

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"`
Request headers
Authorization `string` (required) A token used to authenticate the request. Use the EAS_TOKEN.
Path parameters
kb_id `string` (required) The knowledge base's unique identifier.
file_id `string` (required) The file's unique identifier.
Query parameters
page `int` (optional) The page number. The default value is 1.
size `int` (optional) The number of chunks per page. The default value is 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 chunk

Updates the content or status of a chunk. For example, you can manually correct poorly segmented text or disable a chunk to exclude it from retrieval.

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": "The updated text content of the chunk...", "active": true }'`
Request headers
Authorization `string` (Required) The authentication token for the request. Use EAS_TOKEN.
Content-Type `string` (Required) application/json
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 chunk.
Request body
text `string` (Optional) The updated text content for the chunk.
active `bool` (Optional) Indicates if the chunk is active. If false, the chunk is excluded from retrieval.

Response example

{
    "code": 200,
    "message": "Chunk update successful",
    "data": {
        "active": true,
        "text": "Updated 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"
    }
}

Exclude a chunk

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

Metadata management

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

Define metadata field

Defines a schema for a metadata field in a knowledge base, including its name, value type, and description.

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) Authentication token for the request.
Content-Type `string` (Required) application/json
Path parameters
kb_id `string` (Required) The knowledge base ID.
Request body
kb_id `string` (Required) The knowledge base ID.
name `string` (Required) Display name of the metadata field. Must be 3 to 50 characters long.
value_type `string` (Required) Value type of the field. Must be string, number, or datetime.
description `string` (Optional) Description of the metadata 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 specified 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) Authentication token for the request.
Path parameters
kb_id `string` (Required) The knowledge base ID.

Response example

{
    "code": 200,
    "message": "Metadata listed successfully.",
    "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 the 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) Authentication token for the request.
Path parameters
kb_id `string` (Required) The knowledge base ID.
metadata_id `string` (Required) The ID of the metadata field to delete.

Response example

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

Set file metadata

Sets the metadata for a specific file. Important: This operation replaces all existing metadata for the file. To update metadata without data loss, first retrieve the current values with a GET request, modify them, and then submit the complete set of values with this request.

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) Authentication token for the request.
Content-Type `string` (Required) application/json
Path parameters
kb_id `string` (Required) The knowledge base ID.
file_id `string` (Required) The file ID.
Request body
entries `array` (Required) An array of metadata entries to set on the file. Properties name `string` (Required) Name of a metadata field that is already defined for the knowledge base. value `string/number` (Required) The value to assign to the metadata field. The type of this value must match the value_type defined for the field.

Response example

{
    "code": 200,
    "message": "File metadata set successfully.",
    "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 hybrid retrieval on a specified knowledge base by combining text, vector, 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 the `EAS_TOKEN`.
Content-Type `string` (required) application/json
Request body
query `string` (required) The query text.
knowledge_id `string` (required) The ID of the knowledge base.
user_id `string` (optional) A unique identifier for the user, used for personalization or logging.
metadata_condition `object` (optional) Specifies the conditions for metadata filtering, including a `logical_operator` and a `conditions` array. Properties logical_operator `string` (optional) The logical operator for the conditions. Defaults to `and`. Valid values are `and` and `or`. conditions `array` (optional) An array of condition objects. Properties name `string` (required) The ID of the metadata field. value `string/number` (required) The comparison value. comparison_operator `string` (required) The comparison operator. Valid values `empty`: Checks if the field is null or an empty string. `not empty`: Checks if the field has a non-empty value. `contains`: Checks if the value parameter is a substring of the field's string value. `not contains`: Checks if the value parameter is not a substring of the field's string value. `start with`: Checks if the field's string value starts with the value parameter. `end with`: Checks if the field's string value ends with the value parameter. `=`: Equal to. Applies to number and datetime types. `≠`: Not equal to. Applies to number and datetime types. `≥`: Greater than or equal to. Applies to number and datetime types. `≤`: Less than or equal to. Applies to number and datetime types. `>`: Greater than. Applies to number and datetime types. `<`: Less than. Applies to number and datetime types.
retrieval_setting `object` (optional) Per-request settings that override the default configuration of the knowledge base. Properties top_k `int` (optional) The number of most relevant data chunks to return. score_threshold `float` (optional) The similarity score threshold. Only data chunks with a score at or above this threshold are returned.

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 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 }'`
Request 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. Set this to `aliyun-fc`, as only Alibaba Cloud Function Compute (FC) sandboxes are currently supported.
aliyun_id `string`(Required) Your Alibaba Cloud account ID.
interpreter_id `string`(Required) The code interpreter ID.
enabled `bool`(Required) Set to `true` to enable the sandbox, or `false` to disable it.

Get sandbox configuration

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

Configure FAQ

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

All requests require authorization (e.g., Authorization: Bearer YOUR_BEARER_TOKEN). Replace {EAS_SERVICE_URL} with the actual service URL.

Enable and configure FAQ

Use the Update application API to enable FAQ and apply the configuration.

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 authorization token for the request. Use your `EAS_TOKEN`.
Path parameters
id `string` (Required) The unique ID of the application. Obtain this ID using the Query application API.
Request body
app_id `string` (Required) The application ID.
description `string` (Optional) The application description.
model_id `string` (Required) The ID of the base model.
kb_ids `array` (Optional) An array of knowledge base IDs associated with the application.
enable_faq `bool` (Optional) Enables or disables the FAQ feature.
faq_config `object` (Optional) The FAQ configuration. Properties active `bool` (Optional) Activates or deactivates this FAQ configuration. similarity_threshold `float` (Optional) The similarity threshold. A value between 0.8 and 1.0 is recommended. embedding_model `string` (Optional) The embedding model ID. enable_question_in_retrieval `bool` (Optional) Whether to include the question in the retrieval process. enable_question_in_response `bool` (Optional) Whether to include the question in the response. enable_answer_in_retrieval `bool` (Optional) Whether to include the answer in the retrieval process. enable_answer_in_response `bool` (Optional) Whether to include the answer in the response. return_direct `bool` (Optional) Whether to return the tool output directly, without LLM processing.

Query application

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

The app_id is obtained as follows. On the application configuration page in the console, select the Chat Application tab, find the application ID value (such as chatbot) in the required App ID field, and use it as the value for the app_id parameter in the request.

Create an 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": "On the sign-in page, click '\''Forgot Password'\'' and follow the prompts.",
    "active": true
  }'

List FAQs

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

Update an 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 signing in, go to Account Settings > Security to change your password.",
    "active": true
  }'

Delete an FAQ

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

Bulk upload FAQ files

This request uses multipart/form-data. Upload one or more files using the files field. You can optionally provide a table_config JSON string to map header and column indexes. Supported file types are .xlsx and .xls.

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}'

The table_config parameter:

header_index_max: The zero-based index of the last header row. For a single header row, set this to 0.
question_column_index: The zero-based index of the question column.
answer_column_index: The zero-based index of the answer column.

FAQ retrieval (standalone)

Retrieves FAQ results for a query directly without initiating a 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": "User'\''s input query"
  }'

Optional request fields: user_id and retrieval_setting (e.g., top_k, similarity_threshold). If retrieval_setting is omitted, the application's default FAQ configuration is used.

Prerequisites: Get endpoint and token

Chat API

Knowledge base management

Knowledge base

Request

Request headers

Request body

Response example

List knowledge bases

Request

Request headers

Query parameters

Response example

Get a knowledge base

Request

Headers

Path parameters

Response example

Update knowledge base

Request

Request headers

Path parameters

Request body

Response example

Delete a knowledge base

Request

Request headers

Path parameters

Response example

File management

Upload files

Request

Request headers

Path parameters

Request body

Response example

List files

Request

Request headers

Path parameters

Query parameters

Response example

Get file details

Request

Headers

Path parameters

Response example

Reprocess a file

Request

Header

Path parameter

Response example

Delete a file

Request

Headers

Path parameters

Response example

Data chunk management

List file chunks

Request

Request headers

Path parameters

Query parameters

Response example

Update a chunk

Request

Request headers

Path parameters

Request body

Response example

Exclude a chunk

Metadata management

Define metadata field

Request

Headers

Path parameters

Request body

Response example

List metadata

Request