API REST e tokens de API
Com um token de API, os seus próprios sistemas, como um MAM, um CMS ou os seus scripts, trabalham com um espaço de trabalho pela API REST. A API REST faz parte dos planos Enterprise e OnPremise. A documentação da API descreve cada rota.
- Planos
- Enterprise e OnPremise
- Quem cria tokens
- Cada membro, para si mesmo; os administradores veem e revogam todos os tokens do espaço de trabalho
- O que um token pode fazer
- O que as permissões dele permitem, nunca mais do que a função da pessoa a quem pertence, em um único espaço de trabalho
O que a API pode fazer
Pela API, os seus sistemas leem episódios, transcrições e clipes, enviam episódios em partes ou os importam de armazenamentos conectados, editam clipes, os enviam para aprovação, os aprovam ou devolvem, agendam e publicam clipes aprovados e iniciam tarefas de IA. Eles também podem gerenciar kits de marca, a equipe, as regras editoriais e os webhooks, ler o log de auditoria e o consumo, buscar clipes aprovados com os seus arquivos para um CMS e entregar clipes ao seu MAM ou DAM.
A API segue as mesmas regras do aplicativo: funções, aprovação, embargo e cota. Tarefas de IA e uploads contam na cota da sua organização.
Criar um token de API
Cada membro do espaço de trabalho pode criar tokens para si mesmo.
- Abra Settings → API.
- Clique em Create token.
- Em Name, indique para que serve o token, por exemplo o sistema que vai usá-lo.
- Em Valid for, escolha 30, 90, 180 ou 365 dias.
- Em Permissions, desmarque tudo de que o sistema não precisa. No início, todas as permissões vêm marcadas.
- Clique em Create.
- Clique em Copy e guarde o token onde o seu sistema guarda os segredos dele. O ShowBits o exibe somente esta vez e guarda apenas uma impressão digital dele.
- Clique em Done.
O token age como você, com a sua função, e somente neste espaço de trabalho; ele nunca pode fazer mais do que a sua função permite. Você pode ter até 20 tokens válidos por espaço de trabalho.

Ver e revogar tokens
A lista em API tokens mostra cada token com o nome, o final do valor, o status (Active, Expired ou Revoked), quem o criou, quando foi criado, até quando é válido e quando foi usado pela última vez. Você vê os seus próprios tokens; os administradores veem todos os tokens do espaço de trabalho e podem revogá-los.
- Abra Settings → API.
- Clique em Revoke ao lado do token.
- Confirme com Revoke. Os sistemas que usam o token perdem o acesso imediatamente. Isso não pode ser desfeito.
Um token também deixa de valer quando expira e quando a pessoa a quem pertence sai do espaço de trabalho, e só funciona enquanto o plano da sua organização incluir a API. Crie um token novo com antecedência, antes que o antigo expire.

A sua primeira requisição
O endereço base e a OpenAPI description ficam na mesma página que os seus tokens. A descrição OpenAPI lista todas as rotas em formato legível por máquina; a documentação da API mostra cada rota com a permissão de que ela precisa.
- Abra Settings → API e copie o endereço que aparece depois de Base address. No ShowBits Cloud, ele é
https://app.showbits.ai/api/v1. - Envie o token em todas as requisições, no cabeçalho
Authorization: Bearer sbk_…. - Faça um teste:
curl -H 'Authorization: Bearer sbk_…' https://app.showbits.ai/api/v1/meresponde com o seu nome, o espaço de trabalho do token com oslugdele, as permissões do token e quando ele expira. - Use o slug nos caminhos do espaço de trabalho. Por exemplo,
curl -H 'Authorization: Bearer sbk_…' 'https://app.showbits.ai/api/v1/workspaces/talk-am-abend/clips?status=review'lista os clipes que aguardam aprovação no espaço de trabalho talk-am-abend; para isso, é preciso a permissão Read clips, texts, videos and subtitles.
No ShowBits OnPremise, o endereço base é o da sua instalação. As respostas vêm em JSON com camelCase, com horários em UTC (ISO 8601) e IDs como UUIDs.
Aprovar pela API
Um sistema só pode aprovar ou devolver clipes com um token que tenha a permissão Approve clips and send them back (clips:approve). Um token assim aprova em seu nome; por isso, dê essa permissão apenas aos tokens que precisam dela. A caixa de diálogo avisa isso ao lado da permissão: “This lets a system approve clips in your name.”
Cada chamada é uma etapa de aprovação, como um clique no aplicativo: a resposta diz forwarded quando o clipe passa para a etapa seguinte, ou approved quando ele é liberado. O sistema aprova com um POST na rota do clipe terminada em /approve e devolve um clipe com /reject, ambos com um comment opcional. Um clipe devolvido precisa primeiro voltar para a aprovação; até lá, a API responde com 409.
Limites, erros e paginação
Por token e por minuto, o ShowBits aceita 600 requisições de leitura e 60 de escrita. Os cabeçalhos RateLimit-Limit, RateLimit-Remaining e RateLimit-Reset mostram a sua situação; acima disso, a resposta é 429 com Retry-After. Os erros vêm como application/problem+json (RFC 9457) com reason, uma palavra fixa que o seu sistema pode usar para distinguir os casos: 401 nenhum token válido, 403 falta de permissão ou de função, 404 desconhecido ou em outro espaço de trabalho, 409 não é possível no estado atual (por exemplo notApproved ou embargo), 413 arquivo grande demais, 422 entrada inválida, 429 limite ou cota.
As listas vêm em páginas de até 200 itens (50 por padrão, ajustável com ?limit=). Para a próxima página, passe o nextCursor da resposta como ?cursor=.
Ações da API no log de auditoria
Toda alteração feita com um token aparece no log de auditoria como uma ação da pessoa a quem ele pertence, com “through the API token” e o nome do token. A criação e a revogação de tokens também ficam registradas.
- Abra Settings → Security.
- Role a página até Audit log.
Perguntas
Um token pode funcionar em vários espaços de trabalho?
Não. Um token pertence a uma pessoa e a um espaço de trabalho. Para outro espaço de trabalho, crie um token lá.
Não copiei o token a tempo. O ShowBits pode exibi-lo de novo?
Não. O ShowBits guarda apenas uma impressão digital dele. Revogue o token e crie um novo.
O que acontece com os tokens de alguém que sai do espaço de trabalho?
Eles deixam de valer imediatamente. Os sistemas que os usavam precisam de um token novo, criado por outra pessoa.
Um sistema pode conectar armazenamentos, canais ou chaves de IA pela API?
Não. Conexões, chaves de IA, as credenciais de um MAM, tokens de API e o faturamento são configurados por uma pessoa no aplicativo.
Posso reenviar uma requisição com segurança?
Sim. Um POST pode levar o cabeçalho Idempotency-Key: por token e por chave, ele é executado uma única vez durante 24 horas, e a mesma requisição recebe de novo a resposta armazenada. PUT, PATCH e DELETE podem ser repetidos de qualquer forma.
A API vai mudar e afetar a nossa integração?
A /v1 só cresce: novos campos, rotas e eventos. Ignore campos desconhecidos nas respostas; a API recusa campos desconhecidos nas requisições.
Estamos no Creator ou no Business. Podemos usar a API?
A API REST faz parte do Enterprise e do OnPremise; nos outros planos, Settings → API oferece Write to us. Em todos os planos, o n8n, o Zapier e o Make se conectam sem a API: veja n8n, Zapier e Make.