browse.tg Developer API

Build custom apps, bots, or research tools using real-time Telegram gift catalog data.

Getting Started

All API requests should be sent to the base URL below. The developer API provides public JSON endpoints that require authentication via a header.

Base URL:https://browse.tg

Authentication

Authenticate your requests by including your active API key in the X-API-Key custom HTTP header.

Rate Limiting: Each API Key is rate-limited to 100 requests per minute by default. Excess requests will receive an HTTP 429 Too Many Requests response.

API Endpoints

GET/api/v1/gifts/{id}

Fetch detailed information for a single Telegram gift by its unique ID (e.g. DurovsCap-1).

Parameters

Parameter	Type	Required	Description
id	string	Yes	The unique identifier of the gift (e.g., 'DurovsCap-1')

Request Sample

curl -X GET "https://browse.tg/api/v1/gifts/DurovsCap-1" \
  -H "X-API-Key: your_api_key_here"

GET/api/v1/gifts/search

Search and filter the entire Telegram gift catalog. Supports pagination, custom sorting, and multi-value trait filters.

Parameters

Parameter	Type	Required	Description
q	string	No	Free-text query or numeric serial number
collection	string	No	Comma-separated collection name filters
model	string	No	Comma-separated model trait filters
symbol	string	No	Comma-separated symbol trait filters
backdrop	string	No	Comma-separated backdrop trait filters
owner	string	No	Exact Telegram username of current owner
upgrade_state	string	No	Filter by 'on-chain' or 'off-chain'
sort	string	No	Sort order: 'newest', 'oldest', 'rarest', 'serial', 'price_asc'
page	integer	No	Page number (defaults to 1)
limit	integer	No	Results per page (1 to 100, defaults to 24)

Request Sample

curl -X GET "https://browse.tg/api/v1/gifts/search?q=1&collection=DurovsCap" \
  -H "X-API-Key: your_api_key_here"

GET/api/v1/collections

Retrieve a summary list of all Telegram gift collections indexed by browse.tg.

Request Sample

curl -X GET "https://browse.tg/api/v1/collections" \
  -H "X-API-Key: your_api_key_here"

GET/api/v1/collections/{name}

Fetch comprehensive metadata for a specific collection, along with filtered and paginated gifts.

Parameters

Parameter	Type	Required	Description
name	string	Yes	The collection name identifier (e.g., 'DurovsCap')
sort	string	No	Sort order: 'newest', 'oldest', 'rarest', 'serial', 'price_asc'
models	string	No	Comma-separated model trait filters
limit	integer	No	Results count limit
offset	integer	No	Pagination offset

Request Sample

curl -X GET "https://browse.tg/api/v1/collections/DurovsCap?limit=5" \
  -H "X-API-Key: your_api_key_here"

GET/api/v1/profile/{username}

Fetch gift holdings and portfolio stats for a given Telegram username.

Parameters

Parameter	Type	Required	Description
username	string	Yes	Telegram user handle (e.g. 'durov')

Request Sample

curl -X GET "https://browse.tg/api/v1/profile/durov" \
  -H "X-API-Key: your_api_key_here"

GET/api/v1/trending

Fetch trending gift listings based on search counts and views over the last 24h or 7d.

Parameters

Parameter	Type	Required	Description
period	string	No	Timeframe to rank trending items ('24h' or '7d', defaults to '24h')

Request Sample

curl -X GET "https://browse.tg/api/v1/trending?period=24h" \
  -H "X-API-Key: your_api_key_here"

Request API Access Key

Submit details below to generate an API key. Recreated keys are initially inactive until approved by the administrator.