Collections
Group uploaded files into provider-backed knowledge bases for retrieval (RAG).
A collection groups files into a provider-backed knowledge base that supports
retrieval-augmented generation (RAG). Collections are delegated to providers that natively offer
this feature; the provider defaults to xai.
Collections are a thin pass-through to the upstream provider's knowledge-base API. The exact shape of a collection object (its id, file membership, status, etc.) is defined by that provider — query the provider's documentation for the fields it returns. Yunxin returns the provider's response verbatim. Only providers that implement collections support these endpoints.
Create a collection
POST /v1/collectionsParameters
| Parameter | Type | Required | Description |
|---|---|---|---|
name | string | Yes | A name for the collection. |
description | string | No | An optional description. |
provider | string | No | Provider that backs the collection. Defaults to xai. |
import os
import requests
resp = requests.post(
"https://api.yuhuanstudio.com/v1/collections",
headers={"Authorization": f"Bearer {os.environ['YUNXIN_API_KEY']}"},
json={
"name": "Product docs",
"description": "Knowledge base for support answers",
"provider": "xai",
},
)
collection = resp.json()
print(collection)The response is the provider's collection object.
If the chosen provider isn't available or doesn't support collections, the request returns 400
(for example, Provider 'xai' is not available or disabled. or
Provider xai does not support Collections.).
List collections
GET /v1/collectionsSupports a provider query parameter (defaults to xai). Returns a list under data:
{
"data": [ /* provider collection objects */ ]
}curl "https://api.yuhuanstudio.com/v1/collections?provider=xai" \
-H "Authorization: Bearer $YUNXIN_API_KEY"If the provider is unavailable or doesn't expose listing, an empty list ({"data": []}) is returned.
Add files to a collection
POST /v1/collections/{collection_id}/filesAttach previously uploaded files to a collection so the provider can index them for retrieval.
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
file_ids | string[] | Yes | Ids of files to add to the collection. |
provider | string | No | Provider that backs the collection (query parameter). Defaults to xai. |
import os
import requests
resp = requests.post(
"https://api.yuhuanstudio.com/v1/collections/col_123/files",
headers={"Authorization": f"Bearer {os.environ['YUNXIN_API_KEY']}"},
params={"provider": "xai"},
json={"file_ids": ["file-abc123", "file-def456"]},
)
print(resp.json())Upload files first with the File API, then reference their ids here. The provider indexes the file contents for retrieval.
Delete a collection
DELETE /v1/collections/{collection_id}Supports a provider query parameter (defaults to xai). Returns 204 No Content on success.
curl -X DELETE "https://api.yuhuanstudio.com/v1/collections/col_123?provider=xai" \
-H "Authorization: Bearer $YUNXIN_API_KEY"Authentication
Collections accept either an API key (Authorization: Bearer sk-... or X-API-Key) or a dashboard
session. See Authentication.
Related topics
- File Management — upload the files you add to a collection
- Models API — discover which providers and capabilities are available
How is this guide?