TeleSearch
Inizia gratis

API di TeleSearch

Un'API JSON e un server MCP per agenzie: aggiungi e modifica le tue creator e porta impression, clic e CTR nel tuo CRM, oppure chiedi a Claude di farlo.

Per chi è

L'API e il server MCP sono per le agenzie (account con ruolo agenzia). Agiscono sulle creator della tua agenzia, nient'altro. Gli account creator non ricevono chiavi API. Se il tuo account smette di essere un'agenzia, le tue chiavi smettono di funzionare.

Ottieni una chiave

Accedi con il tuo account agenzia, apri Dashboard, API, dai un nome alla chiave e creala. La chiave viene mostrata una sola volta, quindi conservala al sicuro. Puoi avere fino a 5 chiavi attive e revocarle quando vuoi.

Invia la chiave nell'header Authorization di ogni richiesta. Le chiavi hanno la forma ts_live_ seguita da 40 caratteri.

GET /api/v1/creators

Le creator della tua agenzia.

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

Il profilo completo di una creator. Restituisce 404 se la creator non è tua.

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 è true quando ogni account Telegram della creator è verificato. Ogni account non verificato riporta il tuo verify_code (vedi l'endpoint di verifica qui sotto).

POST /api/v1/creators

Aggiunge una creator alla tua agenzia. Esegue gli stessi controlli del modulo del sito: solo account Telegram personali (niente canali, gruppi o bot), nessun account Telegram già elencato, solo adulti. L'annuncio va online subito, a meno che il controllo automatico dell'età abbia un dubbio: in quel caso resta pending in attesa di revisione umana e un notice lo segnala. Body JSON, fino a 20 KB:

  • accounts (obbligatorio): da 1 a 5 oggetti con link (link t.me o @username), più market_country, market_language e primary facoltativi.
  • age (obbligatorio): numero intero, da 18 a 99.
  • adult_confirmed (obbligatorio): deve essere true. Confermi che la creator è maggiorenne e che l'account è gestito da adulti.
  • Facoltativi: display_name (max 80, di default il nome Telegram), bio (max 2000), origin_country (codice ISO), origin_city, languages (codici come en), categories (uno tra: 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 (oggetto, per esempio {"hair":"blonde"}). links (profili su altre piattaforme) non sono accettati alla creazione: una nuova creator non è verificata, vedi sotto.
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

Restituisce 201 con la stessa forma di GET /creators/:slug (e un notice quando l'annuncio è in attesa di revisione). I campi sconosciuti vengono rifiutati.

PATCH /api/v1/creators/:slug

Modifica i campi del profilo che invii: display_name, bio, age, origin_country, origin_city, languages, categories, attrs, links. I campi omessi restano invariati; null svuota bio, origin_country e origin_city. languages e categories sostituiscono l'intera lista. attrs e links vengono uniti: imposta una chiave a null per rimuoverla. I link richiedono un account verificato: finché un qualsiasi account Telegram della creator non è verificato puoi rimuovere i link ma non aggiungerli o cambiarli (403). Gli account Telegram non si possono cambiare tramite API. Un annuncio online resta online, a meno che il controllo automatico dell'età abbia un dubbio dopo la modifica: in quel caso torna in revisione, come nella 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

Restituisce 200 con la creator aggiornata.

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

Dimostra che possiedi gli account Telegram di una creator, con un controllo della bio in stile TGStat. Gli annunci vanno online subito, ma sono non verificati finché non lo dimostri. Le creator non verificate funzionano normalmente, tranne per il fatto che i link ad altre piattaforme (OnlyFans, Fansly...) non si possono impostare e non vengono mostrati nel profilo pubblico. Le creator verificate ricevono un badge Verificato.

  1. Leggi verify_code (per esempio TS-K7M2QX) da GET /creators/:slug, per ogni account non verificato.
  2. Incollalo in un punto qualsiasi della bio di quell'account Telegram (maiuscole e minuscole non contano, deve essere una parola separata).
  3. Chiama questo endpoint. TeleSearch legge il profilo Telegram pubblico e controlla il codice. Dopo puoi togliere il codice dalla bio.

Body JSON facoltativo: username (controlla un solo account; di default ogni account non verificato, fino a 5) e regenerate: true (emette un nuovo codice invece di controllare). I codici scadono dopo 7 giorni. Limite di 10 tentativi all'ora per utente (condiviso con la dashboard).

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

200 quando verificato (con la creator aggiornata in data). 422 quando il codice non è ancora nella bio (il messaggio ripete il tuo codice), 503 quando non è stato possibile raggiungere Telegram, 429 quando hai finito i tentativi.

DELETE /api/v1/creators/:slug

Rimuove l'annuncio, come Rimuovi nella dashboard. Libera gli username Telegram. Chiamarlo due volte è sicuro.

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

Impression, clic e CTR per creator, più i totali. days è 7, 30 o 90 (default 7). Il CTR è clic diviso impression, oppure null quando non ci sono 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

Una serie giornaliera (giorni UTC, dal più vecchio) per una creator. Restituisce 404 se la creator non è tua.

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: caricamento, coda e programma di pubblicazione

Pubblica brevi reel verticali per una creator, come la pagina Per te (Reels) della dashboard. MP4 o WebM, verticale, massimo 60 secondi e 60 MB. Ogni reel passa una revisione rapida. Quando la creator ha un programma di pubblicazione, i reel approvati restano in coda (dal più vecchio) e uno va online a ogni orario programmato; senza programma vanno online appena approvati.

Stati: in_review, queued (approvato, in attesa del suo slot, con planned_at), live, rejected. I caricamenti hanno una quota propria: 300 reel all'ora per chiave e per agenzia.

POST /api/v1/reels

Passo 1. Body JSON: creator (slug), type (video/mp4 o video/webm), size (byte), caption facoltativa (max 150 caratteri). Restituisce 201 con id del reel e un upload_url firmato, valido 2 ore.

PUT del file, poi POST /api/v1/reels/:id/confirm

Passo 2. Fai PUT dei byte del video su upload_url (senza chiave API in quella richiesta), poi conferma. TeleSearch controlla il file e aggiunge il reel in revisione. Body JSON facoltativo: caption (sostituisce quella del passo 1) e duration_s. Confermare due volte è sicuro. I caricamenti non confermati scadono dopo un giorno.

# 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

I reel della creator in ordine di pubblicazione, con stato, visualizzazioni e like, più il riepilogo della coda.

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

Pubblica ora: un reel in coda va online subito; un reel ancora in revisione va online appena viene approvato.

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

Il programma di pubblicazione: posts_per_day (1, 2 o 3), times (orari locali a 24 ore, tanti quanti i post al giorno) e timezone (nome IANA). schedule è null quando non ne è impostato uno. Uno slot perso (o che trova la coda vuota) viene saltato, mai recuperato. DELETE rimuove il programma: i reel in coda vanno online subito, e da quel momento i reel approvati vanno online subito.

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

Errori e limiti

  • 400 body non valido. La risposta elenca ogni problema per campo: {"error":"Validation failed.","fields":{"age":"TeleSearch only lists adults: the minimum age is 18."}}
  • 401 chiave mancante, non valida o revocata.
  • 403 il titolare della chiave non è (più) un'agenzia, oppure hai provato a impostare link su una creator non verificata.
  • 404 creator non trovata, o non è una delle tue.
  • 409 l'account Telegram è già su TeleSearch (se è tuo, rivendicalo dalla dashboard), oppure l'annuncio è stato rifiutato o rimosso.
  • 413 body più grande di 20 KB. 422 un link Telegram non utilizzabile (non è un account personale, non trovato). 503 non è stato possibile raggiungere Telegram, riprova più tardi.
  • 429 troppe richieste: 600 richieste all'ora per chiave e per agenzia (più chiavi condividono la quota dell'agenzia), di cui 60 possono essere scritture (POST, PATCH, DELETE) e 20 nuove creator.

Le risposte non vengono mai messe in cache e l'accesso dal browser (CORS) non è abilitato: chiama l'API dal tuo server, non da una pagina web.

Server MCP

Collega Claude, Cursor o qualsiasi client MCP alla tua agenzia, e gestisci le creator e leggi le statistiche in linguaggio naturale. È un server remoto (Streamable HTTP, stateless) che usa le stesse chiavi API, gli stessi controlli e gli stessi limiti dell'API.

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

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

Invia un solo messaggio JSON-RPC per richiesta: i batch non sono supportati e ogni richiesta conta come un'unità della tua quota.

Claude (claude.ai e Claude Desktop)

Apri Impostazioni, Connettori, Aggiungi connettore personalizzato. Inserisci https://telesearch.ai/api/mcp come URL e aggiungi l'header Authorization: Bearer ts_live_YOUR_KEY dove il tuo piano o client permette di impostare header personalizzati. Se il tuo client supporta solo connettori OAuth, usa Claude Code o Cursor qui sotto, oppure Claude Desktop con un bridge locale come 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

Aggiungi questo a ~/.cursor/mcp.json (o .cursor/mcp.json in un progetto):

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

Poi prova: “Elenca le mie creator su TeleSearch e mostra i clic del mese scorso per ognuna.” Tratta la chiave come una password: chiunque la abbia può modificare le tue creator.