TeleSearch
Начать бесплатно

API TeleSearch

JSON API и MCP-сервер для агентств: добавляй и редактируй своих креаторов и подтягивай их показы, клики и CTR в свою CRM или попроси Claude сделать это за тебя.

Для кого это

API и MCP-сервер предназначены для агентств (аккаунтов с ролью агентства). Они работают только с креаторами твоего агентства и больше ни с чем. Аккаунты креаторов API-ключей не получают. Если твой аккаунт перестанет быть агентством, ключи перестанут работать.

Получи ключ

Войди в аккаунт агентства, открой Кабинет, API, назови ключ и создай его. Ключ показывается один раз, поэтому сохрани его надёжно. Одновременно можно иметь до 5 активных ключей и в любой момент отозвать любой из них.

Передавай ключ в заголовке Authorization в каждом запросе. Ключи выглядят как ts_live_ и 40 символов после него.

GET /api/v1/creators

Креаторы твоего агентства.

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

Полный профиль одного креатора. Возвращает 404, если креатор не твой.

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, когда каждый аккаунт Telegram креатора подтверждён. У каждого неподтверждённого аккаунта есть твой verify_code (см. эндпоинт verify ниже).

POST /api/v1/creators

Добавляет креатора в твоё агентство. Выполняются те же проверки, что и в форме на сайте: только личные аккаунты Telegram (без каналов, групп и ботов), без аккаунта Telegram, который уже есть в каталоге, только для взрослых. Анкета публикуется сразу, если только автоматическая проверка возраста не вызывает сомнений: тогда она остаётся в статусе pending до ручной проверки, а notice сообщает об этом. Тело JSON, до 20 КБ:

  • accounts (обязательно): от 1 до 5 объектов с link (ссылка t.me или @username), а также необязательными market_country, market_language и primary.
  • age (обязательно): целое число от 18 до 99.
  • adult_confirmed (обязательно): должно быть true. Ты подтверждаешь, что креатор совершеннолетний, а аккаунтом управляют взрослые.
  • Необязательно: display_name (макс. 80, по умолчанию имя из Telegram), bio (макс. 2000), origin_country (код ISO), origin_city, languages (коды вроде en), categories (одна из: 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 (объект, например {"hair":"blonde"}). links (юзернеймы на других платформах) при создании не принимаются: новый креатор не подтверждён, см. ниже.
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

Возвращает 201 в том же формате, что и GET /creators/:slug (и notice, когда анкета задержана на проверку). Неизвестные поля отклоняются.

PATCH /api/v1/creators/:slug

Изменяет те поля профиля, которые ты отправил: display_name, bio, age, origin_country, origin_city, languages, categories, attrs, links. Пропущенные поля не меняются; null очищает bio, origin_country и origin_city. languages и categories заменяют весь список. attrs и links объединяются: установи ключ в null, чтобы удалить его. Для ссылок нужен подтверждённый аккаунт: пока любой аккаунт Telegram креатора не подтверждён, ссылки можно удалять, но нельзя добавлять или менять (403). Аккаунты Telegram через API изменить нельзя. Опубликованная анкета остаётся опубликованной, если только автоматическая проверка возраста после правки не вызывает сомнений: тогда она возвращается на проверку, как в кабинете.

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

Возвращает 200 с обновлённым креатором.

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

Подтверждает, что аккаунты Telegram креатора принадлежат тебе, по принципу проверки био как в TGStat. Анкеты публикуются сразу, но остаются неподтверждёнными, пока владение не доказано. Неподтверждённые креаторы работают как обычно, но ссылки на другие платформы (OnlyFans, Fansly...) задать нельзя, и в публичном профиле они не показываются. Подтверждённые креаторы получают значок Verified.

  1. Возьми verify_code (например, TS-K7M2QX) из GET /creators/:slug для каждого неподтверждённого аккаунта.
  2. Вставь его в любое место в био этого аккаунта Telegram (регистр не важен, код должен быть отдельным словом).
  3. Вызови этот эндпоинт. TeleSearch прочитает публичный профиль Telegram и проверит код. После этого код можно убрать из био.

Необязательное тело JSON: username (проверить один аккаунт; по умолчанию все неподтверждённые аккаунты, до 5) и regenerate: true (выдать новый код вместо проверки). Коды истекают через 7 дней. Лимит 10 попыток в час на пользователя (общий с кабинетом).

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

200, когда подтверждение прошло (с обновлённым креатором в data). 422, когда кода ещё нет в био (в сообщении повторяется твой код), 503, когда не удалось связаться с Telegram, 429, когда попытки закончились.

DELETE /api/v1/creators/:slug

Удаляет анкету, как «Удалить» в кабинете. Освобождает юзернеймы Telegram. Повторный вызов безопасен.

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

Показы, клики и CTR по каждому креатору, а также итоги. days равно 7, 30 или 90 (по умолчанию 7). CTR — это клики, делённые на показы, или null, если показов нет.

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

Посуточный ряд (дни UTC, сначала самые старые) по одному креатору. Возвращает 404, если креатор не твой.

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: загрузка, очередь и расписание публикаций

Публикуй короткие вертикальные reels для креатора, как на странице For You (Reels) в кабинете. MP4 или WebM, вертикальные, не более 60 секунд и 60 МБ. Каждый reel проходит быструю проверку. Если у креатора есть расписание публикаций, одобренные reels ждут в очереди (сначала самые старые), и один выходит в назначенное время; без расписания они выходят сразу после одобрения.

Статусы: in_review, queued (одобрен, ждёт своего слота, с planned_at), live, rejected. У загрузок своя квота: 300 reels в час на ключ и на агентство.

POST /api/v1/reels

Шаг 1. Тело JSON: creator (slug), type (video/mp4 или video/webm), size (в байтах), необязательный caption (до 150 символов). Возвращает 201 с id reel и подписанным upload_url, действительным 2 часа.

Отправь файл через PUT, затем POST /api/v1/reels/:id/confirm

Шаг 2. Отправь байты видео через PUT на upload_url (без API-ключа в этом запросе), затем подтверди. TeleSearch проверит файл и добавит reel на проверку. Необязательное тело JSON: caption (заменяет подпись из шага 1) и duration_s. Повторное подтверждение безопасно. Неподтверждённые загрузки истекают через сутки.

# 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

Reels креатора в порядке публикации со статусом, просмотрами и лайками, а также сводка по очереди.

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

Опубликовать сейчас: reel из очереди выходит сразу; reel, который ещё на проверке, выйдет, как только будет одобрен.

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

Расписание публикаций: posts_per_day (1, 2 или 3), times (локальное время в 24-часовом формате, столько же значений, сколько постов в день) и timezone (имя IANA). schedule равно null, если расписание не задано. Пропущенный слот (или слот, в котором очередь пуста) пропускается и не наверстывается. DELETE удаляет расписание: reels из очереди выходят сразу, а одобренные reels с этого момента выходят сразу после одобрения.

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

Ошибки и лимиты

  • 400 недопустимое тело запроса. Ответ перечисляет каждую проблему по полям: {"error":"Validation failed.","fields":{"age":"TeleSearch only lists adults: the minimum age is 18."}}
  • 401 ключ отсутствует, недействителен или отозван.
  • 403 владелец ключа больше не агентство (или никогда им не был), либо ты пытался задать ссылки для неподтверждённого креатора.
  • 404 креатор не найден или не принадлежит тебе.
  • 409 аккаунт Telegram уже есть на TeleSearch (если он твой, заяви на него права в кабинете) либо анкета была отклонена или удалена.
  • 413 тело больше 20 КБ. 422 ссылку на Telegram нельзя использовать (не личный аккаунт, не найден). 503 не удалось связаться с Telegram, повтори позже.
  • 429 слишком много запросов: 600 запросов в час на ключ и на агентство (несколько ключей делят квоту агентства), из них 60 могут быть записью (POST, PATCH, DELETE) и 20 новыми креаторами.

Ответы никогда не кэшируются, а доступ из браузера (CORS) не включён: вызывай API с сервера, а не с веб-страницы.

MCP-сервер

Подключи Claude, Cursor или любой MCP-клиент к своему агентству, управляй креаторами и читай статистику обычным языком. Это удалённый сервер (Streamable HTTP, без состояния), который использует те же API-ключи, те же проверки и те же лимиты, что и API.

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

Инструменты: 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.

Отправляй одно сообщение JSON-RPC на запрос: пакеты не поддерживаются, и каждый запрос считается за одну единицу твоей квоты.

Claude (claude.ai и Claude Desktop)

Открой Settings, Connectors, Add custom connector. Укажи https://telesearch.ai/api/mcp как URL и добавь заголовок Authorization: Bearer ts_live_YOUR_KEY, если твой тариф или клиент позволяет задавать свои заголовки. Если твой клиент поддерживает только коннекторы OAuth, используй Claude Code или Cursor ниже либо Claude Desktop с локальным мостом вроде 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

Добавь это в ~/.cursor/mcp.json (или .cursor/mcp.json в проекте):

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

Потом попробуй: «Покажи моих креаторов в TeleSearch и клики каждого за прошлый месяц». Относись к ключу как к паролю: любой, у кого он есть, может редактировать твоих креаторов.