# Collections (/docs/collections)


A **collection** groups [files](/docs/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`.

<Callout type="info">
  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.
</Callout>

## Create a collection [#create-a-collection]

```
POST /v1/collections
```

### Parameters [#parameters]

| 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`. |

```python
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.

<Callout type="warn">
  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.`).
</Callout>

## List collections [#list-collections]

```
GET /v1/collections
```

Supports a `provider` query parameter (defaults to `xai`). Returns a list under `data`:

```json
{
  "data": [ /* provider collection objects */ ]
}
```

```bash
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 [#add-files-to-a-collection]

```
POST /v1/collections/{collection_id}/files
```

Attach previously uploaded [files](/docs/files) to a collection so the provider can index them for
retrieval.

### Parameters [#parameters-1]

| 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`. |

```python
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())
```

<Callout type="info">
  Upload files first with the [File API](/docs/files), then reference their ids here. The provider
  indexes the file contents for retrieval.
</Callout>

## Delete a collection [#delete-a-collection]

```
DELETE /v1/collections/{collection_id}
```

Supports a `provider` query parameter (defaults to `xai`). Returns `204 No Content` on success.

```bash
curl -X DELETE "https://api.yuhuanstudio.com/v1/collections/col_123?provider=xai" \
  -H "Authorization: Bearer $YUNXIN_API_KEY"
```

## Authentication [#authentication]

Collections accept either an API key (`Authorization: Bearer sk-...` or `X-API-Key`) or a dashboard
session. See [Authentication](/docs/authentication).

## Related topics [#related-topics]

* [File Management](/docs/files) — upload the files you add to a collection
* [Models API](/docs/models-api) — discover which providers and capabilities are available