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.

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

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"
  }'

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:

{
  "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.

Get an existing link’s settings

If you know the share_id, request its settings directly:

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:

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:

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"
  }'

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:

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}

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

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 — get a project or folder ID and populate it with videos.
2. General API Guidelines — authorization, error format, and rate limits.
3. Share a Folder or Project — the dashboard workflow and recipient experience.