API TeleSearch

API w formacie JSON i serwer MCP dla agencji: dodawaj i edytuj swoje twórczynie oraz pobieraj ich wyświetlenia, kliknięcia i CTR do własnego CRM albo poproś o to Claude.

Dla kogo to jest

API i serwer MCP są dla agencji (kont z rolą agencji). Działają na twórczyniach twojej agencji i na niczym więcej. Konta twórczyń nie dostają kluczy API. Jeśli twoje konto przestanie być agencją, twoje klucze przestaną działać.

Zdobądź klucz

Zaloguj się na konto agencji, otwórz Panel, API, nazwij klucz i go utwórz. Klucz jest pokazywany tylko raz, więc zapisz go w bezpiecznym miejscu. Możesz mieć do 5 aktywnych kluczy i w każdej chwili odwołać dowolny z nich.

Wysyłaj klucz w nagłówku Authorization każdego żądania. Klucze wyglądają jak ts_live_, a po tym 40 znaków.

GET /api/v1/creators

Twórczynie twojej agencji.

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

Pełny profil jednej twórczyni. Zwraca 404, jeśli twórczyni nie należy do ciebie.

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 ma wartość true, gdy każde konto twórczyni na Telegramie jest zweryfikowane. Każde niezweryfikowane konto ma twój verify_code (zobacz endpoint verify poniżej).

POST /api/v1/creators

Dodaje twórczynię do twojej agencji. Wykonuje te same kontrole co formularz na stronie: tylko prywatne konta na Telegramie (bez kanałów, grup i botów), żadne konto na Telegramie, które już jest w katalogu, tylko dorosłe. Profil trafia na stronę od razu, chyba że automatyczne sprawdzenie wieku budzi wątpliwość: wtedy jest wstrzymany jako pending do weryfikacji przez człowieka, a notice o tym informuje. Treść JSON, do 20 KB:

accounts (wymagane): od 1 do 5 obiektów z link (link t.me lub @username), opcjonalnie market_country, market_language i primary.
age (wymagane): liczba całkowita, od 18 do 99.
adult_confirmed (wymagane): musi być true. Potwierdzasz, że twórczyni jest dorosła, a konto jest prowadzone przez dorosłych.
Opcjonalnie: display_name (maks. 80, domyślnie nazwa z Telegrama), bio (maks. 2000), origin_country (kod ISO), origin_city, languages (kody takie jak en), categories (jedna z: 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 (obiekt, na przykład {"hair":"blonde"}). links (nazwy na innych platformach) nie są przyjmowane przy tworzeniu: nowy twórczyni jest niezweryfikowany, zobacz niżej.

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

Zwraca 201 w tym samym kształcie co GET /creators/:slug (oraz notice, gdy profil jest wstrzymany do weryfikacji). Nieznane pola są odrzucane.

PATCH /api/v1/creators/:slug

Edytuje przesłane pola profilu: display_name, bio, age, origin_country, origin_city, languages, categories, attrs, links. Pominięte pola pozostają bez zmian; null czyści bio, origin_country i origin_city. languages i categories zastępują całą listę. attrs i links są scalane: ustaw klucz na null, żeby go usunąć. Linki wymagają zweryfikowanego konta: dopóki jakiekolwiek konto twórczyni na Telegramie jest niezweryfikowane, możesz usuwać linki, ale nie dodawać ani zmieniać (403). Kont na Telegramie nie można zmieniać przez API. Aktywny profil pozostaje aktywny, chyba że po edycji automatyczne sprawdzenie wieku budzi wątpliwość: wtedy wraca do weryfikacji, tak jak w panelu.

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

Zwraca 200 ze zaktualizowanym twórczynią.

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

Dowodzi, że jesteś właścicielem kont twórczyni na Telegramie, podobnie jak sprawdzenie bio w stylu TGStat. Profile trafiają na stronę od razu, ale są niezweryfikowane, dopóki tego nie udowodnisz. Niezweryfikowane twórczynie działają jak zwykle, z wyjątkiem tego, że linków do innych platform (OnlyFans, Fansly...) nie można ustawić i nie są pokazywane w profilu publicznym. Zweryfikowane twórczynie dostają odznakę Verified.

Odczytaj verify_code (na przykład TS-K7M2QX) z GET /creators/:slug, dla każdego niezweryfikowanego konta.
Wklej go w dowolnym miejscu w bio tego konta na Telegramie (wielkość liter nie ma znaczenia, musi to być osobne słowo).
Wywołaj ten endpoint. TeleSearch odczytuje publiczny profil na Telegramie i sprawdza kod. Potem możesz usunąć kod z bio.

Opcjonalna treść JSON: username (sprawdź jedno konto; domyślnie każde niezweryfikowane konto, do 5) i regenerate: true (wystaw nowy kod zamiast sprawdzać). Kody wygasają po 7 dniach. Limit to 10 prób na godzinę na użytkownika (wspólny z panelem).

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

200, gdy zweryfikowano (z zaktualizowaną twórczynią w data). 422, gdy kodu jeszcze nie ma w bio (komunikat powtarza twój kod), 503, gdy nie udało się połączyć z Telegramem, 429, gdy skończyły ci się próby.

DELETE /api/v1/creators/:slug

Usuwa profil, tak jak Usuń w panelu. Zwalnia username z Telegrama. Dwukrotne wywołanie jest bezpieczne.

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

Wyświetlenia, kliknięcia i CTR na twórczynię, plus sumy. days to 7, 30 lub 90 (domyślnie 7). CTR to kliknięcia podzielone przez wyświetlenia, albo null, gdy nie ma wyświetleń.

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

Seria dzienna (dni UTC, od najstarszego) dla jednej twórczyni. Zwraca 404, jeśli twórczyni nie należy do ciebie.

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: przesyłanie, kolejka i harmonogram publikacji

Publikuj krótkie pionowe reelsy dla twórczyni, tak jak na stronie For You (Reels) w panelu. MP4 lub WebM, pionowo, maks. 60 sekund i 60 MB. Każdy reels przechodzi szybką weryfikację. Gdy twórczyni ma harmonogram publikacji, zatwierdzone reelsy czekają w kolejce (najstarsze pierwsze), a jeden trafia na żywo o każdej zaplanowanej godzinie; bez harmonogramu trafiają na żywo, gdy tylko zostaną zatwierdzone.

Statusy: in_review, queued (zatwierdzony, czeka na swój slot, z planned_at), live, rejected. Przesyłanie ma własny limit: 300 reelsów na godzinę na klucz i na agencję.

POST /api/v1/reels

Krok 1. Treść JSON: creator (slug), type (video/mp4 lub video/webm), size (bajty), opcjonalnie caption (maks. 150 znaków). Zwraca 201 z id reelsa i podpisanym upload_url, ważnym 2 godziny.

Wyślij plik przez PUT, potem POST /api/v1/reels/:id/confirm

Krok 2. Wyślij bajty wideo przez PUT na upload_url (bez klucza API w tym żądaniu), potem potwierdź. TeleSearch sprawdza plik i dodaje reels do weryfikacji. Opcjonalna treść JSON: caption (zastępuje ten z kroku 1) i duration_s. Dwukrotne potwierdzenie jest bezpieczne. Niepotwierdzone przesłania wygasają po dobie.

# 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

Reelsy twórczyni w kolejności publikacji, ze statusem, wyświetleniami i polubieniami, plus podsumowanie kolejki.

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

Opublikuj teraz: reels z kolejki trafia na żywo od razu; reels wciąż w weryfikacji trafia na żywo, gdy tylko zostanie zatwierdzony.

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

Harmonogram publikacji: posts_per_day (1, 2 lub 3), times (godziny lokalne w formacie 24-godzinnym, tyle, ile postów dziennie) i timezone (nazwa IANA). schedule ma wartość null, gdy nic nie ustawiono. Pominięty slot (albo taki, który zastaje pustą kolejkę) jest pomijany i nigdy nie jest nadrabiany. DELETE usuwa harmonogram: reelsy z kolejki trafiają na żywo od razu, a zatwierdzone reelsy od tej pory trafiają na żywo natychmiast.

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

Błędy i limity

400 nieprawidłowa treść. Odpowiedź wymienia każdy problem według pola: {"error":"Validation failed.","fields":{"age":"TeleSearch only lists adults: the minimum age is 18."}}
401 brakujący, nieprawidłowy lub odwołany klucz.
403 właściciel klucza nie jest (już) agencją albo próbowałeś ustawić linki dla niezweryfikowanej twórczyni.
404 nie znaleziono twórczyni albo nie jest jedną z twoich.
409 konto na Telegramie jest już w TeleSearch (jeśli jest twoje, przejmij je w panelu) albo profil został odrzucony lub usunięty.
413 treść większa niż 20 KB. 422 link do Telegrama, którego nie można użyć (to nie konto prywatne, nie znaleziono). 503 nie udało się połączyć z Telegramem, spróbuj później.
429 za dużo żądań: 600 żądań na godzinę na klucz i na agencję (kilka kluczy dzieli limit agencji), z czego 60 może być zapisami (POST, PATCH, DELETE) i 20 nowymi twórczyniami.

Odpowiedzi nigdy nie są cache'owane, a dostęp z przeglądarki (CORS) nie jest włączony: wywołuj API z serwera, a nie ze strony internetowej.

Serwer MCP

Połącz Claude, Cursor albo dowolnego klienta MCP ze swoją agencją i zarządzaj twórczyniami oraz czytaj statystyki zwykłym językiem. To zdalny serwer (Streamable HTTP, bezstanowy), który używa tych samych kluczy API, tych samych kontroli i tych samych limitów co API.

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

Narzędzia: 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.

Wysyłaj jedną wiadomość JSON-RPC na żądanie: batche nie są obsługiwane, a każde żądanie liczy się jako jedna jednostka twojego limitu.

Claude (claude.ai i Claude Desktop)

Otwórz Ustawienia, Konektory, Dodaj własny konektor. Wpisz https://telesearch.ai/api/mcp jako URL i dodaj nagłówek Authorization: Bearer ts_live_YOUR_KEY tam, gdzie twój plan lub klient pozwala ustawiać własne nagłówki. Jeśli twój klient obsługuje tylko konektory OAuth, użyj Claude Code albo Cursor poniżej, albo Claude Desktop z lokalnym mostem, takim jak 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

Dodaj to do ~/.cursor/mcp.json (albo .cursor/mcp.json w projekcie):

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

Potem spróbuj: „Wypisz moje twórczynie w TeleSearch i pokaż kliknięcia z zeszłego miesiąca dla każdego.” Traktuj klucz jak hasło: każdy, kto go ma, może edytować twoje twórczynie.