> For the complete documentation index, see [llms.txt](https://academy.shade.inc/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://academy.shade.inc/developers/using-the-api/collections-and-share-links.md).

# Collections and share links

Group assets into collections and share files, folders, and collections with people outside your workspace using share links.

Collections group assets from anywhere in a drive without moving them. Share links let people outside your workspace view, comment on, or download files and folders. This guide covers both through the API.

## Prerequisites

* A Shade API key, stored in the `SHADE_KEY` environment variable
* A drive ID. See [Finding your IDs](/developers/get-started/integrating-with-shade.md)
* To create share links, the **Share** permission on the files you're sharing

## Base information

* **Base URL**: `https://api.shade.inc`
* **Authentication**: your API key in the `Authorization` header, with no `Bearer` prefix
* **Paths** start with the drive ID, for example `/YOUR_DRIVE_ID/Fall Campaign/Deliverables`

## 1. Create a collection

```bash
curl -X POST "https://api.shade.inc/collections" \
  -H "Authorization: $SHADE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "drive_id": "YOUR_DRIVE_ID",
    "name": "Fall Campaign selects",
    "description": "Best takes for the edit"
  }'
```

The response is the new collection's ID as a JSON string:

```json
"5e4d3c2b-1a09-4f8e-b7d6-c5b4a3928170"
```

List a drive's collections with `GET /collections?drive_id=YOUR_DRIVE_ID`.

## 2. Add assets

Add assets by ID, or add every asset under a folder:

```bash
curl -X POST "https://api.shade.inc/collections/COLLECTION_ID/assets" \
  -H "Authorization: $SHADE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "asset_ids": ["c2d9e8f1-3b4a-4c5d-8e6f-7a8b9c0d1e2f"],
    "directory_paths": ["/YOUR_DRIVE_ID/Fall Campaign/Interviews"]
  }'
```

Remove assets with `DELETE /collections/{collection_id}/assets` and a body of `{"asset_ids": [...]}`. The files themselves stay where they are.

## 3. List what's in a collection

Search with `collection_id` to page through a collection's assets. This also lets you filter and sort within it:

```bash
curl -X POST "https://api.shade.inc/search" \
  -H "Authorization: $SHADE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "drive_id": "YOUR_DRIVE_ID",
    "collection_id": "COLLECTION_ID",
    "filters": [{ "id": "type", "clause": "is", "options": ["VIDEO"] }]
  }'
```

See [Searching and filtering assets](/developers/using-the-api/searching-and-filtering-assets.md) for every filter and how to page through results.

## 4. Create a share link

Share links point at a file or folder. Pick what viewers can do with `allowed_actions`:

| Action     | Viewers can             |
| ---------- | ----------------------- |
| `read`     | View files and previews |
| `comment`  | Leave comments          |
| `download` | Download files          |

```bash
curl -X POST "https://api.shade.inc/workspaces/drives/YOUR_DRIVE_ID/public-file-shares" \
  -H "Authorization: $SHADE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "path": "/YOUR_DRIVE_ID/Fall Campaign/Rough Cuts",
    "name": "Fall Campaign rough cuts",
    "is_public_enabled": true,
    "allowed_actions": ["read", "comment"],
    "expiration_date": "2026-10-31T23:59:59Z"
  }'
```

Optional settings:

| Field             | Description                                           |
| ----------------- | ----------------------------------------------------- |
| `password`        | Viewers must enter this password                      |
| `expiration_date` | The link stops working after this time, in ISO 8601   |
| `max_view_count`  | The link stops working after this many unique viewers |

The response includes the share link's `id`. Send viewers to:

```
https://app.shade.inc/publish/SHARE_ID
```

## 5. Manage share links

| Task                            | Request                                                              |
| ------------------------------- | -------------------------------------------------------------------- |
| List links for a file or folder | `GET /workspaces/drives/{drive_id}/public-file-shares?path=...`      |
| List every link in a drive      | `GET /workspaces/drives/{drive_id}/drive-shared-links`               |
| Change a link                   | `PUT /workspaces/drives/{drive_id}/public-file-shares/{share_id}`    |
| Delete a link                   | `DELETE /workspaces/drives/{drive_id}/public-file-shares/{share_id}` |

`PUT` takes the same fields as creating a link, and `is_public_enabled` and `allowed_actions` are required. Set `is_public_enabled` to `false` to turn a link off without deleting it. To remove a password, send `"removed_password": true`.

Each link reports `is_expired` and `is_view_limit_reached`, so you can find links that have stopped working.

## 6. Share a collection

Collections are shared through their own settings rather than a separate share link. Update the collection with `is_public_enabled`, `allowed_actions`, and optionally `password` and `expiration_date`:

```bash
curl -X PUT "https://api.shade.inc/collections/COLLECTION_ID" \
  -H "Authorization: $SHADE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "is_public_enabled": true,
    "allowed_actions": ["read", "download"],
    "password": "autumn-2026"
  }'
```

The collection's link is `https://app.shade.inc/collection/INVITE_ID`, using the `invite_id` from `GET /collections/{collection_id}`.

## Tips

* Give every share link a clear `name`. It's what you'll see when listing a drive's links later.
* Use `expiration_date` or `max_view_count` for client deliveries, so links don't stay open forever.
* Share a collection rather than a folder when the files you want to send live in different folders.

## Related

* [Working with assets](/developers/using-the-api/working-with-assets.md)
* [Searching and filtering assets](/developers/using-the-api/searching-and-filtering-assets.md)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://academy.shade.inc/developers/using-the-api/collections-and-share-links.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `build a script that syncs our docs to a CMS` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.