API REST

Authentification

L’API REST donne aux scripts et aux tableaux de bord les mêmes données que l’application. Un script y accède avec une clé API de l’espace de travail envoyée comme bearer token. Cette page couvre les clés, leurs niveaux d’accès et les erreurs que vous pouvez recevoir.

Adresse de base et format

https://teddit.io/api

Les requêtes et les réponses sont en JSON. Envoyez Content-Type: application/json avec chaque corps. Un corps de requête peut faire jusqu’à 4 Mo.
Les identifiants sont des nombres. L’API appelle un espace de travail une organisation (/orgs/:orgId) et un site un projet (/projects/:id).
Les heures sont en ISO 8601, en UTC. Les semaines et autres périodes sont données sous forme de date, YYYY-MM-DD.

La liste des adresses est sur la page Endpoints.

Clés API

Créez une clé dans l’application : icône d’engrenage → API & MCP → Créer une clé. N’importe quel rôle le peut ; la clé reçoit au plus l’accès du vôtre.

Une clé ressemble à tdt_ suivi de 40 lettres, chiffres, - et _.
Elle n’est affichée qu’une fois, à sa création. Teddit en stocke un hachage, pas la clé, donc une clé perdue ne peut pas être récupérée. Créez-en une nouvelle à la place.
Une clé appartient à un seul espace de travail et peut atteindre chaque site qu’il contient.
La liste des clés montre le nom de chaque clé, ses premiers caractères, son accès, qui l’a créée et sa dernière utilisation. « Dernière utilisation » est mis à jour au plus une fois toutes les cinq minutes.
Une clé n’expire pas. Révoquez-la avec l’icône de corbeille ; elle cesse de fonctionner à la requête suivante.

Les mêmes clés ouvrent le serveur MCP.

Envoyer la clé

Mettez la clé dans l’en-tête Authorization de chaque requête :

curl https://teddit.io/api/whoami \
  -H "Authorization: Bearer tdt_…"

GET /api/whoami est l’appel par lequel commencer. Il dit à quel espace de travail la clé appartient et ce qu’elle peut faire :

{
  "kind": "token",
  "tokenName": "Reporting script",
  "user": { "id": 7, "name": "Dana Whitfield", "email": "dana@brightloop.example" },
  "org": { "id": 3, "name": "Brightloop", "plan": "free" },
  "role": "viewer"
}

Utilisez org.id dans les adresses /orgs/:orgId/…. user est la personne qui a créé la clé : les actions effectuées avec la clé, comme lancer une analyse, sont enregistrées sous ce nom.

La clé est l’identifiant complet. Tenez-la à l’écart des pages web, des dépôts et des messages de chat, et donnez à chaque script sa propre clé, pour pouvoir en révoquer une sans arrêter les autres.

Niveaux d’accès des clés

Une clé a l’un de trois niveaux d’accès. Chacun est un rôle de l’espace de travail, et chacun inclut celui qui le précède.

Accès dans l’application	`role`	Peut appeler
Lecture	`viewer`	Tout ce qui lit : rapports, prompts, réponses, concurrents, pages, analyses, membres. Aussi l’estimation du coût d’une analyse.
Lecture + édition	`member`	En plus : créer, modifier et supprimer des prompts, des catégories et des concurrents ; importer ; changer les noms, la langue et le pays d’un site.
Lecture + analyse	`admin`	En plus : lancer et annuler des analyses, activer et désactiver le calendrier, changer le plafond mensuel et les réglages d’analyse, ajouter des sites, inviter et retirer des membres.

Il n’y a pas de clés avec le rôle Owner. Recharger, supprimer un site et renommer un espace de travail restent réservés à un Owner connecté.
Vous ne pouvez pas créer une clé avec plus d’accès que votre propre rôle ne vous en donne.
Une clé suit la personne qui l’a créée : abaissée avec son rôle, arrêtée quand elle quitte l’espace de travail.

Ce qu’une clé ne peut pas faire

Certaines actions exigent une personne connectée à l’application dans un navigateur. Appelées avec une clé, elles répondent 403 avec « This action needs a signed-in person, not an API token. »

Créer, lister et révoquer des clés API.
Changer votre nom, votre e-mail ou votre mot de passe, et supprimer votre compte.
Créer un espace de travail, en supprimer un, passer d’un espace à l’autre et en quitter un.
Accepter une invitation.

Une clé ne voit rien non plus en dehors de son espace de travail. Un identifiant de site ou d’espace qui appartient à quelqu’un d’autre répond 404, comme un identifiant qui n’existe pas.

Erreurs

Chaque erreur a le même corps : un message destiné à une personne dans error, et fields avec un message par champ quand le problème est dans l’entrée, sinon null.

HTTP/1.1 409 Conflict

{
  "error": "This prompt already exists in the project.",
  "fields": { "text": "Already tracked" }
}

Statut	Quand
400	La requête est bien formée mais refusée : une limite de l’espace de travail est atteinte, une analyse ne peut pas démarrer (une autre est en cours, aucun prompt actif, le solde ne la couvre pas, le plafond mensuel est dépensé), ou une adresse n’est pas un domaine. Le message dit laquelle.
401	Pas de clé, une clé mal formée, ou une clé révoquée. Le message est « Sign in to continue. »
403	Le niveau d’accès de la clé est trop bas pour l’action, ou l’action exige une personne connectée.
404	L’adresse ou l’identifiant n’existe pas, ou il appartient à un autre espace de travail.
409	Un doublon : un prompt avec le même texte, un concurrent ou une catégorie avec le même nom, une invitation pour quelqu’un qui est déjà membre.
422	Le corps ou la chaîne de requête n’a pas passé la validation. `fields` nomme chaque champ erroné.
429	Trop de requêtes vers une adresse qui a sa propre limite, comme la connexion, les invitations ou la relecture du sitemap. Attendez et réessayez.
500, 502	Quelque chose a échoué de notre côté, ou un assistant a échoué pendant le traitement de la requête.

Les appels réussis répondent 200 avec du JSON. Supprimer un site, un membre ou une invitation répond 204 sans corps.

Limites de débit et de l’espace de travail

La plupart des requêtes faites avec une clé n’ont pas de limite de débit. Quelques actions ont la leur : inviter des personnes, relire le sitemap et réécrire les requêtes. Les dépasser répond 429.
Les limites de l’espace de travail s’appliquent à l’API exactement comme dans l’application : sites, prompts par site, analyses par mois et membres. Un appel qui dépasserait une limite répond 400 avec la limite dans le message.
Les adresses de liste sont paginées. La liste des prompts prend page et perPage (5 à 200) ; en demander plus répond 422.

Précédent‹ Exemples de questions SuivantEndpoints ›