Tracking API
Endpoints
Create tracker
POST /api/tracking
Body:
json
{
"name": "string (required)",
"keyword": "string (required, max 800)",
"exact_match": "boolean (default: false)",
"minus_words": "string[] | null",
"search_channels": "boolean (default: true)",
"search_chats": "boolean (default: true)",
"filter_geo": "string | null",
"filter_language": "string | null",
"filter_category": "string | null",
"filter_min_subscribers": "number | null",
"include_sources": "string[] | null",
"exclude_sources": "string[] | null",
"notify_via": "'bot' | 'webhook' (default: 'bot')",
"webhook_url": "string | null (required if notify_via = 'webhook')",
"notify_on_delete": "boolean (default: false)"
}Response: KeywordTrackerResponse (201)
List trackers
GET /api/tracking
Response: KeywordTrackerResponse[]
Get tracker
GET /api/tracking/:id
Response: KeywordTrackerResponse
Update tracker
PATCH /api/tracking/:id
Body: partial fields from Create
Response: KeywordTrackerResponse
Delete tracker
DELETE /api/tracking/:id
Response:
json
{
"success": true
}Get limits
GET /api/tracking/limits
Response:
json
{
"current": 2,
"max": 5,
"plan": "pro"
}Get matches
GET /api/tracking/:id/matches?limit=20&offset=0
Response:
json
{
"items": "KeywordMatchResponse[]",
"total": 42
}Get unread count
GET /api/tracking/:id/matches/unread
Response:
json
{
"count": 5
}Mark all matches read
POST /api/tracking/:id/matches/read-all
Response:
json
{
"success": true
}Test notification
POST /api/tracking/:id/test
Response:
json
{
"success": true
}Get filter options
GET /api/tracking/filters
Response:
json
{
"geo": [{ "code": "RU", "label": "Россия" }],
"languages": [{ "code": "ru", "label": "Русский" }],
"categories": [{ "code": "tech", "label": "Технологии" }]
}Types
KeywordTrackerResponse
| Field | Type | Description |
|---|---|---|
| id | number | Tracker ID |
| name | string | Display name |
| keyword | string | Search keyword/phrase |
| exact_match | boolean | Whole-word matching |
| minus_words | string[] | null | Exclusion words |
| search_channels | boolean | Search in channels |
| search_chats | boolean | Search in chats |
| filter_geo | string | null | Country filter |
| filter_language | string | null | Language filter |
| filter_category | string | null | Category filter |
| filter_min_subscribers | number | null | Min subscriber count |
| include_sources | string[] | null | Only search in these sources |
| exclude_sources | string[] | null | Exclude these sources |
| notify_via | 'bot' | 'webhook' | Notification method |
| webhook_url | string | null | Webhook URL |
| notify_on_delete | boolean | Notify on post deletion |
| is_enabled | boolean | Active status |
| total_matches | number | Total match count |
| created_at | string | ISO 8601 datetime |
KeywordMatchResponse
| Field | Type | Description |
|---|---|---|
| id | number | Match ID |
| tracker_id | number | Parent tracker ID |
| source_title | string | null | Channel/chat title |
| source_username | string | null | Channel/chat username |
| source_message_id | number | Telegram message ID |
| text_snippet | string | null | Matched text preview |
| matched_keyword | string | null | Actual matched text |
| post_url | string | null | Direct link to post |
| is_deleted | boolean | Post was deleted |
| is_read | boolean | Read status |
| detected_at | string | ISO 8601 detection datetime |
Authentication
All endpoints require Authorization: Bearer <token> header. Obtain token via /api/auth/telegram.
Rate limits
Standard API rate limits apply (see rate-limits).