TeleSearch API

Eine JSON-API und ein MCP-Server für Agenturen: Füge deine Creator hinzu und bearbeite sie und hol dir ihre Impressions, Klicks und CTR in dein eigenes CRM, oder lass Claude das erledigen.

Für wen es ist

Die API und der MCP-Server sind für Agenturen (Konten mit der Agenturrolle). Sie wirken auf die Creator deiner Agentur, sonst auf nichts. Creator-Konten bekommen keine API-Schlüssel. Wenn dein Konto keine Agentur mehr ist, funktionieren deine Schlüssel nicht mehr.

Einen Schlüssel holen

Melde dich mit deinem Agenturkonto an, öffne Dashboard, API, gib deinem Schlüssel einen Namen und erstelle ihn. Der Schlüssel wird nur einmal angezeigt, also bewahre ihn sicher auf. Du kannst bis zu 5 aktive Schlüssel haben und jeden jederzeit widerrufen.

Sende den Schlüssel im Authorization-Header jeder Anfrage. Schlüssel sehen aus wie ts_live_ gefolgt von 40 Zeichen.

GET /api/v1/creators

Die Creator deiner Agentur.

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

Das vollständige Profil eines Creators. Gibt 404 zurück, wenn der Creator nicht dir gehört.

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 ist true, wenn jedes Telegram-Konto des Creators verifiziert ist. Jedes nicht verifizierte Konto trägt deinen verify_code (siehe den Verify-Endpunkt unten).

POST /api/v1/creators

Fügt einen Creator zu deiner Agentur hinzu. Es laufen dieselben Prüfungen wie beim Formular auf der Website: nur persönliche Telegram-Konten (keine Kanäle, Gruppen oder Bots), kein Telegram-Konto, das schon gelistet ist, nur Erwachsene. Der Eintrag geht sofort live, außer die automatische Altersprüfung hat einen Zweifel: Dann wird er als pending zur menschlichen Prüfung zurückgehalten und ein notice weist darauf hin. JSON-Body, bis zu 20 KB:

accounts (erforderlich): 1 bis 5 Objekte mit link (t.me-Link oder @username), optional market_country, market_language und primary.
age (erforderlich): ganze Zahl, 18 bis 99.
adult_confirmed (erforderlich): muss true sein. Du bestätigst, dass der Creator erwachsen ist und das Konto von Erwachsenen betrieben wird.
Optional: display_name (max. 80, Standard ist der Telegram-Name), bio (max. 2000), origin_country (ISO-Code), origin_city, languages (Codes wie en), categories (einer von: 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 (Objekt, zum Beispiel {"hair":"blonde"}). links (Handles auf anderen Plattformen) werden bei der Erstellung nicht akzeptiert: Ein neuer Creator ist nicht verifiziert, siehe unten.

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

Gibt 201 mit derselben Struktur wie GET /creators/:slug zurück (und ein notice, wenn der Eintrag zur Prüfung zurückgehalten wird). Unbekannte Felder werden abgelehnt.

PATCH /api/v1/creators/:slug

Bearbeitet die Profilfelder, die du sendest: display_name, bio, age, origin_country, origin_city, languages, categories, attrs, links. Felder, die du weglässt, bleiben unverändert; null leert bio, origin_country und origin_city. languages und categories ersetzen die ganze Liste. attrs und links werden zusammengeführt: Setze einen Schlüssel auf null, um ihn zu entfernen. Links brauchen ein verifiziertes Konto: Solange irgendein Telegram-Konto des Creators nicht verifiziert ist, kannst du Links entfernen, aber nicht hinzufügen oder ändern (403). Telegram-Konten lassen sich nicht über die API ändern. Ein Live-Eintrag bleibt live, außer die automatische Altersprüfung hat nach der Bearbeitung einen Zweifel: Dann geht er zurück in die Prüfung, wie im 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

Gibt 200 mit dem aktualisierten Creator zurück.

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

Belegt, dass dir die Telegram-Konten eines Creators gehören, ähnlich dem Bio-Check im Stil von TGStat. Einträge gehen sofort live, sind aber nicht verifiziert, bis es belegt ist. Nicht verifizierte Creator funktionieren wie gewohnt, nur dass Links zu anderen Plattformen (OnlyFans, Fansly...) nicht gesetzt werden können und im öffentlichen Profil nicht angezeigt werden. Verifizierte Creator bekommen ein Verified-Abzeichen.

Lies verify_code (zum Beispiel TS-K7M2QX) aus GET /creators/:slug, pro nicht verifiziertem Konto.
Füge ihn irgendwo in die Bio dieses Telegram-Kontos ein (Groß-/Kleinschreibung egal, er muss ein eigenes Wort sein).
Ruf diesen Endpunkt auf. TeleSearch liest das öffentliche Telegram-Profil und prüft den Code. Du kannst den Code danach aus der Bio entfernen.

Optionaler JSON-Body: username (ein Konto prüfen; Standard sind alle nicht verifizierten Konten, bis zu 5) und regenerate: true (einen neuen Code ausstellen statt zu prüfen). Codes laufen nach 7 Tagen ab. Begrenzt auf 10 Versuche pro Stunde und Nutzer (geteilt mit dem Dashboard).

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

200, wenn verifiziert (mit dem aktualisierten Creator in data). 422, wenn der Code noch nicht in der Bio steht (die Meldung wiederholt deinen Code), 503, wenn Telegram nicht erreichbar war, 429, wenn deine Versuche aufgebraucht sind.

DELETE /api/v1/creators/:slug

Entfernt den Eintrag, wie Entfernen im Dashboard. Es gibt die Telegram-Usernamen frei. Zweimaliges Aufrufen ist unbedenklich.

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, Klicks und CTR pro Creator sowie Summen. days ist 7, 30 oder 90 (Standard 7). CTR ist Klicks geteilt durch Impressions, oder null, wenn es keine Impressions gibt.

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

Eine Tagesreihe (UTC-Tage, älteste zuerst) für einen Creator. Gibt 404 zurück, wenn der Creator nicht dir gehört.

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, Warteschlange und Posting-Zeitplan

Poste kurze vertikale Reels für einen Creator, wie auf der Seite „Für dich“ (Reels) im Dashboard. MP4 oder WebM, vertikal, maximal 60 Sekunden und 60 MB. Jedes Reel bekommt eine schnelle Prüfung. Hat der Creator einen Posting-Zeitplan, warten freigegebene Reels in einer Warteschlange (älteste zuerst) und zu jedem geplanten Zeitpunkt geht eines live; ohne Zeitplan gehen sie live, sobald sie freigegeben sind.

Status: in_review, queued (freigegeben, wartet auf seinen Slot, mit planned_at), live, rejected. Uploads haben ihr eigenes Kontingent: 300 Reels pro Stunde pro Schlüssel und pro Agentur.

POST /api/v1/reels

Schritt 1. JSON-Body: creator (Slug), type (video/mp4 oder video/webm), size (Bytes), optional caption (max. 150 Zeichen). Gibt 201 mit der Reel-id und einer signierten upload_url zurück, 2 Stunden gültig.

Die Datei per PUT senden, dann POST /api/v1/reels/:id/confirm

Schritt 2. Sende die Video-Bytes per PUT an upload_url (ohne API-Schlüssel bei dieser Anfrage) und bestätige dann. TeleSearch prüft die Datei und legt das Reel in die Prüfung. Optionaler JSON-Body: caption (ersetzt die aus Schritt 1) und duration_s. Zweimaliges Bestätigen ist unbedenklich. Unbestätigte Uploads laufen nach einem Tag ab.

# 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

Die Reels des Creators in Posting-Reihenfolge, mit Status, Aufrufen und Likes, plus der Zusammenfassung der Warteschlange.

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

Jetzt posten: Ein Reel in der Warteschlange geht sofort live; ein Reel, das noch in der Prüfung ist, geht live, sobald es freigegeben ist.

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

Der Posting-Zeitplan: posts_per_day (1, 2 oder 3), times (24-Stunden-Ortszeiten, so viele wie Posts pro Tag) und timezone (IANA-Name). schedule ist null, wenn keiner gesetzt ist. Ein verpasster Slot (oder einer mit leerer Warteschlange) wird übersprungen, nie nachgeholt. DELETE entfernt den Zeitplan: Reels in der Warteschlange gehen sofort live und freigegebene Reels gehen ab dann sofort live.

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" } }

Fehler und Limits

400 ungültiger Body. Die Antwort listet jedes Problem nach Feld auf: {"error":"Validation failed.","fields":{"age":"TeleSearch only lists adults: the minimum age is 18."}}
401 fehlender, ungültiger oder widerrufener Schlüssel.
403 der Schlüsselinhaber ist (nicht mehr) eine Agentur, oder du hast versucht, Links bei einem nicht verifizierten Creator zu setzen.
404 Creator nicht gefunden oder nicht einer von dir.
409 das Telegram-Konto ist schon auf TeleSearch (wenn es deins ist, beanspruche es im Dashboard), oder der Eintrag wurde abgelehnt oder entfernt.
413 Body größer als 20 KB. 422 ein Telegram-Link, der nicht genutzt werden kann (kein persönliches Konto, nicht gefunden). 503 Telegram war nicht erreichbar, versuch es später erneut.
429 zu viele Anfragen: 600 Anfragen pro Stunde pro Schlüssel und pro Agentur (mehrere Schlüssel teilen sich das Kontingent der Agentur), davon dürfen 60 Schreibzugriffe (POST, PATCH, DELETE) und 20 neue Creator sein.

Antworten werden nie gecacht und der Browserzugriff (CORS) ist nicht aktiviert: Ruf die API von deinem Server auf, nicht von einer Webseite.

MCP-Server

Verbinde Claude, Cursor oder einen beliebigen MCP-Client mit deiner Agentur, verwalte Creator und lies Statistiken in einfachem Deutsch. Es ist ein Remote-Server (Streamable HTTP, zustandslos), der dieselben API-Schlüssel, dieselben Prüfungen und dieselben Limits nutzt wie die API.

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

Tools: 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.

Sende pro Anfrage eine JSON-RPC-Nachricht: Batches werden nicht unterstützt und jede Anfrage zählt als eine Einheit deines Kontingents.

Claude (claude.ai und Claude Desktop)

Öffne Einstellungen, Connectors, Benutzerdefinierten Connector hinzufügen. Gib https://telesearch.ai/api/mcp als URL ein und füge den Header Authorization: Bearer ts_live_YOUR_KEY hinzu, wo dein Tarif oder Client benutzerdefinierte Header erlaubt. Wenn dein Client nur OAuth-Connectors unterstützt, nutze Claude Code oder Cursor unten, oder Claude Desktop mit einer lokalen Bridge wie 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

Füge das zu ~/.cursor/mcp.json hinzu (oder .cursor/mcp.json in einem Projekt):

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

Probier dann: „Liste meine TeleSearch-Creator auf und zeig die Klicks des letzten Monats für jeden.“ Behandle den Schlüssel wie ein Passwort: Wer ihn hat, kann deine Creator bearbeiten.