TeleSearch
Mulai gratis

TeleSearch API

API JSON dan server MCP untuk agensi: tambah dan edit kreatormu, dan tarik impresi, klik, dan CTR mereka ke CRM-mu sendiri, atau minta Claude melakukannya.

Untuk siapa

API dan server MCP ini untuk agensi (akun dengan peran agensi). Keduanya bekerja pada kreator agensimu, tidak lebih. Akun kreator tidak mendapat API key. Jika akunmu berhenti menjadi agensi, key-mu berhenti berfungsi.

Dapatkan key

Masuk dengan akun agensimu, buka Dashboard, API, beri nama key-mu lalu buat. Key hanya ditampilkan sekali, jadi simpan dengan aman. Kamu bisa punya hingga 5 key aktif dan mencabut salah satunya kapan saja.

Kirim key di header Authorization pada setiap request. Key tampak seperti ts_live_ diikuti 40 karakter.

GET /api/v1/creators

Kreator agensimu.

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

Profil lengkap satu kreator. Mengembalikan 404 jika kreatornya bukan milikmu.

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 bernilai true jika setiap akun Telegram kreator sudah terverifikasi. Setiap akun yang belum terverifikasi membawa verify_code milikmu (lihat endpoint verify di bawah).

POST /api/v1/creators

Menambahkan kreator ke agensimu. Menjalankan pemeriksaan yang sama dengan formulir di situs: hanya akun Telegram pribadi (tanpa channel, grup, atau bot), tidak ada akun Telegram yang sudah terdaftar, hanya dewasa. Listing langsung tayang, kecuali pemeriksaan usia otomatis ragu: maka ditahan sebagai pending untuk ditinjau manusia dan sebuah notice menyatakannya. Body JSON, hingga 20 KB:

  • accounts (wajib): 1 sampai 5 objek dengan link (tautan t.me atau @username), serta opsional market_country, market_language, dan primary.
  • age (wajib): bilangan bulat, 18 sampai 99.
  • adult_confirmed (wajib): harus true. Kamu mengonfirmasi bahwa kreatornya dewasa dan akunnya dikelola orang dewasa.
  • Opsional: display_name (maks 80, default nama Telegram), bio (maks 2000), origin_country (kode ISO), origin_city, languages (kode seperti en), categories (salah satu dari: 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 (objek, misalnya {"hair":"blonde"}). links (handle di platform lain) tidak diterima saat pembuatan: kreator baru belum terverifikasi, lihat di bawah.
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

Mengembalikan 201 dengan bentuk yang sama seperti GET /creators/:slug (dan sebuah notice ketika listing ditahan untuk ditinjau). Field yang tidak dikenal ditolak.

PATCH /api/v1/creators/:slug

Mengedit field profil yang kamu kirim: display_name, bio, age, origin_country, origin_city, languages, categories, attrs, links. Field yang tidak kamu kirim tidak berubah; null mengosongkan bio, origin_country, dan origin_city. languages dan categories mengganti seluruh daftar. attrs dan links digabung: setel sebuah key ke null untuk menghapusnya. Links butuh akun terverifikasi: selama ada akun Telegram kreator yang belum terverifikasi, kamu bisa menghapus link tapi tidak menambah atau mengubahnya (403). Akun Telegram tidak bisa diubah lewat API. Listing yang sudah tayang tetap tayang, kecuali pemeriksaan usia otomatis ragu setelah pengeditan: maka kembali ke tinjauan, seperti di 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

Mengembalikan 200 dengan kreator yang sudah diperbarui.

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

Membuktikan kamu memiliki akun Telegram sebuah kreator, seperti pengecekan bio ala TGStat. Listing langsung tayang, tapi belum terverifikasi sampai dibuktikan. Kreator yang belum terverifikasi berfungsi seperti biasa, kecuali link ke platform lain (OnlyFans, Fansly...) tidak bisa disetel dan tidak ditampilkan di profil publik. Kreator terverifikasi mendapat lencana Terverifikasi.

  1. Baca verify_code (misalnya TS-K7M2QX) dari GET /creators/:slug, per akun yang belum terverifikasi.
  2. Tempel di mana saja di bio akun Telegram itu (huruf besar/kecil tidak masalah, harus berupa kata terpisah).
  3. Panggil endpoint ini. TeleSearch membaca profil Telegram publik dan memeriksa kodenya. Kamu boleh menghapus kode dari bio setelahnya.

Body JSON opsional: username (cek satu akun; default semua akun yang belum terverifikasi, hingga 5) dan regenerate: true (terbitkan kode baru, bukan memeriksa). Kode kedaluwarsa setelah 7 hari. Dibatasi 10 percobaan per jam per pengguna (dibagi dengan dashboard).

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

200 ketika terverifikasi (dengan kreator yang diperbarui di data). 422 ketika kode belum ada di bio (pesannya mengulang kodemu), 503 ketika Telegram tidak bisa dijangkau, 429 ketika percobaanmu habis.

DELETE /api/v1/creators/:slug

Menghapus listing, seperti Hapus di dashboard. Username Telegram jadi bebas. Memanggilnya dua kali aman.

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

Impresi, klik, dan CTR per kreator, plus total. days bernilai 7, 30, atau 90 (default 7). CTR adalah klik dibagi impresi, atau null jika tidak ada impresi.

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

Deret harian (hari UTC, terlama dulu) untuk satu kreator. Mengembalikan 404 jika kreatornya bukan milikmu.

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: unggah, antrean, dan jadwal posting

Posting reels vertikal pendek untuk kreator, seperti halaman For You (Reels) di dashboard. MP4 atau WebM, vertikal, maks 60 detik dan 60 MB. Setiap reel melewati peninjauan singkat. Jika kreator punya jadwal posting, reels yang disetujui menunggu di antrean (terlama dulu) dan satu tayang di setiap waktu terjadwal; tanpa jadwal, reels tayang begitu disetujui.

Status: in_review, queued (disetujui, menunggu slotnya, dengan planned_at), live, rejected. Unggahan punya kuota sendiri: 300 reels per jam per key dan per agensi.

POST /api/v1/reels

Langkah 1. Body JSON: creator (slug), type (video/mp4 atau video/webm), size (byte), opsional caption (maks 150 karakter). Mengembalikan 201 dengan id reel dan upload_url bertanda tangan, berlaku 2 jam.

PUT file-nya, lalu POST /api/v1/reels/:id/confirm

Langkah 2. PUT byte video ke upload_url (tanpa API key pada request itu), lalu konfirmasi. TeleSearch memeriksa file dan menambahkan reel ke tinjauan. Body JSON opsional: caption (menggantikan yang dari langkah 1) dan duration_s. Konfirmasi dua kali aman. Unggahan yang belum dikonfirmasi kedaluwarsa setelah sehari.

# 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 kreator berdasarkan urutan posting, dengan status, views, dan likes, plus ringkasan antrean.

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

Posting sekarang: reel yang mengantre langsung tayang; reel yang masih ditinjau tayang begitu disetujui.

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

Jadwal posting: posts_per_day (1, 2, atau 3), times (waktu lokal format 24 jam, sebanyak posting per hari) dan timezone (nama IANA). schedule bernilai null jika belum disetel. Slot yang terlewat (atau menemukan antrean kosong) dilewati, tidak pernah dikejar. DELETE menghapus jadwal: reels yang mengantre langsung tayang, dan reels yang disetujui langsung tayang mulai saat itu.

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

Error dan batas

  • 400 body tidak valid. Respons mencantumkan setiap masalah per field: {"error":"Validation failed.","fields":{"age":"TeleSearch only lists adults: the minimum age is 18."}}
  • 401 key hilang, tidak valid, atau dicabut.
  • 403 pemilik key bukan agensi (lagi), atau kamu mencoba menyetel links pada kreator yang belum terverifikasi.
  • 404 kreator tidak ditemukan, atau bukan milikmu.
  • 409 akun Telegram sudah ada di TeleSearch (jika itu milikmu, klaim dari dashboard), atau listing ditolak atau dihapus.
  • 413 body lebih besar dari 20 KB. 422 tautan Telegram yang tidak bisa dipakai (bukan akun pribadi, tidak ditemukan). 503 Telegram tidak bisa dijangkau, coba lagi nanti.
  • 429 terlalu banyak request: 600 request per jam per key dan per agensi (beberapa key berbagi kuota agensi), di antaranya 60 boleh berupa penulisan (POST, PATCH, DELETE) dan 20 kreator baru.

Respons tidak pernah di-cache, dan akses browser (CORS) tidak diaktifkan: panggil API dari servermu, bukan dari halaman web.

Server MCP

Hubungkan Claude, Cursor, atau klien MCP mana pun ke agensimu, lalu kelola kreator dan baca statistik dengan bahasa biasa. Ini server jarak jauh (Streamable HTTP, stateless) yang memakai API key yang sama, pemeriksaan yang sama, dan batas yang sama dengan API.

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

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

Kirim satu pesan JSON-RPC per request: batch tidak didukung, dan setiap request dihitung satu unit kuotamu.

Claude (claude.ai dan Claude Desktop)

Buka Settings, Connectors, Add custom connector. Masukkan https://telesearch.ai/api/mcp sebagai URL dan tambahkan header Authorization: Bearer ts_live_YOUR_KEY di tempat paket atau klienmu memungkinkan menyetel header kustom. Jika klienmu hanya mendukung konektor OAuth, pakai Claude Code atau Cursor di bawah, atau Claude Desktop dengan bridge lokal seperti 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

Tambahkan ini ke ~/.cursor/mcp.json (atau .cursor/mcp.json di sebuah proyek):

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

Lalu coba: “Tampilkan kreator TeleSearch-ku dan klik bulan lalu untuk masing-masing.” Perlakukan key seperti kata sandi: siapa pun yang memilikinya bisa mengedit kreatormu.