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

  1. Apri Settings → API.
  2. Clicca su Create token.
  3. In Name, indica a cosa serve il token, per esempio il sistema che lo usa.
  4. In Valid for, scegli 30, 90, 180 o 365 giorni.
  5. In Permissions, togli la spunta a tutto ciò di cui il sistema non ha bisogno. All’inizio tutti i permessi sono spuntati.
  6. Clicca su Create.
  7. 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.
  8. 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.

Screenshot di ShowBits: Creare un token API

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.

  1. Apri Settings → API.
  2. Clicca su Revoke accanto al token.
  3. 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.

Screenshot di ShowBits: Vedere e revocare i token

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.

  1. Apri Settings → API e copia l’indirizzo accanto a Base address. In ShowBits Cloud è https://app.showbits.ai/api/v1.
  2. Invia il token con ogni richiesta, nell’header Authorization: Bearer sbk_….
  3. Prova: curl -H 'Authorization: Bearer sbk_…' https://app.showbits.ai/api/v1/me risponde con il tuo nome, il workspace del token con il suo slug, i permessi del token e la sua scadenza.
  4. 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.

  1. Apri Settings → Security.
  2. 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.