API REST y tokens de API

Con un token de API, tus propios sistemas, como un MAM, un CMS o tus scripts, trabajan con un espacio de trabajo a través de la API REST. La API REST se incluye en los planes Enterprise y OnPremise. La documentación de la API describe cada ruta.

Planes
Enterprise y OnPremise
Quién crea tokens
Cada miembro, para sí mismo; los administradores ven y revocan todos los tokens del espacio de trabajo
Qué puede hacer un token
Lo que permitan sus permisos, nunca más que el rol de la persona a la que pertenece, en un solo espacio de trabajo

Qué puede hacer la API

A través de la API, tus sistemas leen episodios, transcripciones y clips, suben episodios por partes o los importan desde almacenamientos conectados, editan clips, los envían a aprobación, los aprueban o los devuelven, programan y publican clips aprobados e inician tareas de IA. También pueden gestionar kits de marca, el equipo, las normas editoriales y los webhooks, leer el registro de auditoría y el consumo, obtener clips aprobados con sus archivos para un CMS y entregar clips a tu MAM o DAM.

La API sigue las mismas reglas que la app: roles, aprobación, embargo y cuota. Las tareas de IA y las subidas se descuentan de la cuota de tu organización.

Crear un token de API

Cualquier miembro del espacio de trabajo puede crear tokens para sí mismo.

  1. Abre Settings → API.
  2. Haz clic en Create token.
  3. En Name, indica para qué sirve el token, por ejemplo, el sistema que lo usa.
  4. En Valid for, elige 30, 90, 180 o 365 días.
  5. En Permissions, desmarca todo lo que el sistema no necesite. Al principio, todos los permisos están marcados.
  6. Haz clic en Create.
  7. Haz clic en Copy y guarda el token donde tu sistema guarda sus secretos. ShowBits solo lo muestra esta vez y solo conserva una huella digital del token.
  8. Haz clic en Done.

El token actúa como tú, con tu rol y solo en este espacio de trabajo; nunca puede hacer más que tu rol. Puedes tener hasta 20 tokens válidos por espacio de trabajo.

Captura de pantalla de ShowBits: Crear un token de API

Ver y revocar tokens

La lista de API tokens muestra cada token con su nombre, el final de su valor, su estado (Active, Expired o Revoked), quién lo creó, cuándo se creó, hasta cuándo es válido y cuándo se usó por última vez. Ves tus propios tokens; los administradores ven todos los tokens del espacio de trabajo y pueden revocarlos.

  1. Abre Settings → API.
  2. Haz clic en Revoke junto al token.
  3. Confirma con Revoke. Los sistemas que usan el token pierden el acceso de inmediato. Esta acción no se puede deshacer.

Un token también deja de funcionar cuando caduca y cuando la persona a la que pertenece deja el espacio de trabajo, y solo funciona mientras el plan de tu organización incluya la API. Crea un token nuevo con antelación, antes de que caduque el anterior.

Captura de pantalla de ShowBits: Ver y revocar tokens

Tu primera solicitud

La dirección base y la OpenAPI description están en la misma página que tus tokens. La descripción OpenAPI enumera cada ruta en un formato legible por máquinas; la documentación de la API muestra cada ruta con el permiso que necesita.

  1. Abre Settings → API y copia la dirección que aparece junto a Base address. En ShowBits Cloud es https://app.showbits.ai/api/v1.
  2. Envía el token con cada solicitud, en el encabezado Authorization: Bearer sbk_….
  3. Pruébalo: curl -H 'Authorization: Bearer sbk_…' https://app.showbits.ai/api/v1/me responde con tu nombre, el espacio de trabajo del token con su slug, los permisos del token y cuándo caduca.
  4. Usa el slug en las rutas del espacio de trabajo. Por ejemplo, curl -H 'Authorization: Bearer sbk_…' 'https://app.showbits.ai/api/v1/workspaces/talk-am-abend/clips?status=review' enumera los clips que esperan aprobación en el espacio de trabajo talk-am-abend; para ello se necesita el permiso Read clips, texts, videos and subtitles.

En ShowBits OnPremise, la dirección base es la de tu instalación. Las respuestas son JSON en camelCase, con las horas en UTC (ISO 8601) y los ID como UUID.

Aprobar a través de la API

Un sistema solo puede aprobar clips o devolverlos con un token que tenga el permiso Approve clips and send them back (clips:approve). Un token así aprueba en tu nombre, así que da este permiso solo a los tokens que lo necesiten. El diálogo lo indica junto al permiso: “This lets a system approve clips in your name.”

Cada llamada es un paso de aprobación, como un clic en la app: la respuesta indica forwarded cuando el clip pasa al siguiente paso, o approved cuando queda aprobado. El sistema aprueba con un POST a la ruta del clip terminada en /approve y devuelve un clip con /reject, ambos con un comment opcional. Un clip devuelto primero tiene que volver a pasar a aprobación; hasta entonces, la API responde con 409.

Límites, errores y paginación

Por token y por minuto, ShowBits acepta 600 solicitudes de lectura y 60 de escritura. Los encabezados RateLimit-Limit, RateLimit-Remaining y RateLimit-Reset muestran en qué punto estás; si los superas, la respuesta es 429 con Retry-After. Los errores llegan como application/problem+json (RFC 9457) con reason, una palabra fija con la que tu sistema puede decidir qué hacer: 401 no hay un token válido, 403 falta un permiso o un rol, 404 desconocido o en otro espacio de trabajo, 409 no es posible en el estado actual (por ejemplo, notApproved o embargo), 413 archivo demasiado grande, 422 entrada no válida, 429 límite o cuota.

Las listas llegan en páginas de hasta 200 entradas (50 por defecto, ajustable con ?limit=). Para la página siguiente, pasa nextCursor de la respuesta como ?cursor=.

Acciones de la API en el registro de auditoría

Cada cambio realizado con un token aparece en el registro de auditoría como una acción de la persona a la que pertenece, con “through the API token” y el nombre del token. La creación y la revocación de tokens también quedan registradas.

  1. Abre Settings → Security.
  2. Desplázate hacia abajo hasta Audit log.

Preguntas

¿Puede un token funcionar en varios espacios de trabajo?

No. Un token pertenece a una persona y a un espacio de trabajo. Para otro espacio de trabajo, crea un token allí.

No copié el token a tiempo. ¿Puede ShowBits volver a mostrarlo?

No. ShowBits solo conserva una huella digital del token. Revoca el token y crea uno nuevo.

¿Qué pasa con los tokens de alguien que deja el espacio de trabajo?

Dejan de funcionar de inmediato. Los sistemas que los usaban necesitan un token nuevo, creado por otra persona.

¿Puede un sistema conectar almacenamientos, canales o claves de IA a través de la API?

No. Las conexiones, las claves de IA, las credenciales de un MAM, los tokens de API y la facturación los configura una persona en la app.

¿Puedo volver a enviar una solicitud sin riesgo?

Sí. Un POST puede llevar el encabezado Idempotency-Key: por token y clave, se ejecuta una sola vez durante 24 horas, y la misma solicitud vuelve a recibir la respuesta guardada. PUT, PATCH y DELETE se pueden repetir de todos modos.

¿Puede cambiar la API y afectar a nuestra integración?

/v1 solo crece: campos, rutas y eventos nuevos. Ignora los campos desconocidos en las respuestas; la API rechaza los campos desconocidos en las solicitudes.

Tenemos Creator o Business. ¿Podemos usar la API?

La API REST se incluye en Enterprise y OnPremise; en otros planes, Settings → API ofrece Write to us. En todos los planes, n8n, Zapier y Make se conectan sin la API: consulta n8n, Zapier y Make.