# Share Folders and Projects via API


The API shares a folder or project through a public link. In Kinescope, this mechanism is called sharing; the API uses the `shares` paths and the `share_id` and `reset-token` fields. Recipients do not need a Kinescope account: they view videos and subfolders in a browser and enter a password when required.

The `/v1/shares` endpoints let you create a link from an LMS, CRM, or your own backend, change its settings, and close access. Before you begin, read the [general API guidelines](https://docs.kinescope.com/developer-guides/api-general-rules/).

## When to configure sharing in code

* **An LMS grants access after payment.** Your backend creates a link to a lesson folder and sends it to a student.
* **You need time-limited access.** Set an expiry date for a contractor or partner.
* **A link reached the wrong recipient.** Reset it and send the new address without changing the other settings.
* **A subscription has ended.** Revoke access to all materials with one request.

## How sharing works

1. Create a share for a folder or project and receive a `share_id`, `token`, and ready-to-use link.
2. The recipient opens `https://kinescope.io/sh/{token}` and sees the catalog without signing in to Kinescope.
3. A folder or project can have only one active link.
4. Use `PATCH` to change the password, access period, download permission, or name.
5. `reset-token` creates a new address, and `DELETE` revokes access permanently.

Folders and projects use the same mechanism: pass the ID of either object as `entity_id`.

## What you need

* A workspace API token in the `Authorization: Bearer YOUR_API_TOKEN` header.
* A paid plan: creating a link is not available on the free plan.
* A folder or project ID. You can obtain it while [uploading files via API](https://docs.kinescope.com/developer-guides/file-upload-via-api/#preparation-getting-the-project-or-folder-id).
* The admin, editor+, editor, or manager role. The viewer role can read an existing link's settings but cannot change them.

## Create a public link

`POST https://api.kinescope.io/v1/shares`

```bash
curl -X POST 'https://api.kinescope.io/v1/shares' \
  -H 'Authorization: Bearer YOUR_API_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "entity_id": "5b8a54a1-1f4f-4a5f-9a3a-2a4b0e2f1c77",
    "display_name": "Python course — cohort 12",
    "password": "python-2026",
    "allow_download": true,
    "expires_at": "2026-12-01T00:00:00Z"
  }'
```

| Field | Type | Required | Description |
|---|---|---|---|
| `entity_id` | UUID | Yes | ID of a folder or project |
| `display_name` | string | No | Link name, up to 255 characters |
| `password` | string | No | A password with four or more characters |
| `allow_download` | boolean | No | Allows video downloads; defaults to `false` |
| `starts_at` | RFC3339 | No | The time when the link starts working |
| `expires_at` | RFC3339 | No | The time when the link stops working |

When you provide both dates, `starts_at` must be earlier than `expires_at`. A password shorter than four characters fails API validation.

A successful request returns `201 Created`:

```json
{
  "data": {
    "share_id": "9f1d3c02-77a0-4f5e-8b26-1e0a5d3c8b41",
    "entity_id": "5b8a54a1-1f4f-4a5f-9a3a-2a4b0e2f1c77",
    "display_name": "Python course — cohort 12",
    "has_password": true,
    "allow_download": true,
    "starts_at": null,
    "expires_at": "2026-12-01T00:00:00Z",
    "is_active": true,
    "token": "iVv6uEZ5V3DZ2ytZ28RUru",
    "link": "https://kinescope.io/sh/iVv6uEZ5V3DZ2ytZ28RUru"
  }
}
```

Save the `share_id`: you need it for subsequent requests. Send the recipient the value of `link`.

> **Внимание:**

Do not expose an API token in a browser or mobile application. Create and manage links only from your backend.



## Get an existing link's settings

If you know the `share_id`, request its settings directly:

```bash
curl 'https://api.kinescope.io/v1/shares/9f1d3c02-77a0-4f5e-8b26-1e0a5d3c8b41' \
  -H 'Authorization: Bearer YOUR_API_TOKEN'
```

If you only know the folder or project ID, use `entity_id`:

```bash
curl 'https://api.kinescope.io/v1/shares/entity/5b8a54a1-1f4f-4a5f-9a3a-2a4b0e2f1c77' \
  -H 'Authorization: Bearer YOUR_API_TOKEN'
```

Both requests return the active link. After it is revoked, it can no longer be found by either `share_id` or `entity_id`.

## Change the password, dates, or download permission

`PATCH https://api.kinescope.io/v1/shares/{share_id}`

Send only the fields you need to change:

```bash
curl -X PATCH 'https://api.kinescope.io/v1/shares/9f1d3c02-77a0-4f5e-8b26-1e0a5d3c8b41' \
  -H 'Authorization: Bearer YOUR_API_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "password": "new-password",
    "allow_download": false,
    "expires_at": "2027-01-15T00:00:00Z"
  }'
```

| Value to send | Result |
|---|---|
| Omit a field | Its value does not change |
| `"password": "new-password"` | Sets or replaces the password |
| `"password": ""` | Removes the password |
| `"display_name": ""` | Removes the custom link name |
| `"starts_at": null` or `"expires_at": null` | Removes the date restriction |

Changing or removing a password ends recipients' active sessions. They must open the link and pass access verification again.

## Reset a link address

Call `reset-token` when you need to replace a link:

```bash
curl -X POST 'https://api.kinescope.io/v1/shares/9f1d3c02-77a0-4f5e-8b26-1e0a5d3c8b41/reset-token' \
  -H 'Authorization: Bearer YOUR_API_TOKEN'
```

The response contains a new sharing object with a new `share_id`, `token`, and `link`. It retains the settings, while the old address stops working immediately. Update your saved `share_id` and send the new link to recipients.

## Revoke access

`DELETE https://api.kinescope.io/v1/shares/{share_id}`

```bash
curl -X DELETE 'https://api.kinescope.io/v1/shares/9f1d3c02-77a0-4f5e-8b26-1e0a5d3c8b41' \
  -H 'Authorization: Bearer YOUR_API_TOKEN'
```

After revocation, the link and all deep links to its videos or subfolders stop working. Create a new link to share the item again.

## Handle common errors

| HTTP | When it happens |
|---|---|
| `403 Forbidden` | The token lacks the required role or item access, or the plan does not support sharing |
| `404 Not Found` | The link or item was not found |
| `409 Conflict` | The item already has an active link, or you cannot reset revoked access |
| `422 Unprocessable Entity` | The password, dates, or another field fails validation |

If you repeat `POST` for the same folder or project, the API returns `409`. Get the existing link by `entity_id`, then update or revoke it.

## What's next?

1. **[File Upload via API](https://docs.kinescope.com/developer-guides/file-upload-via-api/)** — get a project or folder ID and populate it with videos.
2. **[General API Guidelines](https://docs.kinescope.com/developer-guides/api-general-rules/)** — authorization, error format, and rate limits.
3. **[Share a Folder or Project](https://docs.kinescope.com/catalog-and-video-management/sharing-folders-and-projects/)** — the dashboard workflow and recipient experience.