Endpoints

Conventions

Tous les chemins sont relatifs à https://teddit.io/api. Envoyez la clé comme décrit sous Authentification.

• Accès est le rôle de clé le plus bas qui peut appeler l’endpoint : viewer (une clé Lecture), member (Lecture + édition) ou admin (Lecture + analyse). Un rôle supérieur peut toujours l’appeler aussi.
• :orgId est l’identifiant de l’espace de travail donné par GET /whoami. :id est un identifiant de site donné par GET /orgs/:orgId/projects.
• Paramètres de période. Les endpoints de rapport prennent period (day, week, month ou quarter ; par défaut week) et start (n’importe quelle date dans la période voulue, YYYY-MM-DD ; par défaut la dernière période). Leurs réponses répètent period et start et listent chaque période qui a des données dans periods.
• Dans les réponses, « cité » est mentioned, « lié » est ownCited, votre place est brandRank, visibility est le score de visibilité, et un assistant est un provider avec la clé openai, anthropic, perplexity, gemini, google_aio ou google_ai_mode.

Les outils MCP renvoient les mêmes données, donc la description d’un outil décrit aussi l’endpoint correspondant.

Espace de travail

Ajouter un site prend name et url (tous deux obligatoires), et en option industry, brandTerms (autres noms, jusqu’à 50), competitors (objets avec name et domain, jusqu’à 50), language (par défaut English) et location (par défaut United States).

Inviter prend email et role (viewer, member ou admin ; par défaut member). Changer un rôle prend role. Ce qu’un admin peut et ne peut pas faire aux autres membres est sur la page Rôles.

Non disponible aux clés : tout ce qui est sous /auth et /account, créer, supprimer et quitter des espaces de travail, renommer un espace de travail (PATCH /orgs/:orgId, Owner seulement), recharger et les factures (Owner seulement) et gérer les clés (/orgs/:orgId/tokens).

Sites

Changer les réglages prend n’importe lequel de ces champs :

• name, brandTerms : le nom de marque et ses autres noms. Changer l’un ou l’autre relit toutes les réponses stockées ; la réponse porte alors un résumé reanalysis.
• industry, language, location (le pays).
• scanFrequencyDays (1 à 365) : l’intervalle entre les analyses planifiées.
• monthlyCapUsd : le plafond mensuel du site en dollars américains. null ou 0 le retire.
• scanSettings : les réglages d’analyse enregistrés, remplacés en bloc. Un objet avec providers (clés d’assistant ; omis signifie tous les connectés), models (clé d’assistant vers modèle), category, budgetUsd (le maximum qu’une analyse peut coûter ; 0 signifie le double de son estimation) et skipAtCap (false laisse les analyses démarrer même quand le plafond mensuel est dépensé).

Calendrier prend enabled (true ou false). Activer le calendrier programme la première analyse pour la nuit suivante (UTC) ; les réponses d’une analyse planifiée arrivent en quelques heures.

Supprimer un site, avec ses prompts, ses analyses et ses réponses, est réservé à un Owner connecté et n’est pas disponible aux clés.

Personas d’acheteurs

GET /projects/:id/personas liste les personas d’un site avec le nombre de prompts que chacun pose ; POST (member) en ajoute un avec name (jusqu’à 80 caractères) et context (jusqu’à 600) : qui pose la question, avec ses mots. PATCH /projects/:id/personas/:personaId change l’un ou l’autre ; DELETE en retire un, et ses prompts sont posés nus à partir de l’analyse suivante. Les prompts prennent personaId à la création, à la modification et à la modification en masse (null l’efface). Chaque réponse conserve les mots avec lesquels elle a été posée comme context.

Rapports

Tous sont en GET, exigent viewer, et prennent les paramètres de période.

curl "https://teddit.io/api/projects/12/report?period=month&start=2026-09-15" \
  -H "Authorization: Bearer tdt_…"

Comment les chiffres de ces réponses sont calculés : Indicateurs et statuts.

Prompts et catégories

La liste et l’export prennent les mêmes paramètres de requête : q (recherche de texte), category, status (draft, active, paused), intent, verdict (named, lost, cited, missing, failed), competitor (le nom d’un concurrent suivi), stability (held, volatile, lost) et scanned (yes, never). La liste prend aussi sort (created, text, category, rank, scanned), dir (asc, desc), page, perPage (5 à 200, par défaut 20) et les paramètres de période, qui définissent ce que représente une case d’historique.

Ajouter prend text (3 à 500 caractères, obligatoire), category ou categories (une liste de jusqu’à 8), intent (par défaut informational), funnel (par défaut awareness) et status (par défaut active). Un texte déjà suivi répond 409. Modifier prend les mêmes champs, tous optionnels ; categories remplace toute la liste.

En masse prend ids (1 à 5000) et status, category ou delete: true. Supprimer un prompt supprime ses réponses.

Importer prend contents (le texte du fichier, jusqu’à 2 000 000 caractères), status (par défaut draft) et dryRun. Il renvoie rows, created, updated, skipped et categories. Le format du fichier est sur la page Importer des prompts.

Une réponse prend engine (une clé d’assistant ; par défaut le premier assistant qui a répondu) ou r (l’identifiant d’une réponse passée, pris dans les results du prompt).

Fusionner des catégories prend names (les catégories à regrouper) et into (le nom qu’elles deviennent). Un seul nom est un renommage, plusieurs sont une fusion, et un into vide retire les catégories de leurs prompts.

Concurrents et pages

Suivre prend name (obligatoire), domain, aliases (autres noms, jusqu’à 30), color et logo. Changer prend les mêmes champs, tous optionnels : seul ce que vous envoyez change, aliases remplace toute la liste, et domain: null retire le domaine. Les trois endpoints de concurrents relisent les réponses stockées quand les noms changent et renvoient le résultat comme reanalysis.

Pages prend q, section (la première partie du chemin), shown (yes ou no), page et perPage (5 à 200, par défaut 50).

Analyses

Estimer et lancer prennent le même corps. Chaque champ est optionnel :

• providers : des clés d’assistant. Vide signifie chaque assistant connecté.
• promptIds : un ensemble choisi de prompts. Vide signifie chaque prompt actif. Les prompts qui ne sont pas actifs sont ignorés.
• category : analyser une catégorie.
• sample : analyser ce nombre de prompts, tirés au hasard.
• models : clé d’assistant vers modèle, parmi les options de scan-options. chatgpt-app et gemini-app (rapide : réponse immédiate) et chatgpt-app-queue et gemini-app-queue (lent et moins cher : quelques minutes) prennent la réponse telle que l’application l’affiche.
• saved : true prend les assistants, les modèles et la catégorie des réglages d’analyse enregistrés du site plutôt que de cette requête. Au lancement, il prend aussi la limite par analyse enregistrée.
• Lancement seulement : budgetUsd (arrêter dès que l’analyse a coûté ce montant ; omis, le double de son estimation) et label.

Estimer renvoie prompts, answers, cost et formatted. Lancer renvoie l’analyse, répond 402 quand le solde ne couvre pas l’analyse, et 400 avec la raison pour tout le reste qui l’empêche de démarrer. Les raisons, et comment le coût est compté, sont sur la page Solde et limites de dépenses.

Une analyse prend tab (all, notNamed, competitorsOnly, errors), engine (une clé d’assistant) et page. Les statuts d’analyse sont queued, running, cancelling, cancelled, done et failed.

Un exemple complet

Trouver le site, ajouter un prompt, chiffrer une analyse d’une catégorie, la lancer et lire le résultat. Lancer l’analyse exige une clé Lecture + analyse.

KEY="tdt_…"
API="https://teddit.io/api"

# 1. Which workspace is this key for?
curl "$API/whoami" -H "Authorization: Bearer $KEY"
#    → "org": { "id": 3, … }

# 2. The sites of the workspace
curl "$API/orgs/3/projects" -H "Authorization: Bearer $KEY"
#    → "projects": [{ "id": 12, "domain": "brightloop.example", … }]

# 3. Add a prompt
curl -X POST "$API/projects/12/prompts" \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"text": "What does email automation cost for 10,000 contacts?", "category": "pricing", "intent": "commercial"}'

# 4. What would a scan of that category cost?
curl -X POST "$API/projects/12/scans/estimate" \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"category": "pricing"}'
#    → { "prompts": …, "answers": …, "cost": …, "formatted": "$…" }

# 5. Run it, and stop at 2 dollars
curl -X POST "$API/projects/12/scans" \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"category": "pricing", "budgetUsd": 2}'

# 6. Follow it until "run" is null
curl "$API/projects/12/scans/live" -H "Authorization: Bearer $KEY"

# 7. Read this week's report
curl "$API/projects/12/report" -H "Authorization: Bearer $KEY"