Compartilhar Pastas e Projetos pela API

A API compartilha uma pasta ou projeto por um link público. No Kinescope, esse mecanismo é chamado de compartilhamento; a API usa os caminhos shares e os campos share_id e reset-token. Quem recebe o link não precisa de conta no Kinescope: vê vídeos e subpastas no navegador e informa uma senha quando necessário.

Os endpoints /v1/shares permitem criar um link a partir de um LMS, CRM ou backend próprio, alterar suas configurações e fechar o acesso. Antes de começar, leia as regras gerais da API.

Quando configurar o compartilhamento por código

• Um LMS libera acesso após o pagamento. Seu backend cria um link para a pasta de aulas e o envia ao aluno.
• Você precisa de acesso temporário. Defina uma data de expiração para um fornecedor ou parceiro.
• O link chegou à pessoa errada. Renove-o e envie o novo endereço sem alterar as outras configurações.
• Uma assinatura terminou. Revogue o acesso a todos os materiais com uma única solicitação.

Como o compartilhamento funciona

1. Você cria um compartilhamento para uma pasta ou projeto e recebe share_id, token e um link pronto.
2. O destinatário abre https://kinescope.io/sh/{token} e vê o catálogo sem entrar no Kinescope.
3. Uma pasta ou projeto pode ter apenas um link ativo.
4. Use PATCH para alterar senha, período de acesso, permissão de download ou nome.
5. reset-token cria um novo endereço, e DELETE revoga o acesso definitivamente.

Pastas e projetos usam o mesmo mecanismo: passe o ID de qualquer um deles em entity_id.

O que você precisa preparar

• Um token de API do workspace no cabeçalho Authorization: Bearer YOUR_API_TOKEN.
• Um plano pago: a criação de link não está disponível no plano gratuito.
• O ID da pasta ou do projeto. Você pode obtê-lo no upload de arquivos via API.
• A função admin, editor+, editor ou manager. A função viewer pode consultar as configurações de um link existente, mas não pode alterá-las.

Crie um link público

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": "Curso de Python — turma 12",
    "password": "python-2026",
    "allow_download": true,
    "expires_at": "2026-12-01T00:00:00Z"
  }'

Se você informar as duas datas, starts_at deve ser anterior a expires_at. Uma senha com menos de quatro caracteres não passa na validação da API.

Uma solicitação bem-sucedida retorna 201 Created:

{
  "data": {
    "share_id": "9f1d3c02-77a0-4f5e-8b26-1e0a5d3c8b41",
    "entity_id": "5b8a54a1-1f4f-4a5f-9a3a-2a4b0e2f1c77",
    "display_name": "Curso de Python — turma 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"
  }
}

Guarde o share_id: ele será necessário nas próximas solicitações. Envie ao destinatário o valor de link.

Consulte as configurações de um link existente

Se você souber o share_id, consulte as configurações diretamente:

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

Se você souber apenas o ID da pasta ou do projeto, use entity_id:

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

As duas solicitações retornam o link ativo. Depois da revogação, ele não é encontrado por share_id nem por entity_id.

Altere senha, datas ou permissão de download

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

Envie apenas os campos que precisa alterar:

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

Alterar ou remover uma senha encerra as sessões ativas dos destinatários. Eles precisam abrir o link e passar pela verificação novamente.

Renove o endereço do link

Chame reset-token quando precisar substituir um link:

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

A resposta contém um novo objeto de compartilhamento, com novos share_id, token e link. As configurações são mantidas, mas o endereço antigo para de funcionar imediatamente. Atualize o share_id salvo e envie o novo link aos destinatários.

Revogue o acesso

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'

Depois da revogação, o link e todos os links diretos para vídeos ou subpastas deixam de funcionar. Crie outro link para compartilhar o item novamente.

Trate os erros mais comuns

Se você repetir POST para a mesma pasta ou projeto, a API retorna 409. Primeiro obtenha o link existente por entity_id; depois atualize-o ou revogue-o.

O que fazer a seguir?

1. Upload de Arquivos via API — obtenha o ID de um projeto ou pasta e adicione vídeos.
2. Regras Gerais da API — autorização, formato de erros e limites de requisições.
3. Como compartilhar uma pasta ou projeto — o fluxo no painel e a experiência de quem recebe o link.