TeleSearch
Commence gratuitement

API TeleSearch

Une API JSON et un serveur MCP pour les agences : ajoute et modifie tes créatrices, et récupère leurs impressions, clics et CTR dans ton propre CRM, ou demande à Claude de le faire.

Pour qui

L'API et le serveur MCP sont réservés aux agences (comptes avec le rôle agence). Ils agissent sur les créatrices de ton agence, rien d'autre. Les comptes de créatrices n'ont pas de clés API. Si ton compte cesse d'être une agence, tes clés cessent de fonctionner.

Obtenir une clé

Connecte-toi avec ton compte agence, ouvre Dashboard, API, donne un nom à ta clé et crée-la. La clé n'est affichée qu'une seule fois, donc range-la en lieu sûr. Tu peux avoir jusqu'à 5 clés actives et en révoquer n'importe laquelle à tout moment.

Envoie la clé dans l'en-tête Authorization de chaque requête. Les clés ressemblent à ts_live_ suivi de 40 caractères.

GET /api/v1/creators

Les créatrices de ton agence.

curl -H "Authorization: Bearer ts_live_YOUR_KEY" \
  https://telesearch.ai/api/v1/creators
{
  "data": [
    {
      "id": "0b1c2d3e-0000-0000-0000-000000000000",
      "slug": "jane",
      "name": "Jane",
      "status": "approved",
      "verified": false,
      "telegram_usernames": ["jane_official"]
    }
  ]
}

GET /api/v1/creators/:slug

Le profil complet d'une créatrice. Renvoie 404 si la créatrice n'est pas à toi.

curl -H "Authorization: Bearer ts_live_YOUR_KEY" \
  https://telesearch.ai/api/v1/creators/jane
{
  "data": {
    "id": "0b1c2d3e-0000-0000-0000-000000000000",
    "slug": "jane",
    "url": "https://telesearch.ai/m/jane",
    "name": "Jane",
    "bio": "Hi, I am Jane.",
    "age": 26,
    "origin_country": "FR",
    "origin_city": "Paris",
    "languages": ["en", "fr"],
    "categories": ["Amateur"],
    "attrs": { "hair": "brunette" },
    "links": {},
    "verified": false,
    "links_unlocked": false,
    "status": "approved",
    "created_at": "2026-10-01T09:30:00.000Z",
    "telegram_accounts": [
      {
        "username": "jane_official", "primary": true, "market_country": "US", "market_language": "en",
        "verified": false, "verify_code": "TS-K7M2QX", "verify_code_expires_at": "2026-10-08T09:30:00.000Z", "verify_code_expired": false
      }
    ]
  }
}

verified vaut true quand tous les comptes Telegram de la créatrice sont vérifiés. Chaque compte non vérifié porte ton verify_code (voir l'endpoint verify plus bas).

POST /api/v1/creators

Ajoute une créatrice à ton agence. Les vérifications sont les mêmes que sur le formulaire du site : uniquement des comptes Telegram perso (pas de canaux, de groupes ni de bots), aucun compte Telegram déjà listé, adultes uniquement. Le profil est mis en ligne tout de suite, sauf si la vérification automatique de l'âge a un doute : il est alors mis en attente en pending pour une revue humaine et un notice l'indique. Corps JSON, jusqu'à 20 Ko :

  • accounts (obligatoire) : 1 à 5 objets avec link (lien t.me ou @username), et en option market_country, market_language et primary.
  • age (obligatoire) : nombre entier, de 18 à 99.
  • adult_confirmed (obligatoire) : doit valoir true. Tu confirmes que la créatrice est majeure et que le compte est géré par des adultes.
  • Facultatifs : display_name (80 max, par défaut le nom Telegram), bio (2000 max), origin_country (code ISO), origin_city, languages (codes comme en), categories (une parmi : Amateur, Cosplay, Fitness, Feet, Couples, Trans, Milf, Teen 18+, Asian, Latina, Ebony, Blonde, Brunette, Redhead, Tattoo, Petite, Curvy, Busty, Chubby, BBW, Big Ass, Mature, Goth, E-girl, Gamer, Lesbian, Arab, Indian, BDSM, Femdom, Roleplay, Girlfriend Experience, ASMR, Cam, Custom Videos, Dirty Talk, Homemade, Solo, Bikini, High Heels, Latex, Lingerie, Stockings, Leather, Boots, Bondage, Dominatrix, Dominant, Submissive, Fetish, Nurse, Teacher, Secretary, Maid, Anime, Geek, Nudist, Hairy, Muscular, Alt), attrs (objet, par exemple {"hair":"blonde"}). Les links (pseudos sur d'autres plateformes) ne sont pas acceptés à la création : une nouvelle créatrice n'est pas vérifiée, voir plus bas.
curl -X POST -H "Authorization: Bearer ts_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"accounts":[{"link":"@jane_official","market_country":"US","market_language":"en"}],"age":26,"adult_confirmed":true,"display_name":"Jane","languages":["en"]}' \
  https://telesearch.ai/api/v1/creators

Renvoie 201 avec la même structure que GET /creators/:slug (et un notice quand le profil est en attente de revue). Les champs inconnus sont rejetés.

PATCH /api/v1/creators/:slug

Modifie les champs de profil que tu envoies : display_name, bio, age, origin_country, origin_city, languages, categories, attrs, links. Les champs omis restent inchangés ; null efface bio, origin_country et origin_city. languages et categories remplacent toute la liste. attrs et links sont fusionnés : mets une clé à null pour la supprimer. Les liens nécessitent un compte vérifié : tant qu'un compte Telegram de la créatrice n'est pas vérifié, tu peux supprimer des liens mais pas en ajouter ni en modifier (403). Les comptes Telegram ne peuvent pas être modifiés via l'API. Un profil en ligne reste en ligne, sauf si la vérification automatique de l'âge a un doute après la modification : il repasse alors en revue, comme dans le dashboard.

curl -X PATCH -H "Authorization: Bearer ts_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"bio":"New bio","attrs":{"hair":"blonde","eyes":null}}' \
  https://telesearch.ai/api/v1/creators/jane

Renvoie 200 avec la créatrice mise à jour.

POST /api/v1/creators/:slug/verify

Prouve que tu possèdes les comptes Telegram d'une créatrice, comme la vérification de bio façon TGStat. Les profils sont mis en ligne tout de suite, mais ils sont non vérifiés tant que ce n'est pas prouvé. Les créatrices non vérifiées fonctionnent normalement, sauf que les liens vers d'autres plateformes (OnlyFans, Fansly...) ne peuvent pas être définis et ne sont pas affichés sur le profil public. Les créatrices vérifiées reçoivent un badge Vérifié.

  1. Lis verify_code (par exemple TS-K7M2QX) depuis GET /creators/:slug, pour chaque compte non vérifié.
  2. Colle-le n'importe où dans la bio de ce compte Telegram (la casse n'a pas d'importance, ce doit être un mot séparé).
  3. Appelle cet endpoint. TeleSearch lit le profil Telegram public et vérifie le code. Tu peux ensuite retirer le code de la bio.

Corps JSON facultatif : username (vérifier un seul compte ; par défaut chaque compte non vérifié, jusqu'à 5) et regenerate: true (émettre un nouveau code au lieu de vérifier). Les codes expirent après 7 jours. Limité à 10 tentatives par heure et par utilisateur (partagées avec le dashboard).

curl -X POST -H "Authorization: Bearer ts_live_YOUR_KEY" \
  https://telesearch.ai/api/v1/creators/jane/verify

200 quand c'est vérifié (avec la créatrice mise à jour dans data). 422 quand le code n'est pas encore dans la bio (le message rappelle ton code), 503 quand Telegram n'a pas pu être joint, 429 quand tu n'as plus de tentatives.

DELETE /api/v1/creators/:slug

Supprime le profil, comme Supprimer dans le dashboard. Cela libère les noms d'utilisateur Telegram. L'appeler deux fois ne pose aucun problème.

curl -X DELETE -H "Authorization: Bearer ts_live_YOUR_KEY" \
  https://telesearch.ai/api/v1/creators/jane
{ "data": { "slug": "jane", "removed": true } }

GET /api/v1/stats?days=7

Impressions, clics et CTR par créatrice, plus les totaux. days vaut 7, 30 ou 90 (7 par défaut). Le CTR correspond aux clics divisés par les impressions, ou null s'il n'y a aucune impression.

curl -H "Authorization: Bearer ts_live_YOUR_KEY" \
  "https://telesearch.ai/api/v1/stats?days=30"
{
  "days": 30,
  "creators": [
    { "id": "0b1c2d3e-0000-0000-0000-000000000000", "slug": "jane", "name": "Jane", "impressions": 12840, "clicks": 391, "ctr": 0.0305 }
  ],
  "totals": { "impressions": 12840, "clicks": 391, "ctr": 0.0305 }
}

GET /api/v1/creators/:slug/stats?days=7

Une série journalière (jours UTC, du plus ancien au plus récent) pour une créatrice. Renvoie 404 si la créatrice n'est pas à toi.

curl -H "Authorization: Bearer ts_live_YOUR_KEY" \
  "https://telesearch.ai/api/v1/creators/jane/stats?days=7"
{
  "id": "0b1c2d3e-0000-0000-0000-000000000000",
  "slug": "jane",
  "name": "Jane",
  "days": 7,
  "series": [
    { "date": "2026-10-01", "impressions": 1820, "clicks": 52, "ctr": 0.0286 }
  ]
}

Reels : upload, file d'attente et planning de publication

Publie des reels courts et verticaux pour une créatrice, comme sur la page Pour toi (Reels) du dashboard. MP4 ou WebM, vertical, 60 secondes et 60 Mo max. Chaque reel passe une revue rapide. Quand la créatrice a un planning de publication, les reels approuvés attendent dans une file (du plus ancien au plus récent) et un seul est mis en ligne à chaque horaire prévu ; sans planning, ils sont mis en ligne dès leur approbation.

Statuts : in_review, queued (approuvé, en attente de son créneau, avec planned_at), live, rejected. Les uploads ont leur propre quota : 300 reels par heure, par clé et par agence.

POST /api/v1/reels

Étape 1. Corps JSON : creator (slug), type (video/mp4 ou video/webm), size (octets), et en option caption (150 caractères max). Renvoie 201 avec l'identifiant id du reel et une upload_url signée, valable 2 heures.

Envoie le fichier en PUT, puis POST /api/v1/reels/:id/confirm

Étape 2. Envoie les octets de la vidéo en PUT vers upload_url (sans clé API sur cette requête), puis confirme. TeleSearch vérifie le fichier et ajoute le reel en revue. Corps JSON facultatif : caption (remplace celle de l'étape 1) et duration_s. Confirmer deux fois ne pose aucun problème. Les uploads non confirmés expirent après un jour.

# 1. Announce the reel
curl -X POST -H "Authorization: Bearer ts_live_YOUR_KEY" -H "Content-Type: application/json" \
  -d '{"creator":"jane","type":"video/mp4","size":'$(wc -c < reel.mp4)',"caption":"Sunday mood"}' \
  https://telesearch.ai/api/v1/reels
# -> { "data": { "id": "6f1c...", "upload_url": "https://...", "upload_method": "PUT", "expires_in": 7200 } }

# 2. Upload the file
curl -X PUT -H "Content-Type: video/mp4" --data-binary @reel.mp4 "UPLOAD_URL"

# 3. Confirm
curl -X POST -H "Authorization: Bearer ts_live_YOUR_KEY" https://telesearch.ai/api/v1/reels/6f1c.../confirm

GET /api/v1/reels?creator=:slug

Les reels de la créatrice dans l'ordre de publication, avec statut, vues et likes, plus le résumé de la file.

curl -H "Authorization: Bearer ts_live_YOUR_KEY" \
  "https://telesearch.ai/api/v1/reels?creator=jane"
{
  "creator": { "id": "0b1c2d3e-0000-0000-0000-000000000000", "slug": "jane" },
  "queue": { "queued": 12, "in_review": 3, "next_post_at": "2026-10-08T16:00:00.000Z" },
  "data": [
    { "id": "6f1c...", "status": "queued", "caption": "Sunday mood", "views": 0, "likes": 0, "duration_s": 14.2, "source": "upload",
      "created_at": "2026-10-07T10:12:00.000Z", "published_at": null, "planned_at": "2026-10-08T16:00:00.000Z" }
  ]
}

POST /api/v1/reels/:id/publish

Publier maintenant : un reel en file est mis en ligne immédiatement ; un reel encore en revue est mis en ligne dès son approbation.

GET, PUT and DELETE /api/v1/creators/:slug/schedule

Le planning de publication : posts_per_day (1, 2 ou 3), times (horaires locaux au format 24 h, autant que de publications par jour) et timezone (nom IANA). schedule vaut null quand aucun n'est défini. Un créneau manqué (ou qui trouve la file vide) est ignoré, jamais rattrapé. DELETE supprime le planning : les reels en file sont mis en ligne immédiatement, et les reels approuvés sont ensuite mis en ligne dès leur approbation.

curl -X PUT -H "Authorization: Bearer ts_live_YOUR_KEY" -H "Content-Type: application/json" \
  -d '{"posts_per_day":2,"times":["09:00","19:30"],"timezone":"Europe/Paris"}' \
  https://telesearch.ai/api/v1/creators/jane/schedule
{ "data": { "creator": "jane", "schedule": { "posts_per_day": 2, "times": ["09:00", "19:30"], "timezone": "Europe/Paris" },
  "queued": 12, "in_review": 3, "next_post_at": "2026-10-07T17:30:00.000Z" } }

Erreurs et limites

  • 400 corps invalide. La réponse liste chaque problème par champ : {"error":"Validation failed.","fields":{"age":"TeleSearch only lists adults: the minimum age is 18."}}
  • 401 clé manquante, invalide ou révoquée.
  • 403 le propriétaire de la clé n'est plus une agence, ou tu as essayé de définir des liens sur une créatrice non vérifiée.
  • 404 créatrice introuvable, ou qui n'est pas à toi.
  • 409 le compte Telegram est déjà sur TeleSearch (s'il est à toi, réclame-le depuis le dashboard), ou le profil a été rejeté ou supprimé.
  • 413 corps de plus de 20 Ko. 422 lien Telegram inutilisable (pas un compte perso, introuvable). 503 Telegram n'a pas pu être joint, réessaie plus tard.
  • 429 trop de requêtes : 600 requêtes par heure, par clé et par agence (plusieurs clés se partagent le quota de l'agence), dont 60 peuvent être des écritures (POST, PATCH, DELETE) et 20 de nouvelles créatrices.

Les réponses ne sont jamais mises en cache, et l'accès depuis le navigateur (CORS) n'est pas activé : appelle l'API depuis ton serveur, pas depuis une page web.

Serveur MCP

Connecte Claude, Cursor ou n'importe quel client MCP à ton agence, et gère tes créatrices et lis tes stats en langage courant. C'est un serveur distant (Streamable HTTP, sans état) qui utilise les mêmes clés API, les mêmes vérifications et les mêmes limites que l'API.

URL : https://telesearch.ai/api/mcp

Outils : list_creators, get_creator, get_stats, get_daily_stats, create_creator, update_creator, verify_creator, delete_creator, list_reels, create_reel_upload, confirm_reel, publish_reel_now, get_reel_schedule, set_reel_schedule.

Envoie un message JSON-RPC par requête : les lots ne sont pas pris en charge, et chaque requête compte pour une unité de ton quota.

Claude (claude.ai et Claude Desktop)

Ouvre Settings, Connectors, Add custom connector. Saisis https://telesearch.ai/api/mcp comme URL et ajoute l'en-tête Authorization: Bearer ts_live_YOUR_KEY là où ton forfait ou ton client te permet de définir des en-têtes personnalisés. Si ton client ne gère que les connecteurs OAuth, utilise Claude Code ou Cursor ci-dessous, ou Claude Desktop avec un pont local comme mcp-remote :

{
  "mcpServers": {
    "telesearch": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://telesearch.ai/api/mcp", "--header", "Authorization: Bearer ts_live_YOUR_KEY"]
    }
  }
}

Claude Code

claude mcp add --transport http telesearch https://telesearch.ai/api/mcp \
  --header "Authorization: Bearer ts_live_YOUR_KEY"

Cursor

Ajoute ceci à ~/.cursor/mcp.json (ou .cursor/mcp.json dans un projet) :

{
  "mcpServers": {
    "telesearch": {
      "url": "https://telesearch.ai/api/mcp",
      "headers": { "Authorization": "Bearer ts_live_YOUR_KEY" }
    }
  }
}

Puis essaie : « Liste mes créatrices TeleSearch et montre-moi les clics du mois dernier pour chacune. » Traite la clé comme un mot de passe : quiconque l'a peut modifier tes créatrices.