Tags (Categories) API
Overview
Use GET /api/v1/tags to search tags (categories), then GET /api/v1/tags/:id/advertisers to list advertisers for a tag with the same filters as the tag show page in the app.
Performance
- Searchkick-first – Tag search uses Searchkick when available (fast + relevance)
- SQL fallback – Tag search falls back to SQL when Searchkick is unavailable/errors
- No total count – Pagination uses
has_moreonly (fast with millions of advertisers) - Searchkick-first – Uses Elasticsearch with
track_total_hits: false - SQL fallback – When Searchkick is unavailable, uses an indexed SQL subquery (no
COUNT)
Index: Search tags
Search for tags (categories) by name. This endpoint is Searchkick-first, with a SQL fallback when Searchkick is unavailable.
Request
GET /api/v1/tags
Params: search (or q), page, per_page.
Authentication
X-Api-Key: YOUR_API_KEY
Required header (or api_key query param)
Tag advertisers: List advertisers for a tag
Returns advertisers for a given tag (category), with the same filters as the tag show page in the app.
Request
GET /api/v1/tags/:id/advertisers
:id can be the tag ID (integer) or the tag slug (e.g. electronics)
Authentication
X-Api-Key: YOUR_API_KEY
Required header (or api_key query param)
API Playground
Test tag search and tag advertisers. For advertisers, use a tag id or slug (e.g. electronics). Optional: page, per_page, network_id, status, sort.
Parameters
Tag search
| Parameter | Type | Required | Description |
|---|---|---|---|
search (or q) |
string | No | Search term for tag names |
page |
integer | No | Page number (default: 1) |
per_page |
integer | No | Results per page (default: 50, max: 100) |
Tag advertisers
| Parameter | Type | Required | Description |
|---|---|---|---|
id |
path | Yes | Tag ID (integer) or tag slug (e.g. electronics) |
page |
integer | No | Page number (default: 1) |
per_page |
integer | No | Results per page (default: 300, max: 500) |
network_id |
integer | No | Filter advertisers by network ID |
status |
string | No | Filter by advertiser status (e.g. approved, applied) |
sort |
string | No | global_total_sales (default) or global_total_commissions |
Response Format
Both endpoints return data plus meta. Tag advertisers includes the tag object.
Tag search
{
"data": [
{ "id": 1, "name": "sports", "slug": "sports", "taggings_count": 123 },
...
],
"meta": {
"search": "sport",
"page": 1,
"per_page": 50,
"has_more": false
}
}Tag advertisers
{
"tag": { "id": 123, "name": "electronics" },
"data": [
{ "id": "1", "type": "advertiser", "attributes": { "name": "...", "status": "approved", ... } },
...
],
"meta": {
"page": 1,
"per_page": 300,
"has_more": true
}
}Examples
Search tags
curl -H "X-Api-Key: YOUR_API_KEY" \
"https://app.hienergy.ai/api/v1/tags?search=sport&per_page=20"By tag slug
curl -H "X-Api-Key: YOUR_API_KEY" \
"https://app.hienergy.ai/api/v1/tags/electronics/advertisers"With filters
curl -H "X-Api-Key: YOUR_API_KEY" \
"https://app.hienergy.ai/api/v1/tags/123/advertisers?network_id=1&status=approved&per_page=100&sort=global_total_commissions"