Search

POST /v1/search/messages
Required scope:
search.read

Request

{
  "source_ref": "@Tbatashev",
  "query": "open source projects and AI automation",
  "limit": 5,
  "scan_messages_limit": 200,
  "period_from": null,
  "period_to": null
}

Fields

NameTypeRequiredDefaultDescription
source_refstringyes-Telegram source reference
querystringyes-Search query
limitintegerno20Number of hits
scan_messages_limitintegerno200Recent messages to scan
period_fromdatetimenonullOptional lower datetime bound
period_todatetimenonullOptional upper datetime bound

Response

{
  "items": [
    {
      "source_ref": "@Tbatashev",
      "telegram_message_id": "604",
      "source_title": "Batashev / Systems",
      "text": "Full matched message text.",
      "message_link": "https://t.me/Tbatashev/604",
      "posted_at": "2026-04-10T12:00:00Z",
      "score": 0.8123,
      "context_before": [
        {
          "telegram_message_id": "602",
          "text": "Previous message.",
          "sender_peer_id": "123456",
          "posted_at": "2026-04-10T11:50:00Z",
          "message_link": "https://t.me/Tbatashev/602"
        }
      ],
      "context_after": [
        {
          "telegram_message_id": "605",
          "text": "Next message.",
          "sender_peer_id": "123456",
          "posted_at": "2026-04-10T12:05:00Z",
          "message_link": "https://t.me/Tbatashev/605"
        }
      ]
    }
  ]
}

Ranking

Search uses hybrid ranking:
SignalPurpose
Semantic similarityCaptures meaning through embeddings
Lexical coverageRewards direct query term overlap
Phrase matchRewards exact phrase matches
Short-message factorAvoids over-ranking vague short messages
Each hit includes up to 2 messages before and 2 messages after the match.