Démarrer : une clé et un premier appel

L’API publique Videas permet à l’un de vos serveurs de travailler avec la bibliothèque de votre organisation et avec ses chaînes : lire ce que la bibliothèque contient — ses assets et les workspaces où ils sont rangés —, y ajouter des fichiers et des vidéos hébergées ailleurs, modifier ce qui s’y trouve, et le publier sur les chaînes de l’organisation. Elle répond sur https://api.videas.com/v1, parle JSON sur HTTPS, et se décrit dans un contrat OpenAPI 3.1, que la référence de l’API présente et permet de télécharger.

Trois choses à faire, dans cet ordre : créer une clé, la garder sur un serveur, et l’envoyer avec chaque requête.

Créer une clé

Ce sont les propriétaires et les administrateurs de l’organisation qui créent les clés, dans l’application Videas :

1. Ouvrez Paramètres → Accès API, puis Créer une clé.
2. Nom de la clé : ce à quoi elle sert — « Synchro CMS », « Import LMS » —, pour la reconnaître dans la liste, et dans l’historique des assets qu’elle modifie.
3. Expiration : pas d’expiration, 30 jours, 60 jours, 90 jours ou un an. Une clé qui expire d’elle-même, c’est un secret oublié de moins.
4. Ce que la clé peut faire : cochez les permissions dont l’intégration a besoin, et rien de plus. Celles qui lisent sont cochées par défaut ; celles qui écrivent sont décochées, pour qu’une clé qui écrit soit toujours créée délibérément.
5. Créer la clé, puis Copier la clé. Sa valeur complète, ak_…, s’affiche cette seule fois et ne pourra plus être lue : rangez-la tout de suite. Une clé dont la valeur est perdue se révoque et se remplace.

Une clé appartient à l’organisation, pas à la personne qui l’a créée. Elle continue de fonctionner quand cette personne s’en va, et tout ce qu’elle atteint appartient à cette seule organisation.

Ses permissions

Une clé ouvre l’API avec les permissions qu’elle porte, et aucune autre. Elle peut en porter sept, et chacune ouvre ce qu’elle dit :

• Aucune n’en implique une autre : une clé créée pour publier ne peut pas modifier un asset, et une clé créée pour modifier ne peut pas lire la bibliothèque. Une écriture répond ce qu’elle a écrit, que la clé puisse lire ou non.
• Trois dépendent de ce qu’utilise l’organisation. Les deux permissions des chaînes n’ouvrent rien pour une organisation qui ne publie pas de chaînes : chaque endpoint des chaînes lui répond 403, comme à une clé qui ne les porte pas. Et assets.third_party_video.import n’ouvre rien tant que Videas n’a pas activé les vidéos hébergées ailleurs pour l’organisation : jusque-là, POST /v1/assets répond 404. Une clé peut les porter d’avance, et fonctionne sans rien changer le jour où l’organisation a la fonction.
• Une clé sans permission n’ouvre rien.

La garder sur un serveur

La clé est un secret, comme un mot de passe :

• rangez-la dans un gestionnaire de secrets ou dans une variable d’environnement que lit votre serveur — jamais dans un dépôt de code, une page web ou une application que vous distribuez à vos utilisateurs ;
• donnez à chaque intégration sa propre clé, pour pouvoir en révoquer une sans toucher aux autres ;
• pour en révoquer une, Révoquer dans le même écran : tout ce qui l’utilise encore cesse aussitôt de s’authentifier.

Une page web ne peut de toute façon pas appeler l’API : /v1 n’envoie aucun en-tête CORS, le navigateur refuse donc de transmettre ses réponses à la page. Pour que vos utilisateurs envoient des fichiers depuis leur navigateur, votre serveur ouvre l’upload et ne confie à la page que le jeton propre à cet upload, jamais la clé — voir Ajouter un fichier par l’API.

L’envoyer avec chaque requête

La clé part dans l’en-tête Authorization, en jeton Bearer :

Authorization: Bearer ak_…

Sans elle, ou avec une clé inconnue, expirée ou révoquée, la réponse est un 401 de code unauthorized. Une clé qui ne porte pas la permission que demande un endpoint reçoit un 403, forbidden.

Votre premier appel

Listez les assets de votre bibliothèque :

export VIDEAS_API_KEY="ak_…"   # mieux : depuis votre gestionnaire de secrets

curl https://api.videas.com/v1/assets \
  -H "Authorization: Bearer $VIDEAS_API_KEY"

La réponse est une page d’assets, du plus ancien au plus récent, avec le curseur de la page suivante :

{
  "data": [
    {
      "id": "0192a6b2-4f1a-7b90-8e0d-51c3a7f2b046",
      "name": "Cours d’ouverture",
      "type": "video",
      "status": "ready",
      "workspace_id": "0192a6b1-7c3e-7d40-9a51-3f0e2b6c8d10",
      "description": null,
      "external_ref": "cours-42/seance-1",
      "language": "fr",
      "duration_ms": 2712000,
      "created_at": "2026-09-26T09:12:44Z",
      "updated_at": "2026-09-26T09:31:02Z",
      "third_party": null,
      "thumbnail_url": "https://app.videas.com/images/assets/0192a6b2-4f1a-7b90-8e0d-51c3a7f2b046/thumbnail.jpg"
    }
  ],
  "next": "MDE5MmE2YjItNGYxYS03Yjkw…"
}

Le même appel en Node.js (18 ou plus) et en Python, sur votre serveur :

const response = await fetch('https://api.videas.com/v1/assets', {
  headers: { Authorization: `Bearer ${process.env.VIDEAS_API_KEY}` },
})
const page = await response.json()
if (!response.ok) throw new Error(`${page.code}: ${page.message}`)
console.log(page.data.length, 'assets sur cette page')

import os

import requests

response = requests.get(
    "https://api.videas.com/v1/assets",
    headers={"Authorization": f"Bearer {os.environ['VIDEAS_API_KEY']}"},
)
response.raise_for_status()
page = response.json()
print(len(page["data"]), "assets sur cette page")

Un 403 ici signifie que la clé ne peut pas lire la bibliothèque : créez-en une avec Lire la bibliothèque par l’API cochée.

Ce que fait l’API

La bibliothèque

Y ajouter

Modifier un asset

Les chaînes

Ce qui a été regardé

De nouvelles ressources arrivent sous /v1 sans rien changer à ce qui y est déjà — Erreurs, limites et versions dit ce qui peut changer et ce qui ne le peut pas.

Pour aller plus loin

• Lire la bibliothèque — filtres, pages, comptages, un asset, les workspaces.
• Ajouter un fichier par l’API, depuis un lien, ou une vidéo hébergée ailleurs.
• Modifier un asset, ses champs personnalisés et sa vignette.
• Publier sur une chaîne.
• Erreurs, limites et versions — que faire de chaque refus.
• La référence de l’API : chaque endpoint, chaque champ et chaque erreur, générés depuis le contrat.