API REST e token API
Con un token API, i tuoi sistemi, come un MAM, un CMS o i tuoi script, lavorano con un workspace tramite l’API REST. L’API REST è disponibile con i piani Enterprise e OnPremise. La documentazione API descrive ogni route.
- Piani
- Enterprise e OnPremise
- Chi crea i token
- Ogni membro, per sé; gli amministratori vedono e revocano tutti i token del workspace
- Cosa può fare un token
- Ciò che consentono i suoi permessi, mai più del ruolo della persona a cui appartiene, in un solo workspace
Cosa può fare l’API
Tramite l’API, i tuoi sistemi leggono episodi, trascrizioni e clip, caricano episodi in più parti o li importano da spazi di archiviazione collegati, modificano clip, le inviano per l’approvazione, le approvano o le rimandano indietro, pianificano e pubblicano le clip approvate e avviano attività di IA. Possono anche gestire i brand kit, il team, le regole editoriali e i webhook, leggere il log di audit e i consumi, recuperare le clip approvate con i relativi file per un CMS e consegnare clip al tuo MAM o DAM.
L’API segue le stesse regole dell’app: ruoli, approvazione, embargo e quota. Attività di IA e upload vengono scalati dalla quota della tua organizzazione.
Creare un token API
Ogni membro del workspace può creare token per sé.
- Apri Settings → API.
- Clicca su Create token.
- In Name, indica a cosa serve il token, per esempio il sistema che lo usa.
- In Valid for, scegli 30, 90, 180 o 365 giorni.
- In Permissions, togli la spunta a tutto ciò di cui il sistema non ha bisogno. All’inizio tutti i permessi sono spuntati.
- Clicca su Create.
- Clicca su Copy e conserva il token dove il tuo sistema custodisce i propri segreti. ShowBits lo mostra solo questa volta e ne conserva solo un’impronta.
- Clicca su Done.
Il token agisce come te, con il tuo ruolo, e solo in questo workspace; non può mai fare più di quanto consenta il tuo ruolo. Puoi avere fino a 20 token validi per workspace.

Vedere e revocare i token
L’elenco in API tokens mostra ogni token con il nome, la parte finale del suo valore, lo stato (Active, Expired o Revoked), chi l’ha creato, quando è stato creato, fino a quando è valido e quando è stato usato l’ultima volta. Tu vedi i tuoi token; gli amministratori vedono tutti i token del workspace e possono revocarli.
- Apri Settings → API.
- Clicca su Revoke accanto al token.
- Conferma con Revoke. I sistemi che usano il token perdono subito l’accesso. L’operazione non può essere annullata.
Un token termina anche quando scade e quando la persona a cui appartiene lascia il workspace, e funziona solo finché il piano della tua organizzazione include l’API. Crea un nuovo token per tempo, prima che quello vecchio scada.

La prima richiesta
L’indirizzo di base e la OpenAPI description si trovano nella stessa pagina dei tuoi token. La descrizione OpenAPI elenca ogni route in un formato leggibile dalle macchine; la documentazione API mostra ogni route con il permesso necessario.
- Apri Settings → API e copia l’indirizzo accanto a Base address. In ShowBits Cloud è
https://app.showbits.ai/api/v1. - Invia il token con ogni richiesta, nell’header
Authorization: Bearer sbk_…. - Prova:
curl -H 'Authorization: Bearer sbk_…' https://app.showbits.ai/api/v1/merisponde con il tuo nome, il workspace del token con il suoslug, i permessi del token e la sua scadenza. - Usa lo slug nei percorsi del workspace. Per esempio,
curl -H 'Authorization: Bearer sbk_…' 'https://app.showbits.ai/api/v1/workspaces/talk-am-abend/clips?status=review'elenca le clip in attesa di approvazione nel workspace talk-am-abend; serve il permesso Read clips, texts, videos and subtitles.
In ShowBits OnPremise, l’indirizzo di base è quello della tua installazione. Le risposte sono in JSON in camelCase, con gli orari in UTC (ISO 8601) e gli ID come UUID.
Approvare tramite l’API
Un sistema può approvare clip o rimandarle indietro solo con un token che ha il permesso Approve clips and send them back (clips:approve). Un token del genere approva a tuo nome, quindi assegna questo permesso solo ai token che ne hanno bisogno. La finestra di dialogo lo segnala accanto al permesso: “This lets a system approve clips in your name.”
Ogni chiamata è una fase di approvazione, come un clic nell’app: la risposta è forwarded quando la clip passa alla fase successiva, o approved quando è approvata in via definitiva. Il sistema approva con un POST sulla route della clip che termina con /approve e rimanda indietro una clip con /reject, entrambi con un comment facoltativo. Una clip rimandata indietro deve prima tornare in approvazione; fino ad allora l’API risponde con 409.
Limiti, errori e paginazione
Per token e per minuto, ShowBits accetta 600 richieste di lettura e 60 di scrittura. Gli header RateLimit-Limit, RateLimit-Remaining e RateLimit-Reset mostrano a che punto sei; oltre il limite, la risposta è 429 con Retry-After. Gli errori arrivano come application/problem+json (RFC 9457) con reason, una parola fissa in base alla quale il tuo sistema può distinguere i casi: 401 nessun token valido, 403 permesso o ruolo mancante, 404 sconosciuto o in un altro workspace, 409 non possibile nello stato attuale (per esempio notApproved o embargo), 413 file troppo grande, 422 input non valido, 429 limite o quota.
Gli elenchi arrivano in pagine fino a 200 voci (50 per impostazione predefinita, regolabile con ?limit=). Per la pagina successiva, passa nextCursor della risposta come ?cursor=.
Azioni API nel log di audit
Ogni modifica fatta con un token compare nel log di audit come azione della persona a cui appartiene, con “through the API token” e il nome del token. Anche la creazione e la revoca dei token vengono registrate.
- Apri Settings → Security.
- Scorri in basso fino a Audit log.
Domande
Un token può funzionare in più workspace?
No. Un token appartiene a una persona e a un workspace. Per un altro workspace, crea un token lì.
Non ho copiato il token in tempo. ShowBits può mostrarlo di nuovo?
No. ShowBits ne conserva solo un’impronta. Revoca il token e creane uno nuovo.
Cosa succede ai token di chi lascia il workspace?
Terminano subito. I sistemi che li usavano hanno bisogno di un nuovo token, creato da un’altra persona.
Un sistema può collegare spazi di archiviazione, canali o chiavi IA tramite l’API?
No. Connessioni, chiavi IA, le credenziali di un MAM, token API e fatturazione vengono configurati da una persona nell’app.
Posso inviare di nuovo una richiesta senza rischi?
Sì. Un POST può avere l’header Idempotency-Key: per ogni token e chiave viene eseguito una sola volta nell’arco di 24 ore, e la stessa richiesta riceve di nuovo la risposta salvata. PUT, PATCH e DELETE si possono comunque ripetere.
Le modifiche all’API possono rompere la nostra integrazione?
/v1 cresce soltanto: nuovi campi, route ed eventi. Ignora i campi sconosciuti nelle risposte; l’API rifiuta i campi sconosciuti nelle richieste.
Abbiamo Creator o Business. Possiamo usare l’API?
L’API REST è disponibile con Enterprise e OnPremise; negli altri piani, Settings → API offre Write to us. In tutti i piani, n8n, Zapier e Make si collegano senza l’API: vedi n8n, Zapier e Make.