TeleSearch
Comece grátis

API do TeleSearch

Uma API JSON e um servidor MCP para agências: adicione e edite suas criadoras e leve impressões, cliques e CTR para o seu próprio CRM, ou peça para o Claude fazer isso.

Para quem é

A API e o servidor MCP são para agências (contas com o papel de agência). Eles agem nas criadoras da sua agência, e só neles. Contas de criadora não recebem chaves de API. Se a sua conta deixar de ser uma agência, suas chaves param de funcionar.

Pegue uma chave

Entre com a sua conta de agência, abra Painel, API, dê um nome à chave e crie. A chave aparece uma única vez, então guarde em um lugar seguro. Você pode ter até 5 chaves ativas e revogar qualquer uma a qualquer momento.

Envie a chave no header Authorization de toda requisição. As chaves têm o formato ts_live_ seguido de 40 caracteres.

GET /api/v1/creators

As criadoras da sua agência.

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

O perfil completo de uma criadora. Retorna 404 se a criadora não for sua.

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 todas as contas do Telegram da criadora estão verificadas. Cada conta não verificada traz o seu verify_code (veja o endpoint de verificação abaixo).

POST /api/v1/creators

Adiciona uma criadora à sua agência. Roda as mesmas checagens do formulário do site: só contas pessoais do Telegram (sem canais, grupos ou bots), nenhuma conta do Telegram que já esteja listada, só adultos. O perfil entra no ar na hora, a menos que a checagem automática de idade tenha dúvida: nesse caso ele fica como pending para revisão humana e um notice avisa. Corpo JSON, até 20 KB:

  • accounts (obrigatório): de 1 a 5 objetos com link (link t.me ou @username), e opcionalmente market_country, market_language e primary.
  • age (obrigatório): número inteiro, de 18 a 99.
  • adult_confirmed (obrigatório): precisa ser true. Você confirma que a criadora é adulto e que a conta é administrada por adultos.
  • Opcionais: display_name (máx. 80, por padrão o nome do Telegram), bio (máx. 2000), origin_country (código ISO), origin_city, languages (códigos como en), categories (um 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 exemplo {"hair":"blonde"}). links (usernames em outras plataformas) não são aceitos na criação: uma criadora nova não é verificada, veja abaixo.
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

Retorna 201 com o mesmo formato de GET /creators/:slug (e um notice quando o perfil fica em revisão). Campos desconhecidos são rejeitados.

PATCH /api/v1/creators/:slug

Edita os campos de perfil que você enviar: display_name, bio, age, origin_country, origin_city, languages, categories, attrs, links. Os campos que você omitir não mudam; null limpa bio, origin_country e origin_city. languages e categories substituem a lista inteira. attrs e links são mesclados: defina uma chave como null para removê-la. Links exigem uma conta verificada: enquanto qualquer conta do Telegram da criadora não estiver verificada, você pode remover links, mas não adicionar nem alterar (403). As contas do Telegram não podem ser alteradas pela API. Um perfil no ar continua no ar, a menos que a checagem automática de idade tenha dúvida depois da edição: aí ele volta para revisão, como no painel.

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

Retorna 200 com a criadora atualizada.

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

Prova que você é dono das contas do Telegram de uma criadora, no estilo da checagem de bio do TGStat. Os perfis entram no ar na hora, mas ficam não verificados até a prova. Criadoras não verificadas funcionam normalmente, exceto que links para outras plataformas (OnlyFans, Fansly...) não podem ser definidos e não aparecem no perfil público. Criadoras verificadas ganham um selo de Verificado.

  1. Leia o verify_code (por exemplo TS-K7M2QX) em GET /creators/:slug, por conta não verificada.
  2. Cole em qualquer lugar da bio dessa conta do Telegram (maiúsculas e minúsculas não importam, precisa ser uma palavra separada).
  3. Chame este endpoint. O TeleSearch lê o perfil público do Telegram e confere o código. Depois você pode tirar o código da bio.

Corpo JSON opcional: username (confere uma conta; por padrão, todas as contas não verificadas, até 5) e regenerate: true (emite um código novo em vez de conferir). Os códigos expiram em 7 dias. Limitado a 10 tentativas por hora por usuário (compartilhado com o painel).

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

200 quando verificada (com a criadora atualizada em data). 422 quando o código ainda não está na bio (a mensagem repete o seu código), 503 quando não foi possível acessar o Telegram, 429 quando as tentativas acabaram.

DELETE /api/v1/creators/:slug

Remove o perfil, como Remover no painel. Libera os usernames do Telegram. Chamar duas vezes é 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

Impressões, cliques e CTR por criadora, além dos totais. days é 7, 30 ou 90 (padrão 7). CTR é cliques divididos por impressões, ou null quando não há impressões.

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

Uma série diária (dias em UTC, do mais antigo ao mais novo) de uma criadora. Retorna 404 se a criadora não for sua.

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, fila e agenda de postagem

Poste reels curtos na vertical para uma criadora, como na página Para você (Reels) do painel. MP4 ou WebM, vertical, no máximo 60 segundos e 60 MB. Todo reel passa por uma revisão rápida. Quando a criadora tem uma agenda de postagem, os reels aprovados esperam em uma fila (do mais antigo ao mais novo) e um vai ao ar a cada horário agendado; sem agenda, vão ao ar assim que são aprovados.

Status: in_review, queued (aprovado, esperando a vez, com planned_at), live, rejected. Os uploads têm cota própria: 300 reels por hora por chave e por agência.

POST /api/v1/reels

Passo 1. Corpo JSON: creator (slug), type (video/mp4 ou video/webm), size (bytes), e opcionalmente caption (150 caracteres no máximo). Retorna 201 com o id do reel e uma upload_url assinada, válida por 2 horas.

Faça PUT do arquivo e depois POST /api/v1/reels/:id/confirm

Passo 2. Faça PUT dos bytes do vídeo em upload_url (sem chave de API nessa requisição) e depois confirme. O TeleSearch confere o arquivo e coloca o reel em revisão. Corpo JSON opcional: caption (substitui a do passo 1) e duration_s. Confirmar duas vezes é seguro. Uploads não confirmados expiram depois de um dia.

# 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

Os reels da criadora na ordem de postagem, com status, visualizações e curtidas, além do resumo da fila.

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

Postar agora: um reel na fila vai ao ar na hora; um reel ainda em revisão vai ao ar assim que for aprovado.

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

A agenda de postagem: posts_per_day (1, 2 ou 3), times (horários locais de 24 horas, tantos quantos posts por dia) e timezone (nome IANA). schedule é null quando não há nenhuma definida. Um horário perdido (ou que encontra a fila vazia) é pulado, nunca recuperado. DELETE remove a agenda: os reels na fila vão ao ar na hora, e os reels aprovados vão ao ar logo em seguida a partir de então.

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

Erros e limites

  • 400 corpo inválido. A resposta lista cada problema por campo: {"error":"Validation failed.","fields":{"age":"TeleSearch only lists adults: the minimum age is 18."}}
  • 401 chave ausente, inválida ou revogada.
  • 403 o dono da chave não é (mais) uma agência, ou você tentou definir links em uma criadora não verificada.
  • 404 criadora não encontrada, ou não é uma das suas.
  • 409 a conta do Telegram já está no TeleSearch (se for sua, reivindique pelo painel), ou o perfil foi rejeitado ou removido.
  • 413 corpo maior que 20 KB. 422 um link do Telegram que não pode ser usado (não é conta pessoal, não encontrado). 503 não foi possível acessar o Telegram, tente de novo mais tarde.
  • 429 muitas requisições: 600 requisições por hora por chave e por agência (várias chaves dividem a cota da agência), das quais 60 podem ser escritas (POST, PATCH, DELETE) e 20 novas criadoras.

As respostas nunca ficam em cache e o acesso pelo navegador (CORS) não está habilitado: chame a API do seu servidor, não de uma página web.

Servidor MCP

Conecte o Claude, o Cursor ou qualquer cliente MCP à sua agência e gerencie criadoras e leia estatísticas em linguagem natural. É um servidor remoto (Streamable HTTP, sem estado) que usa as mesmas chaves de API, as mesmas checagens e os mesmos limites da API.

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

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

Envie uma mensagem JSON-RPC por requisição: lotes não são suportados, e cada requisição conta como uma unidade da sua cota.

Claude (claude.ai e Claude Desktop)

Abra Configurações, Conectores, Adicionar conector personalizado. Informe https://telesearch.ai/api/mcp como URL e adicione o header Authorization: Bearer ts_live_YOUR_KEY onde o seu plano ou cliente permitir headers personalizados. Se o seu cliente só suporta conectores OAuth, use o Claude Code ou o Cursor abaixo, ou o Claude Desktop com uma ponte 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

Adicione isto em ~/.cursor/mcp.json (ou .cursor/mcp.json em um projeto):

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

Depois tente: “Liste minhas criadoras do TeleSearch e mostre os cliques do mês passado para cada uma.” Trate a chave como uma senha: quem tiver acesso a ela pode editar suas criadoras.