RAG Agent data plane API reference-ApsaraDB RDS(RDS)-阿里云帮助中心

The RAG Agent data plane API handles business requests and data operations on your RDS Supabase instance — managing datasets, uploading documents, querying knowledge bases, and searching the knowledge graph.

Control plane vs. data plane

The RAG Agent API is split into two planes:

Plane	Purpose	Call frequency
Control plane	Manages resource lifecycle: creating, modifying, viewing, and deleting instances	Low
Data plane	Handles business requests: datasets, documents, queries, search, and graph operations	High

This reference covers the data plane API only.

Authentication

All data plane API requests require authentication. Two methods are available.

Authenticate with a ServiceKey

Use this method for administrative access. A ServiceKey grants full access to all datasets.

On the RDS Supabase instance details page, click Get API key in the upper-right corner and copy the ServiceKey.
On the same page, go to Basic Information > Network Information and copy the Public Endpoint.

Pass the ServiceKey in the apikey header:

curl -X GET "http://<public_endpoint>/rag/v1/datasets" \
  -H "apikey: <Supabase_ServiceKey>" \
  -H "Content-Type: application/json"

Authenticate with an AnonKey and access token

Use this method to authenticate as a specific Supabase auth user. Requests can only access datasets that the authenticated user has permission to view or modify.

On the RDS Supabase instance details page, click Get API key in the upper-right corner and copy the AnonKey.
On the same page, go to Basic Information > Network Information and copy the Public Endpoint.

Call the login API to get an access token. The access token is returned in the response body.

curl -X POST "http://<public_endpoint>/login" \
  -H "apikey: <AnonKey>" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "username=<auth_user_email>&password=<auth_user_password>"

Pass both the AnonKey and access token in subsequent requests:

curl -X POST "http://<public_endpoint>/rag/v1/datasets" \
  -H "apikey: <AnonKey>" \
  -H "Authorization: Bearer <RAG_Agent_access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "xxxx",
    "description": "xxxx",
    "rag_type": "rag",
    "storage_type": "local",
    "visibility": "private"
  }'

API

Dataset management

Create a dataset

POST /rag/v1/datasets

Creates a dataset and initializes the corresponding PostgreSQL schema for data isolation.

Request parameters

Parameter	Type	Required	Description
`name`	string	Yes	The name of the dataset. Must be unique. Length: 1–255 characters.
`description`	string	No	The description of the dataset. Maximum length: 2,000 characters. Default: null.
`rag_type`	string	No	The RAG type. Currently, only GraphRAG is supported (default).
`workspace`	string	No	The workspace identifier. Default: null.
`namespace_prefix`	string	No	The namespace prefix. Default: null.
`storage_type`	string	No	The storage class. Valid values: `local`, `supabase` (default), `aliyun-oss`. When set to `supabase` or `aliyun-oss`, you must also provide the `args` parameter.
`chunk_engine`	string	No	The chunking engine type. Default: `default`.
`schedule`	string	No	The scheduling configuration. Default: empty.
`args`	object	No	The storage configuration in JSON format. Required when `storage_type` is `supabase` or `aliyun-oss`. See Storage configuration.
`created_by`	string	No	The creator identifier. Default: null.
`owner_id`	string	No	The owner identifier. Default: null.
`visibility`	string	No	The dataset visibility. Valid values: `private` (default), `public`.
`default_permission`	string	No	The default permission level. Default: null.
`user_id`	string	No	The `user_id` from the Supabase Auth table. Used to control dataset permissions. Default: null.

Storage configuration

When storage_type is supabase:

"args": {
  "supabase_url": "http://your-project.supabase.co",
  "supabase_api_key": "your-supabase-api-key",
  "supabase_bucket_name": "your-bucket-name",
  "path": "test"
}

When storage_type is aliyun-oss:

"args": {
  "oss_endpoint": "http://oss-cn-hangzhou.aliyuncs.com",
  "oss_access_key_id": "LTAI5tF****",
  "oss_access_key_secret": "your-secret-key-here",
  "oss_bucket_name": "my-lightrag-bucket",
  "oss_region": "oss-cn-hangzhou",
  "oss_path": "datasets/production/"
}

Sample response

{
  "dataset": {
    "dataset_uuid": "uuid-string",
    "name": "My Dataset",
    "description": "Dataset description",
    "status": "active",
    "created_at": "2024-01-01T00:00:00Z"
  }
}

List datasets

GET /rag/v1/datasets

Returns a list of datasets. Supports optional filtering and pagination.

Request parameters

Parameter	Type	Required	Description
`owner_id`	string	No	Filter by owner ID. Default: null.
`status`	string	No	Filter by status. Default: null.
`visibility`	string	No	Filter by visibility. Default: null.
`page`	integer	No	The page number. Minimum: 1. Default: 1.
`page_size`	integer	No	The number of results per page. Valid values: 1–100. Default: 20.

Get a dataset

GET /rag/v1/datasets/{dataset_id}

Returns information about a specific dataset.

Path parameters

Parameter	Type	Required	Description
`dataset_id`	string	Yes	The UUID of the dataset.

Update a dataset

PUT /rag/v1/datasets/{dataset_id}

Updates dataset metadata.

Path parameters

Parameter	Type	Required	Description
`dataset_id`	string	Yes	The UUID of the dataset.

Request parameters

Parameter	Type	Required	Description
`description`	string	No	The description of the dataset. Maximum length: 2,000 characters. Default: null.
`rag_type`	string	No	The RAG type. Currently, only GraphRAG is supported (default).
`workspace`	string	No	The workspace identifier. Default: null.
`namespace_prefix`	string	No	The namespace prefix. Default: null.
`storage_type`	string	No	The storage class. Valid values: `local` (default), `supabase`, `aliyun-oss`. When set to `supabase` or `aliyun-oss`, you must also provide the `args` parameter.
`chunk_engine`	string	No	The chunking engine type. Default: `default`.
`schedule`	string	No	The scheduling configuration. Default: empty.
`args`	object	No	The storage configuration in JSON format. Required when `storage_type` is `supabase` or `aliyun-oss`. See Storage configuration.
`created_by`	string	No	The creator identifier. Default: null.
`owner_id`	string	No	The owner identifier. Default: null.
`visibility`	string	No	The dataset visibility. Valid values: `private` (default), `public`.
`default_permission`	string	No	The default permission level. Default: null.
`user_id`	string	No	The `user_id` from the Supabase Auth table. Used to control dataset permissions. Default: null.

Delete a dataset

DELETE /rag/v1/datasets/{dataset_id}

Permanently deletes a dataset and all associated data. This operation cannot be undone.

Path parameters

Parameter	Type	Required	Description
`dataset_id`	string	Yes	The UUID of the dataset.

Document management

Upload a document

POST /rag/v1/datasets/{dataset_id}/documents/upload

Uploads a document to a dataset. Supports local file uploads and remote file references from Supabase, Alibaba Cloud OSS, or any S3-compatible object storage.

Document processing is asynchronous. After upload, use the returned track_id with Get document processing status to poll until the status reaches processed or failed.

Path parameters

Parameter	Type	Required	Description
`dataset_id`	string	Yes	The UUID of the dataset.

Request parameters

For local file uploads, provide the file parameter.

For remote file uploads, provide remote_file_path, remote_storage_type, and remote_storage_config.

Parameter	Type	Required	Description
`file`	binary	No	The file to upload. Default: null.
`remote_file_path`	string	No	The path to the remote file. Default: null.
`remote_storage_type`	string	No	The remote storage type. Default: null.
`remote_storage_config`	string	No	The remote storage configuration as a JSON string. Default: null.
`original_filename`	string	No	The original filename. Default: null.
`multimodal_config`	string	No	The multimodal processing configuration as a JSON string. Default: null.
`api_key_header_value`	string	No	An API key. Default: null.

Remote storage configuration examples

Supabase:

{
  "SUPABASE_URL": "http://your-project.supabase.co",
  "SUPABASE_API_KEY": "your_service_key",
  "SUPABASE_BUCKET_NAME": "multimodal_files"
}

Alibaba Cloud OSS:

{
  "ALIYUN_OSS_ACCESS_KEY": "your_access_key_id",
  "ALIYUN_OSS_SECRET_KEY": "your_access_key_secret",
  "ALIYUN_OSS_ENDPOINT": "oss-cn-beijing.aliyuncs.com",
  "ALIYUN_OSS_BUCKET_NAME": "your_bucket_name",
  "ALIYUN_OSS_REGION": "oss-cn-beijing"
}

Supported file formats

PDF, Word (.doc, .docx), plain text (.txt), Markdown (.md), and HTML (.html). The supported formats may vary by configuration and version.

Insert text

POST /rag/v1/datasets/{dataset_id}/documents/text

Inserts text content directly into a dataset without uploading a file.

Path parameters

Parameter	Type	Required	Description
`dataset_id`	string	Yes	The UUID of the dataset.

Request parameters

Parameter	Type	Required	Description
`text`	string	Yes	The text to insert. Must contain at least one character.
`file_source`	string	No	The source identifier for this text. Default: `text_input`.
`api_key_header_value`	string	No	An API key. Default: null.

Get document processing status

GET /rag/v1/datasets/{dataset_id}/track_status/{track_id}

Returns the processing status of a document by its tracking ID. Poll this endpoint after uploading a document until the status reaches processed or failed.

Status	Description
`pending`	Waiting to be processed.
`processing`	Processing in progress.
`processed`	Processing complete.
`failed`	Processing failed.
`multimodal_parsing`	Parsing multimodal content.
`multimodal_processing`	Processing multimodal content.

Path parameters

Parameter	Type	Required	Description
`dataset_id`	string	Yes	The UUID of the dataset.
`track_id`	string	Yes	The tracking ID returned by the upload request.

List documents

GET /rag/v1/datasets/{dataset_id}/documents

Returns the list of documents in a dataset.

Path parameters

Parameter	Type	Required	Description
`dataset_id`	string	Yes	The UUID of the dataset.

Request parameters

Parameter	Type	Required	Description
`limit`	integer	No	The maximum number of documents to return. Valid values: 1–1,000. Default: 100.
`offset`	integer	No	The number of documents to skip. Minimum: 0. Default: 0.

List documents with pagination

POST /rag/v1/datasets/{dataset_id}/documents/paginated

Returns documents with support for filtering, sorting, and pagination.

Path parameters

Parameter	Type	Required	Description
`dataset_id`	string	Yes	The UUID of the dataset.

Request parameters

Parameter	Type	Required	Description
`status_filter`	string	No	Filter by document status. Valid values: `pending`, `processing`, `processed`, `failed`. Default: null (all statuses).
`page`	integer	No	The page number. Minimum: 1. Default: 1.
`page_size`	integer	No	The number of documents per page. Valid values: 10–200. Default: 50.
`sort_field`	string	No	The field to sort by. Valid values: `created_at`, `updated_at` (default), `id`, `file_path`.
`sort_direction`	string	No	The sort direction. Valid values: `asc`, `desc` (default).

Delete documents

DELETE /rag/v1/datasets/{dataset_id}/documents/delete_document

Deletes specific documents from a dataset.

Path parameters

Parameter	Type	Required	Description
`dataset_id`	string	Yes	The UUID of the dataset.

Request parameters

Parameter	Type	Required	Description
`doc_ids`	array	Yes	The list of document IDs to delete.
`delete_file`	boolean	No	Specifies whether to also delete the corresponding file from the upload folder. Valid values: `true`, `false` (default).

Clear all documents

DELETE /rag/v1/datasets/{dataset_id}/documents

Deletes all documents from a dataset.

Path parameters

Parameter	Type	Required	Description
`dataset_id`	string	Yes	The UUID of the dataset.

Get document statistics

GET /rag/v1/datasets/{dataset_id}/documents/statistics

Returns statistics for documents in a dataset.

Path parameters

Parameter	Type	Required	Description
`dataset_id`	string	Yes	The UUID of the dataset.

Query features

All query endpoints share a common set of parameters for controlling retrieval behavior.

Query modes

Mode	Description	Best for
`local`	Retrieves based on local context	Specific questions requiring precise answers
`global`	Queries the global knowledge graph	General or conceptual questions requiring deep understanding
`hybrid`	Combines local and global knowledge	Balancing accuracy and coverage
`naive`	Vector retrieval only	—
`mix` (default)	Combines vector and graph search	General use (equivalent to `naive` + `hybrid`)
`bypass`	Skips RAG and queries the large language model (LLM) directly	—

Query a dataset

POST /rag/v1/datasets/{dataset_id}/query

Runs a query against a specific dataset and returns a generated response.

Path parameters

Parameter	Type	Required	Description
`dataset_id`	string	Yes	The UUID of the dataset.

Request parameters

Parameter	Type	Required	Description
`query`	string	Yes	The query text. Must contain at least one character.
`mode`	string	No	The query mode. See Query modes. Default: `mix`.
`only_need_context`	boolean	No	Specifies whether to return only the retrieved context without generating a response. Default: null.
`only_need_prompt`	boolean	No	Specifies whether to return only the prompt without generating a response. Default: null.
`response_type`	string	No	The response format type. Default: null.
`top_k`	integer	No	The number of results to return. Valid values: 1–100. Default: null.
`chunk_top_k`	integer	No	The number of chunks to return. Valid values: 1–100. Default: null.
`max_entity_tokens`	integer	No	The token budget for entity context. Minimum: 1. Default: null.
`max_relation_tokens`	integer	No	The token budget for relation context. Minimum: 1. Default: null.
`max_total_tokens`	integer	No	The total token budget. Minimum: 1. Default: null.
`conversation_history`	array	No	The previous conversation turns. Default: null.
`history_turns`	integer	No	The number of conversation rounds to include. Minimum: 0. Default: null.
`ids`	array	No	Filter results to specific document IDs. Default: null.
`user_prompt`	string	No	A custom user prompt. Default: null.
`enable_rerank`	boolean	No	Specifies whether to enable reranking of results. Default: null.

Streaming query

POST /rag/v1/datasets/{dataset_id}/query/stream

Runs a query and streams the response in real time. Accepts the same parameters as Query a dataset.

Path parameters

Parameter	Type	Required	Description
`dataset_id`	string	Yes	The UUID of the dataset.

Request parameters

Same as Query a dataset.

Cross-dataset query

POST /rag/v1/datasets/cross-query

Queries multiple datasets simultaneously, merges the results, and applies cross-dataset reranking. Supports up to 10 datasets per request.

Request parameters

Parameter	Type	Required	Description
`query`	string	Yes	The query text. Must contain at least one character.
`dataset_ids`	array	Yes	The list of dataset IDs to query. Valid values: 1–10 datasets.
`document_filters`	object	No	Per-dataset document ID filters. Format: `{dataset_id: [doc_id1, doc_id2]}`. Default: null.
`mode`	string	No	The query mode. See Query modes. Default: `mix`.
`only_need_context`	boolean	No	Specifies whether to return only the retrieved context without generating a response. Default: null.
`only_need_prompt`	boolean	No	Specifies whether to return only the prompt without generating a response. Default: null.
`response_type`	string	No	The response format type. Default: null.
`top_k`	integer	No	The number of results to return. Valid values: 1–100. Default: null.
`chunk_top_k`	integer	No	The number of chunks to return. Valid values: 1–100. Default: null.
`max_entity_tokens`	integer	No	The token budget for entity context. Minimum: 1. Default: null.
`max_relation_tokens`	integer	No	The token budget for relation context. Minimum: 1. Default: null.
`max_total_tokens`	integer	No	The total token budget. Minimum: 1. Default: null.
`conversation_history`	array	No	The previous conversation turns. Default: null.
`history_turns`	integer	No	The number of conversation rounds to include. Minimum: 0. Default: null.
`user_prompt`	string	No	A custom user prompt. Default: null.
`enable_rerank`	boolean	No	Specifies whether to enable reranking of results. Default: true.
`max_results_per_dataset`	integer	No	The maximum number of results from each dataset before merging. Valid values: 1–100. Default: 20.

Cross-dataset contextual query

POST /rag/v1/datasets/cross-query/context

Retrieves context from multiple datasets without generating a final response. Accepts the same parameters as Cross-dataset query.

Cross-dataset streaming query

POST /rag/v1/datasets/cross-query/stream

Queries multiple datasets and streams the response in real time. Accepts the same parameters as Cross-dataset query.

Search features

Search a dataset

POST /rag/v1/datasets/{dataset_id}/search

Searches for entities, relations, or chunks within a specific dataset.

Path parameters

Parameter	Type	Required	Description
`dataset_id`	string	Yes	The UUID of the dataset.

Request parameters

Parameter	Type	Required	Description
`query`	string	Yes	The search query. Must contain at least one character.
`search_type`	string	No	The type of content to search for. Valid values: `entities`, `relationships`, `chunks`, `all` (default).
`top_k`	integer	No	The number of results to return. Valid values: 1–100. Default: 10.

Graph features

Get graph statistics

GET /rag/v1/datasets/{dataset_id}/graphs/statistics

Returns statistics for the knowledge graph of a dataset.

Path parameters

Parameter	Type	Required	Description
`dataset_id`	string	Yes	The UUID of the dataset.

Get graph labels

GET /rag/v1/datasets/{dataset_id}/graphs/labels

Returns the available node labels in the knowledge graph of a dataset.

Path parameters

Parameter	Type	Required	Description
`dataset_id`	string	Yes	The UUID of the dataset.

Query graph data

GET /rag/v1/datasets/{dataset_id}/graphs

Returns nodes and edges from the knowledge graph of a dataset.

Path parameters

Parameter	Type	Required	Description
`dataset_id`	string	Yes	The UUID of the dataset.

Request parameters

Parameter	Type	Required	Description
`label`	string	No	The graph label to query. Default: `*` (all labels).
`max_depth`	integer	No	The maximum traversal depth. Valid values: 1–10. Default: 2.
`max_nodes`	integer	No	The maximum number of nodes to return. Valid values: 1–1,000. Default: 100.

Get dataset health status

GET /rag/v1/datasets/{dataset_id}/health

Returns the health status of a dataset, including data availability, graph connectivity, and recommendations.

Path parameters

Parameter	Type	Required	Description
`dataset_id`	string	Yes	The UUID of the dataset.

Cache management

Clear dataset cache

POST /rag/v1/datasets/{dataset_id}/clear_cache

Clears the LLM response cache for a dataset.

Path parameters

Parameter	Type	Required	Description
`dataset_id`	string	Yes	The UUID of the dataset.

Pipeline management

Get pipeline status

GET /rag/v1/datasets/{dataset_id}/pipeline/status

Returns the pipeline processing status for a dataset.

Path parameters

Parameter	Type	Required	Description
`dataset_id`	string	Yes	The UUID of the dataset.

Clear pipeline cache

POST /rag/v1/datasets/{dataset_id}/pipeline/clear_cache

Clears the pipeline cache for a dataset.

Path parameters

Parameter	Type	Required	Description
`dataset_id`	string	Yes	The UUID of the dataset.

Get pipeline overview

GET /pipeline/status/overview

Returns the pipeline status for all datasets and the global pipeline.

System features

Get authentication status

GET /auth-status

Returns the current authentication status. If authentication is not configured, a guest token is returned.

Log on

POST /login

Authenticates a user and returns an access token.

Request parameters

Parameter	Type	Required	Description
`username`	string	Yes	The username (email address).
`password`	string	Yes	The password.
`grant_type`	string	No	The grant type. Default: null.
`scope`	string	No	The scope. Default: `""`.
`client_id`	string	No	The client ID. Default: null.
`client_secret`	string	No	The client secret. Default: null.

Health check

GET /health

Returns the current system status.

Request parameters

Parameter	Type	Required	Description
`api_key_header_value`	string	No	An API key. Default: null.

Response schemas

Dataset (DatasetInfo)

{
  "dataset_uuid": "string",
  "name": "string",
  "description": "string",
  "rag_type": "string",
  "workspace": "string",
  "namespace_prefix": "string",
  "created_at": "2024-01-01T00:00:00Z",
  "updated_at": "2024-01-01T00:00:00Z",
  "status": "string",
  "storage_type": "string",
  "chunk_engine": "string",
  "schedule": "string",
  "args": {},
  "created_by": "string",
  "owner_id": "string",
  "visibility": "string",
  "default_permission": "string"
}

Document (DocStatusResponse)

{
  "id": "doc_123456",
  "content_summary": "Research paper on machine learning",
  "content_length": 15240,
  "status": "processed",
  "created_at": "2025-03-31T12:34:56",
  "updated_at": "2025-03-31T12:35:30",
  "track_id": "upload_20250729_170612_abc123",
  "chunks_count": 12,
  "error_msg": null,
  "metadata": {
    "author": "John Doe",
    "year": 2025
  },
  "file_path": "research_paper.pdf"
}

Pagination (PaginationInfo)

{
  "page": 1,
  "page_size": 50,
  "total_count": 150,
  "total_pages": 3,
  "has_next": true,
  "has_prev": false
}

Error response

All errors follow this structure:

{
  "error": "Error type",
  "message": "Detailed error description",
  "dataset_id": "ID of the related dataset (optional)"
}

HTTP status codes

Status code	Meaning	Common causes
200	Success	Request processed successfully.
400	Bad request	Invalid parameters or configuration.
401	Unauthorized	Missing or invalid authentication credentials.
404	Not found	The dataset or document does not exist.
422	Authentication fault	Request parameter validation failed.
500	Server error	An internal server error occurred.

Examples

Create a dataset and upload a document

Create a dataset:

curl -X POST "http://api.example.com/rag/v1/datasets?apikey=<api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Knowledge Base",
    "description": "Company documents and policies",
    "visibility": "private"
  }'

Upload a local file. Note the track_id in the response — use it to check processing status.

curl -X POST "http://api.example.com/rag/v1/datasets/{dataset_id}/documents/upload?apikey=<api_key>" \
  -F "file=@document.pdf"

Poll for processing status until status is processed or failed:

curl -X GET "http://api.example.com/rag/v1/datasets/{dataset_id}/track_status/{track_id}?apikey=<api_key>"

Insert additional text content directly:

curl -X POST "http://api.example.com/rag/v1/datasets/{dataset_id}/documents/text?apikey=<api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "This is important company information...",
    "file_source": "manual_input"
  }'

Query a dataset

Single-dataset query:

curl -X POST "http://api.example.com/rag/v1/datasets/{dataset_id}/query?apikey=<api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "What is our company policy on remote work?",
    "mode": "hybrid",
    "top_k": 5
  }'

Cross-dataset query:

curl -X POST "http://api.example.com/rag/v1/datasets/cross-query?apikey=<api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "Compare policies across departments",
    "dataset_ids": ["dataset1", "dataset2", "dataset3"],
    "enable_rerank": true,
    "max_results_per_dataset": 10
  }'

Search and statistics

Search for entities:

curl -X POST "http://api.example.com/rag/v1/datasets/{dataset_id}/search?apikey=<api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "remote work policy",
    "search_type": "entities",
    "top_k": 10
  }'

Get document statistics:

curl -X GET "http://api.example.com/rag/v1/datasets/{dataset_id}/documents/statistics?apikey=<api_key>"

Get graph statistics:

curl -X GET "http://api.example.com/rag/v1/datasets/{dataset_id}/graphs/statistics?apikey=<api_key>"

Upload from remote storage

From Supabase:

curl -X POST "http://api.example.com/rag/v1/datasets/{dataset_id}/documents/upload?apikey=<api_key>" \
  -F "remote_file_path=folder1/folder2/document.pdf" \
  -F "remote_storage_type=supabase" \
  -F 'remote_storage_config={"url":"http://xxx.supabase.co","key":"xxx","bucket":"bucket"}' \
  -F "original_filename=document.pdf"

From Alibaba Cloud OSS:

curl -X POST "http://api.example.com/rag/v1/datasets/{dataset_id}/documents/upload?apikey=<api_key>" \
  -F "remote_file_path=folder1/folder2/document.pdf" \
  -F "remote_storage_type=aliyun-oss" \
  -F 'remote_storage_config={"access_key_id":"xxx","access_key_secret":"xxx","bucket":"bucket","endpoint":"oss-region.aliyuncs.com"}' \
  -F "original_filename=document.pdf"

Replace folder1/folder2/document.pdf with the actual relative path to your file in the storage service.