API et serveur MCP

La clé

Un administrateur la crée dans API. Elle porte un rôle (le même que les rôles d’équipe) et agit au nom de son créateur. Donnez-lui le rôle le plus faible qui suffit.

La clé n’est montrée qu’une fois, à sa création. Ensuite, la base n’en garde que l’empreinte. Perdue, elle se révoque et se recrée.

Une clé ne peut pas créer une autre clé, gérer l’équipe, engager une dépense, exporter les données ni supprimer une organisation. Ces gestes demandent une vraie session de navigateur.

Un exemple qui marche

Lister vos comptes connectés, pour récupérer leurs identifiants :

curl https://app.timalio.com/api/v1/comptes \
  -H "Authorization: Bearer tml_VOTRE_CLE"

Créer un post :

curl https://app.timalio.com/api/v1/posts \
  -H "Authorization: Bearer tml_VOTRE_CLE" \
  -H "content-type: application/json" \
  -d '{"texte":"Bonjour",
       "comptes":["<identifiant de compte>"],
       "programmeLe":"2026-10-01T09:00:00Z"}'

Le post est créé en brouillon (son état vaut BROUILLON dans la réponse). Il ne partira pas tant qu’il n’a pas été soumis puis validé.

Le soumettre à validation :

curl https://app.timalio.com/api/v1/posts/<id>/action \
  -H "Authorization: Bearer tml_VOTRE_CLE" \
  -H "content-type: application/json" \
  -d '{"action":"SOUMETTRE"}'

Ce qui est exposé

Les actions possibles sur un post sont SOUMETTRE, VALIDER, DEMANDER_REPRISE, MODIFIER, REPROGRAMMER, PROGRAMMER_DIRECTEMENT et SUPPRIMER. Ce sont les mêmes fonctions que l’interface, pas un second jeu de règles : une limite corrigée d’un côté l’est de l’autre.

Un champ inconnu dans une requête d’écriture (par exemple `format_instagram` au lieu de `formatInstagram`) est refusé par un 400 qui le nomme et propose le bon nom : rien n’est jamais ignoré en silence.

Attention à deux champs qui ne se comportent pas pareil quand on modifie un post : envoyer `comptes` ou `images` remplace ce qui existait, un tableau vide vide donc tout ; ne pas envoyer `variantes` les garde, et seul `{}` les efface. Corriger une coquille du texte commun ne doit pas effacer sans un mot l’adaptation écrite par quelqu’un d’autre.

Les plafonds de débit

Quelques routes sont plafonnées par organisation, sur une fenêtre glissante de dix minutes, pour protéger le disque de Timalio et les tiers qu’il appelle en votre nom. Un refus répond 429 avec un en-tête `Retry-After`, en secondes : le temps exact avant qu’un nouvel essai soit permis, et le message d’erreur annonce le même délai en minutes.

• Déposer une image ou une vidéo, directement ou par les outils MCP `envoyer_image`/`envoyer_video` : 60 par organisation toutes les 10 minutes.
• Récupérer une image ou une vidéo par `url` plutôt que la déposer compte sur son propre plafond, plus bas : 20 par organisation toutes les 10 minutes.
• Relire ou écrire un import CSV (`/api/v1/import/apercu` et `/api/v1/import/confirmer` partagent un seul compteur) : 20 par organisation toutes les 10 minutes.
• Vérifier un webhook Discord, une instance Mastodon ou une discussion Telegram : 30 par organisation toutes les 10 minutes.

Noms français, noms anglais

Timalio a d’abord été écrit en français, et chaque nom de cette page a un alias anglais. Les deux sont acceptés, partout, pour de bon : une requête peut employer l’un ou l’autre, champ par champ. Envoyer les deux noms d’un même champ passe quand les deux valeurs sont égales, et est refusé (400) quand elles diffèrent, en nommant les deux champs. Rien n’est choisi à votre place en silence.

Les réponses gardent leurs noms français, quoi que vous envoyiez : `texte`, `etat`, `programme_le`, et des valeurs comme BROUILLON, EN_ATTENTE, PROGRAMME, PUBLIE. Une seule forme, stable : une réponse qui changerait avec la requête casserait celui qui relit ce qu’il a écrit. Les messages d’erreur, eux, arrivent dans la langue du propriétaire de la clé. Deux sorties se demandent en anglais par `?names=en` : la liste des outils MCP, et la ligne d’en-tête de l’export CSV.

Le serveur MCP

La même clé branche une IA sur Timalio. Elle y trouve quatorze outils : lire les règles à jour d’un réseau, lister les comptes, lister et lire les posts, en programmer un ou le publier tout de suite, agir sur un post, déposer une image ou une vidéo, relancer un premier commentaire, et préparer la connexion d’un nouveau compte (plus bas).

{
  "mcpServers": {
    "timalio": {
      "url": "https://app.timalio.com/api/mcp",
      "headers": { "Authorization": "Bearer tml_VOTRE_CLE" }
    }
  }
}

Transport HTTP. Avec `?names=en` à la fin de l’adresse, les outils sont listés sous leurs noms anglais, arguments compris ; sans lui, sous les noms français. Les appels acceptent les deux. Les règles de chaque réseau sont servies dans la langue du propriétaire de la clé.

Un post créé par une IA ne part pas tout seul. Il naît brouillon et suit le même circuit que les autres : il faut le soumettre, et quelqu’un doit le valider. C’est la raison d’être du circuit : une IA qui publie sans relecture est exactement ce qu’on ne veut pas vendre.

Ajouter un compte depuis une IA

`preparer_connexion` permet à une IA d’ajouter un compte, dans deux limites qu’elle ne peut pas lever : elle ne donne jamais le consentement, et elle ne paie jamais. Pour les réseaux qui autorisent sur leur propre écran, elle obtient un lien qui sert une fois, pendant 24 heures. L’IA le remet au titulaire du compte, qui n’a pas besoin de compte Timalio : la page dit quelle organisation demande, puis l’envoie sur l’écran d’autorisation du réseau lui-même. Pour un salon Discord, l’IA donne son webhook, et le salon est connecté après les mêmes vérifications que la page Comptes. L’outil dit quels réseaux il prend en charge ; les autres se connectent depuis la page Comptes.

Un compte que l’abonnement ne couvre pas encore n’est pas refusé : il va au panier, inactif, pendant sept jours. `etat_panier` donne à l’IA les comptes en attente, le montant mensuel qu’ils ajoutent et un lien vers la page Comptes, où un administrateur, connecté, relit le montant et paie. Rien n’est prélevé avant ce clic. Une organisation exemptée n’a pas de panier.

Seule une clé ADMIN crée un lien, et seulement tant que son propriétaire est administrateur. Au plus 10 liens par organisation sur 24 heures. Chaque lien apparaît sur la page Comptes, avec ce qu’il est devenu, et se révoque là ou par `annuler_connexion` ; révoquer la clé éteint aussi ses liens. N’envoyez un lien qu’au titulaire du compte : le premier qui l’ouvre peut y connecter son propre compte.