Skip to main content
POST
Registra uma mídia

Authorizations

Authorization
string
header
required

Token OPACO de sessão de quem administra, emitido por /v1/auth/admin/sign-in e verificado contra a nossa tabela — o mesmo desenho do studentSession, para a outra identidade.

É o esquema de quem ADMINISTRA — o dashboard. O aluno do classroom usa o studentSession; uma rota consumida pelos dois declara os dois esquemas, e o middleware aceita qualquer um deles. As duas credenciais são opacas e chegam pelo mesmo cabeçalho: quem as separa é a tabela em que cada uma existe.

O dashboard o guarda em cookie httpOnly, que o BFF troca pelo Authorization a cada chamada.

Path Parameters

clubId
string<uuid>
required

Id público da organização — o mesmo que GET /v1/me devolve em organization_id.

Na URL o recurso se chama club; no contrato e no domínio, organization. A divergência é deliberada: clubs é a palavra do produto, e a URL é o que as pessoas leem.

É o identificador do provedor de autenticação, e é assim de propósito: o cliente precisa nomear a organização ao pedir o token, e o token é o que prova o escopo. Um id só nosso obrigaria a traduzir um no outro antes de ter um token — e a tradução exigiria uma chamada escopada, que é justamente a que ainda não dá para fazer.

O uuid interno da organização não aparece no contrato: ele é o que as chaves estrangeiras do domínio referenciam, e continua sendo nosso.

Body

application/json
title
string
required
Required string length: 1 - 200
kind
enum<string>

Rótulo de tela — o ícone e o filtro. Nada de acesso lê isto.

Available options:
video,
audio,
image,
document
provider
enum<string>

Ausente significa "hospede você": a resposta traz a assinatura de envio, na Bunny para vídeo e no R2 para arquivo.

Available options:
bunny_stream,
r2,
youtube,
vimeo,
external,
safevideo
visibility
enum<string>

Ausente é private. public manda o arquivo para o bucket com domínio próprio, de onde ele é entregue sem assinatura.

Available options:
private,
public
file_name
string

O nome do arquivo que vai ser enviado. Dele sai a chave do objeto, e é ele que o navegador mostra quando o aluno salva o material.

Maximum string length: 255
mime
string
Maximum string length: 255
external_id
string

O vídeo no YouTube ou no Vimeo, ou a URL em external.

Para youtube e vimeo vale o LINK da barra de endereços ou o id cru: a API normaliza os dois para o mesmo id canônico, que é o que a resposta devolve e o que a tela usa para montar o player. O que não for vídeo daquele provedor é 422 invalid_external_id. Em external o valor é guardado como veio. Em safevideo é a chave do vídeo que o launcher do SafeVideo devolve.

Maximum string length: 2000
thumbnail_url
string

A miniatura do vídeo do SafeVideo, como o launcher a devolve — endereço https. Só vale para provider: safevideo; nos outros é ignorada, porque a miniatura sai do próprio provedor.

Maximum string length: 2000
folder_id
string<uuid>

Response

Mídia registrada

data
object
required
upload
object

O que o browser precisa para enviar o arquivo sozinho. O endereço e os cabeçalhos levam uma ASSINATURA — nunca a chave da conta —, valem para esta mídia e expiram.

tus é o envio em pedaços do vídeo (a Bunny retoma de onde parou); put é um envio único para o R2, e depois dele vem POST /media/{mediaId}/complete.