API Reference
Complete reference for the NextLinks REST API. All endpoints use the base URL https://nextlinks.ai
Endpoints
Authentication
Most API endpoints require authentication. Include your API key in the Authorization header:
Authorization: Bearer YOUR_API_KEYGetting Your API Key
- Navigate to your workspace settings
- Go to the API Keys section
- Generate a new API key
- Store it securely - it won't be shown again
Public Endpoints
The /api/click and /api/event endpoints are public and do not require authentication. They are designed for high-volume traffic.
Click Tracking
/api/clickRedirects users to the destination URL while tracking the click. This is called automatically when users click a NextLink.
Query Parameters
| Parameter | Required | Description |
|---|---|---|
| s | Yes | Link slug |
| d | No | Domain (for custom domains) |
| * | No | Any other params are passed to destination |
Example
# User clicks this URL
https://nextlinks.ai/c/abc123?utm_source=facebook
# System redirects to destination with click_id added
https://yoursite.com/landing?utm_source=facebook&click_id=uuid-hereUTM Parameter Pass-through
All UTM parameters and custom parameters (except reserved ones like s, d, click_id) are automatically appended to the destination URL.
Event/Conversion Tracking
/api/eventRecords a conversion event. Can be called via GET (for image pixels) or POST (for server-side tracking).
Parameters
| Parameter | Required | Description |
|---|---|---|
| pbk | Yes* | Postback key from event config |
| click_id | Yes* | Click ID from the original redirect |
| value | No** | Conversion value (for RevShare payouts) |
| metadata | No | JSON object with additional data |
* At least one of pbk or click_id is required
** Required for RevShare payout type
# GET request (simple)
curl "https://nextlinks.ai/api/event?pbk=your_key&click_id=abc123&value=49.99"
# POST request (with metadata)
curl -X POST https://nextlinks.ai/api/event \
-H "Content-Type: application/json" \
-d '{
"pbk": "your_postback_key",
"click_id": "abc123-def456",
"value": 49.99,
"metadata": {
"order_id": "ORDER-123",
"product": "Premium Plan"
}
}'Response
{
"success": true,
"eventId": 12345,
"clickStatus": "found" // or "pending" if click not yet processed
}NextLinks Management
/api/next-linksList all NextLinks for an account with pagination and filtering.
Query Parameters
| Parameter | Required | Description |
|---|---|---|
| accountId | Yes | Account UUID |
| page | No | Page number (default: 1) |
| selectedTags | No | Array of tag IDs to filter |
| tagOperator | No | 'OR' or 'AND' (default: OR) |
curl "https://nextlinks.ai/api/next-links?accountId=YOUR_ACCOUNT_ID&page=1" \
-H "Authorization: Bearer YOUR_API_KEY"Response
{
"rows": [
{
"id": "uuid",
"internal_name": "My Campaign Link",
"slug": "abc123",
"destination_url": "https://example.com",
"domain_name": "nextlinks.ai",
"active": true,
"tags": [{ "id": "tag-id", "name": "campaign-2024" }],
"created_at": "2024-01-15T10:30:00Z"
}
],
"pagination": {
"page": 1,
"pageSize": 25,
"totalRows": 150,
"totalPages": 6
}
}/api/next-linksCreate a new NextLink.
curl -X POST https://nextlinks.ai/api/next-links \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"accountId": "YOUR_ACCOUNT_ID",
"destination_url": "https://example.com/landing",
"internal_name": "Facebook Campaign Q1",
"slug": "fb-q1",
"domain_id": "domain-uuid",
"tags": ["tag-uuid-1", "tag-uuid-2"]
}'Domains
/api/domainsList all custom domains for an account.
/api/domainsAdd a new custom domain.
curl -X POST https://nextlinks.ai/api/domains \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"accountId": "YOUR_ACCOUNT_ID",
"domain_name": "go.yourcompany.com"
}'Reports & Analytics
/api/reportsGet aggregated analytics data with flexible grouping and filtering.
Request Body
| Field | Type | Description |
|---|---|---|
| accountId | string | Account UUID |
| dateRange | object | { from: 'YYYY-MM-DD', to: 'YYYY-MM-DD' } |
| groupBy | string | link, tag, device, country, browser, os |
| filters | object | Optional filters |
curl -X POST https://nextlinks.ai/api/reports \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"accountId": "YOUR_ACCOUNT_ID",
"dateRange": {
"from": "2024-01-01",
"to": "2024-01-31"
},
"groupBy": "link"
}'Webhooks
/api/webhooksCreate a webhook to receive conversion events.
curl -X POST https://nextlinks.ai/api/webhooks \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"account_id": "YOUR_ACCOUNT_ID",
"name": "My CRM Webhook",
"target_url": "https://yourserver.com/webhook",
"method": "POST",
"payload_template": {
"click_id": "{click_id}",
"value": "{value}",
"timestamp": "{conversion_timestamp}"
}
}'Available Macros
Use these macros in your payload template:
Tags
/api/tagsList or create tags for organizing links.
# List tags
curl -X POST https://nextlinks.ai/api/tags \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"accountId": "YOUR_ACCOUNT_ID",
"page": 1
}'Rate Limits
API requests are subject to rate limiting to ensure service stability:
Standard API Endpoints
- 100 requests per minute per IP
- 1,000 requests per hour per account
Click Tracking (/api/click)
- No rate limiting - designed for high traffic
- Optimized for ad server verification
Event Tracking (/api/event)
- No rate limiting - designed for conversion volume
Rate Limit Headers
Responses include these headers:
X-RateLimit-Remaining: Requests remainingX-RateLimit-Reset: When limit resets
Error Handling
All errors follow a consistent JSON format:
{
"error": "Error message description"
}HTTP Status Codes
200- Success400- Bad request (invalid parameters)401- Unauthorized (missing or invalid API key)403- Forbidden (no access to resource)404- Resource not found429- Rate limit exceeded500- Server error