TeleSearch
Empieza gratis

API de TeleSearch

Una API JSON y un servidor MCP para agencias: añade y edita tus creadoras, y trae sus impresiones, clics y CTR a tu propio CRM, o pídele a Claude que lo haga.

Para quién es

La API y el servidor MCP son para agencias (cuentas con el rol de agencia). Actúan sobre las creadoras de tu agencia y nada más. Las cuentas de creadora no reciben claves de API. Si tu cuenta deja de ser una agencia, tus claves dejan de funcionar.

Consigue una clave

Inicia sesión con tu cuenta de agencia, abre Panel, API, ponle nombre a tu clave y créala. La clave se muestra una sola vez, así que guárdala bien. Puedes tener hasta 5 claves activas y revocar cualquiera en cualquier momento.

Envía la clave en el header Authorization de cada petición. Las claves son ts_live_ seguido de 40 caracteres.

GET /api/v1/creators

Las creadoras de tu agencia.

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

El perfil completo de una creadora. Devuelve 404 si la creadora no es tuyo.

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 es true cuando todas las cuentas de Telegram de la creadora están verificadas. Cada cuenta sin verificar lleva tu verify_code (mira el endpoint de verificación más abajo).

POST /api/v1/creators

Añade una creadora a tu agencia. Aplica las mismas comprobaciones que el formulario del sitio: solo cuentas personales de Telegram (sin canales, grupos ni bots), ninguna cuenta de Telegram que ya esté listada, solo adultos. El perfil se publica de inmediato, salvo que la comprobación automática de edad tenga una duda: entonces queda como pending para revisión humana y un notice lo indica. Cuerpo JSON, de hasta 20 KB:

  • accounts (obligatorio): de 1 a 5 objetos con link (enlace t.me o @usuario), y opcionales market_country, market_language y primary.
  • age (obligatorio): número entero, de 18 a 99.
  • adult_confirmed (obligatorio): debe ser true. Confirmas que la creadora es adulto y que la cuenta la gestionan adultos.
  • Opcionales: display_name (máx. 80, por defecto el nombre de Telegram), bio (máx. 2000), origin_country (código ISO), origin_city, languages (códigos como en), categories (una de: 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 (objeto, por ejemplo {"hair":"blonde"}). links (usuarios en otras plataformas) no se aceptan al crear: una creadora nueva no está verificada, mira más abajo.
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

Devuelve 201 con la misma forma que GET /creators/:slug (y un notice cuando el perfil queda en revisión). Los campos desconocidos se rechazan.

PATCH /api/v1/creators/:slug

Edita los campos del perfil que envíes: display_name, bio, age, origin_country, origin_city, languages, categories, attrs, links. Los campos que omitas no cambian; null vacía bio, origin_country y origin_city. languages y categories reemplazan toda la lista. attrs y links se fusionan: pon una clave en null para quitarla. Los links requieren una cuenta verificada: mientras alguna cuenta de Telegram de la creadora no esté verificada puedes quitar links pero no añadirlos ni cambiarlos (403). Las cuentas de Telegram no se pueden cambiar a través de la API. Un perfil publicado sigue publicado, salvo que la comprobación automática de edad tenga una duda tras la edición: entonces vuelve a revisión, igual que en el panel.

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

Devuelve 200 con la creadora actualizada.

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

Demuestra que eres dueño de las cuentas de Telegram de una creadora, al estilo de la comprobación de bio de TGStat. Los perfiles se publican de inmediato, pero están sin verificar hasta demostrarlo. Las creadoras sin verificar funcionan con normalidad, salvo que no se pueden establecer links a otras plataformas (OnlyFans, Fansly...) y no se muestran en el perfil público. Las creadoras verificadas reciben una insignia de Verificado.

  1. Lee verify_code (por ejemplo TS-K7M2QX) de GET /creators/:slug, por cada cuenta sin verificar.
  2. Pégalo en cualquier parte de la bio de esa cuenta de Telegram (da igual mayúsculas o minúsculas, debe ser una palabra aparte).
  3. Llama a este endpoint. TeleSearch lee el perfil público de Telegram y comprueba el código. Después puedes quitar el código de la bio.

Cuerpo JSON opcional: username (comprueba una cuenta; por defecto todas las cuentas sin verificar, hasta 5) y regenerate: true (emite un código nuevo en vez de comprobar). Los códigos caducan a los 7 días. Limitado a 10 intentos por hora por usuario (compartidos con el panel).

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

200 cuando está verificada (con la creadora actualizada en data). 422 cuando el código aún no está en la bio (el mensaje repite tu código), 503 cuando no se pudo conectar con Telegram, 429 cuando te quedas sin intentos.

DELETE /api/v1/creators/:slug

Elimina el perfil, igual que Eliminar en el panel. Libera los usuarios de Telegram. Llamarlo dos veces es seguro.

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

Impresiones, clics y CTR por creadora, más totales. days es 7, 30 o 90 (por defecto 7). El CTR es clics dividido entre impresiones, o null cuando no hay impresiones.

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 diaria (días UTC, del más antiguo al más reciente) de una creadora. Devuelve 404 si la creadora no es tuyo.

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: subida, cola y calendario de publicación

Publica reels verticales cortos para una creadora, como la página Para ti (Reels) del panel. MP4 o WebM, vertical, 60 segundos y 60 MB máx. Cada reel pasa una revisión rápida. Cuando la creadora tiene un calendario de publicación, los reels aprobados esperan en una cola (el más antiguo primero) y uno sale en cada hora programada; sin calendario salen en cuanto se aprueban.

Estados: in_review, queued (aprobado, esperando su turno, con planned_at), live, rejected. Las subidas tienen su propia cuota: 300 reels por hora por clave y por agencia.

POST /api/v1/reels

Paso 1. Cuerpo JSON: creator (slug), type (video/mp4 o video/webm), size (bytes), y caption opcional (150 caracteres máx.). Devuelve 201 con el id del reel y una upload_url firmada, válida 2 horas.

Haz PUT del archivo y luego POST /api/v1/reels/:id/confirm

Paso 2. Haz PUT de los bytes del vídeo a upload_url (sin clave de API en esa petición) y luego confirma. TeleSearch comprueba el archivo y añade el reel en revisión. Cuerpo JSON opcional: caption (reemplaza el del paso 1) y duration_s. Confirmar dos veces es seguro. Las subidas sin confirmar caducan al cabo de un día.

# 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

Los reels de la creadora en orden de publicación, con estado, vistas y likes, más el resumen de la cola.

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

Publicar ahora: un reel en cola sale de inmediato; un reel todavía en revisión sale en cuanto se aprueba.

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

El calendario de publicación: posts_per_day (1, 2 o 3), times (horas locales en formato de 24 horas, tantas como publicaciones por día) y timezone (nombre IANA). schedule es null cuando no hay ninguno. Un turno que se pierde (o que encuentra la cola vacía) se omite, nunca se recupera. DELETE quita el calendario: los reels en cola salen de inmediato, y los reels aprobados salen al instante a partir de entonces.

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

Errores y límites

  • 400 cuerpo no válido. La respuesta enumera cada problema por campo: {"error":"Validation failed.","fields":{"age":"TeleSearch only lists adults: the minimum age is 18."}}
  • 401 clave ausente, no válida o revocada.
  • 403 el titular de la clave ya no es una agencia, o intentaste establecer links en una creadora sin verificar.
  • 404 creadora no encontrada, o no es una de las tuyas.
  • 409 la cuenta de Telegram ya está en TeleSearch (si es tuya, reclámala desde el panel), o el perfil fue rechazado o eliminado.
  • 413 cuerpo mayor de 20 KB. 422 un enlace de Telegram que no se puede usar (no es una cuenta personal, no se encuentra). 503 no se pudo conectar con Telegram, reintenta más tarde.
  • 429 demasiadas peticiones: 600 peticiones por hora por clave y por agencia (varias claves comparten la cuota de la agencia), de las cuales 60 pueden ser escrituras (POST, PATCH, DELETE) y 20 creadoras nuevas.

Las respuestas nunca se almacenan en caché y el acceso desde el navegador (CORS) no está habilitado: llama a la API desde tu servidor, no desde una página web.

Servidor MCP

Conecta Claude, Cursor o cualquier cliente MCP a tu agencia, y gestiona creadoras y consulta estadísticas en lenguaje natural. Es un servidor remoto (Streamable HTTP, sin estado) que usa las mismas claves de API, las mismas comprobaciones y los mismos límites que la API.

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

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

Envía un mensaje JSON-RPC por petición: no se admiten lotes, y cada petición cuenta como una unidad de tu cuota.

Claude (claude.ai y Claude Desktop)

Abre Ajustes, Conectores, Añadir conector personalizado. Introduce https://telesearch.ai/api/mcp como URL y añade el header Authorization: Bearer ts_live_YOUR_KEY donde tu plan o cliente te deje poner headers personalizados. Si tu cliente solo admite conectores OAuth, usa Claude Code o Cursor más abajo, o Claude Desktop con un puente local como 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

Añade esto a ~/.cursor/mcp.json (o a .cursor/mcp.json en un proyecto):

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

Luego prueba: “Lista mis creadoras de TeleSearch y muéstrame los clics del mes pasado de cada una”. Trata la clave como una contraseña: quien la tenga puede editar tus creadoras.