REST API
Pro
Overview
The tapurl.io REST API lets you create and manage short links, smart rules and view click statistics programmatically. Available on Pro plan and higher.
Base URL: https://tapurl.io/api/v1
Authentication
All API requests require an API key passed in the Authorization header:
Authorization: Bearer tap_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Generate your API key in Dashboard → My Account → API Access.
Keep your API key secret. Anyone with the key has full API access to your account.
Links
Create, list, retrieve and delete short links.
| Method | Endpoint | Description |
|---|---|---|
POST | /links | Create a short link |
GET | /links?project_id= | List links in a project |
GET | /links/{id} | Get a link by ID |
DELETE | /links/{id} | Delete a link |
Create a link
POST /api/v1/links
Authorization: Bearer tap_live_...
Content-Type: application/json
{
"original_url": "https://example.com/very-long-url",
"project_id": "your-project-uuid",
"click_limit": 1000,
"expires_at": "2026-12-31",
"fallback_url": "https://example.com/expired"
}
Response
{
"id": "uuid",
"short_code": "xK3mP9q",
"short_url": "https://tapurl.io/xK3mP9q",
"original_url": "https://example.com/very-long-url",
"project_id": "uuid",
"click_limit": 1000,
"expires_at": "2026-12-31",
"fallback_url": "https://example.com/expired",
"created_at": "2026-07-03T12:00:00Z"
}
Smart rules
Add geo, device or A/B test rules to any link. Each rule contains one or more variants with a target URL and weight.
| Method | Endpoint | Description |
|---|---|---|
POST | /links/{id}/rules | Add a smart rule |
GET | /links/{id}/rules | List rules for a link |
DELETE | /links/{id}/rules/{rule_id} | Delete a rule |
Geo rule — redirect RU traffic
POST /api/v1/links/{id}/rules
{
"type": "geo",
"condition_value": "RU",
"priority": 1,
"variants": [
{ "url": "https://offer-ru.com", "weight": 100 }
]
}
Device rule — mobile traffic
POST /api/v1/links/{id}/rules
{
"type": "device",
"condition_value": "mobile",
"priority": 2,
"variants": [
{ "url": "https://m.example.com", "weight": 100 }
]
}
A/B test — 70/30 split
For A/B testing, add multiple variants to one rule. Leave condition_value empty for ab_test type.
POST /api/v1/links/{id}/rules
{
"type": "ab_test",
"priority": 10,
"variants": [
{ "url": "https://offer-a.com", "weight": 70 },
{ "url": "https://offer-b.com", "weight": 30 }
]
}
| type | condition_value | Description |
|---|---|---|
geo | ISO country code (RU, US, DE…) | Match by visitor country |
device | mobile / desktop / tablet | Match by device type |
ab_test | — (leave empty) | Random split by weight |
Statistics
Get click statistics for any link including total clicks, unique clicks, breakdown by country and device.
GET /api/v1/links/{id}/stats
Authorization: Bearer tap_live_...
{
"link_id": "uuid",
"total_clicks": 1542,
"unique_clicks": 891,
"by_country": [
{ "country": "RU", "clicks": 720 },
{ "country": "US", "clicks": 310 }
],
"by_device": [
{ "device": "mobile", "clicks": 980 },
{ "device": "desktop", "clicks": 562 }
]
}
Error responses
All errors return JSON with an error code and human-readable message:
{
"error": "plan_required",
"message": "API access requires Pro plan or higher",
"upgrade_url": "https://tapurl.io/pricing"
}
| HTTP | error | Description |
|---|---|---|
| 401 | unauthorized | Missing or invalid API key |
| 401 | invalid_api_key | API key not found or revoked |
| 403 | plan_required | Feature not available on current plan |
| 404 | link_not_found | Link doesn't exist or belongs to another account |
| 404 | project_not_found | Project doesn't exist or belongs to another account |
| 422 | invalid_type | Rule type must be geo, device or ab_test |
| 422 | invalid_date | expires_at must be YYYY-MM-DD format |