TeleSearch API

A JSON API and an MCP server for agencies: add and edit your creators, and pull their impressions, clicks and CTR into your own CRM, or ask Claude to do it.

Who it is for

The API and the MCP server are for agencies (accounts with the agency role). They act on the creators of your agency, nothing else. Creator accounts do not get API keys. If your account stops being an agency, your keys stop working.

Get a key

Sign in with your agency account, open Dashboard, API, name your key and create it. The key is shown once, so store it safely. You can have up to 5 active keys and revoke any of them at any time.

Send the key in the Authorization header of every request. Keys look like ts_live_ followed by 40 characters.

GET /api/v1/creators

The creators of your agency.

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

The full profile of one creator. Returns 404 if the creator is not yours.

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 is true when every Telegram account of the creator is verified. Each unverified account carries your verify_code (see the verify endpoint below).

POST /api/v1/creators

Adds a creator to your agency. It runs the same checks as the website form: only personal Telegram accounts (no channels, groups or bots), no Telegram account that is already listed, adults only. The listing goes live right away, unless the automatic age check has a doubt: then it is held as pending for a human review and a notice says so. JSON body, up to 20 KB:

accounts (required): 1 to 5 objects with link (t.me link or @username), optional market_country, market_language and primary.
age (required): whole number, 18 to 99.
adult_confirmed (required): must be true. You confirm the creator is an adult and the account is run by adults.
Optional: display_name (max 80, defaults to the Telegram name), bio (max 2000), origin_country (ISO code), origin_city, languages (codes such as en), categories (one of: 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 (object, for example {"hair":"blonde"}). links (handles on other platforms) are not accepted at creation: a new creator is unverified, see below.

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

Returns 201 with the same shape as GET /creators/:slug (and a notice when the listing is held for review). Unknown fields are rejected.

PATCH /api/v1/creators/:slug

Edits the profile fields you send: display_name, bio, age, origin_country, origin_city, languages, categories, attrs, links. Fields you leave out are unchanged; null clears bio, origin_country and origin_city. languages and categories replace the whole list. attrs and links are merged: set a key to null to remove it. Links need a verified account: while any Telegram account of the creator is unverified you can remove links but not add or change them (403). Telegram accounts cannot be changed through the API. A live listing stays live, unless the automatic age check has a doubt after the edit: it then goes back to review, like in the 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

Returns 200 with the updated creator.

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

Proves you own the Telegram accounts of a creator, like the TGStat style bio check. Listings go live right away, but they are unverified until proven. Unverified creators work as usual, except that links to other platforms (OnlyFans, Fansly...) cannot be set and are not shown on the public profile. Verified creators get a Verified badge.

Read verify_code (for example TS-K7M2QX) from GET /creators/:slug, per unverified account.
Paste it anywhere in the bio of that Telegram account (case does not matter, it must be a separate word).
Call this endpoint. TeleSearch reads the public Telegram profile and checks the code. You can remove the code from the bio afterwards.

Optional JSON body: username (check one account; default every unverified account, up to 5) and regenerate: true (issue a new code instead of checking). Codes expire after 7 days. Limited to 10 attempts per hour per user (shared with the dashboard).

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

200 when verified (with the updated creator in data). 422 when the code is not in the bio yet (the message repeats your code), 503 when Telegram could not be reached, 429 when you are out of attempts.

DELETE /api/v1/creators/:slug

Removes the listing, like Remove in the dashboard. It frees the Telegram usernames. Calling it twice is safe.

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

Impressions, clicks and CTR per creator, plus totals. days is 7, 30 or 90 (default 7). CTR is clicks divided by impressions, or null when there are no impressions.

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

A daily series (UTC days, oldest first) for one creator. Returns 404 if the creator is not yours.

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

Errors and limits

400 invalid body. The response lists each problem by field: {"error":"Validation failed.","fields":{"age":"TeleSearch only lists adults: the minimum age is 18."}}
401 missing, invalid or revoked key.
403 the key owner is not an agency (any more), or you tried to set links on an unverified creator.
404 creator not found, or not one of yours.
409 the Telegram account is already on TeleSearch (if it is yours, claim it from the dashboard), or the listing was rejected or removed.
413 body larger than 20 KB. 422 a Telegram link that cannot be used (not a personal account, not found). 503 Telegram could not be reached, retry later.
429 too many requests: 600 requests per hour per key and per agency (several keys share the agency quota), of which 60 can be writes (POST, PATCH, DELETE) and 20 new creators.

Responses are never cached, and browser (CORS) access is not enabled: call the API from your server, not from a web page.

MCP server

Connect Claude, Cursor or any MCP client to your agency, and manage creators and read stats in plain English. It is a remote server (Streamable HTTP, stateless) that uses the same API keys, the same checks and the same limits as the 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.

Send one JSON-RPC message per request: batches are not supported, and every request counts as one unit of your quota.

Claude (claude.ai and Claude Desktop)

Open Settings, Connectors, Add custom connector. Enter https://telesearch.ai/api/mcp as the URL and add the header Authorization: Bearer ts_live_YOUR_KEY where your plan or client lets you set custom headers. If your client only supports OAuth connectors, use Claude Code or Cursor below, or Claude Desktop with a local bridge such as 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

Add this to ~/.cursor/mcp.json (or .cursor/mcp.json in a project):

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

Then try: “List my TeleSearch creators and show last month’s clicks for each.” Treat the key like a password: anyone who has it can edit your creators.