Overview The Links API allows you to create, retrieve, update, and delete shortened links. Each link can be associated with a client and optionally with a campaign. Links support tagging for organization and provide detailed analytics.
All endpoints require authentication via Bearer token in the Authorization header.
Create Link Request Body The full URL to be shortened. Must be a valid URL format.
UUID of the client this link belongs to. Client must exist in the system.
UUID of the campaign to associate this link with. Optional, can be null.
Array of tag names (strings) to organize the link. Optional.
Response Unique identifier (UUID) of the created link.
The original URL that was shortened.
The generated short code for accessing the link.
UUID of the user who created the link.
UUID of the associated client.
UUID of the associated campaign, or null if not associated.
ISO 8601 timestamp of creation.
ISO 8601 timestamp of last update.
Client information object. Campaign information object, or null if not associated. Aggregated counts. Total number of clicks on this link.
Example Request curl -X POST https://api.example.com/links \ -H "Authorization: Bearer YOUR_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "originalUrl": "https://example.com/very-long-url-path", "clientId": "123e4567-e89b-12d3-a456-426614174000", "campaignId": "987fcdeb-51a2-43d7-b890-123456789abc", "tags": ["social", "instagram"] }'
Example Response { "id" : "550e8400-e29b-41d4-a716-446655440000" , "originalUrl" : "https://example.com/very-long-url-path" , "shortCode" : "abc123" , "userId" : "7c9e6679-7425-40de-944b-e07fc1f90ae7" , "clientId" : "123e4567-e89b-12d3-a456-426614174000" , "campaignId" : "987fcdeb-51a2-43d7-b890-123456789abc" , "createdAt" : "2026-03-09T10:30:00.000Z" , "updatedAt" : "2026-03-09T10:30:00.000Z" , "client" : { "name" : "Acme Corp" }, "campaign" : { "name" : "Spring 2026" }, "_count" : { "clicks" : 0 }, "tags" : [ { "id" : "a1b2c3d4-e5f6-7890-abcd-ef1234567890" , "name" : "social" }, { "id" : "b2c3d4e5-f678-9012-bcde-f12345678901" , "name" : "instagram" } ] }
Error Responses Client not found. { "message" : "Client not found" }
List Links Query Parameters Filter links by client UUID.
Filter links by campaign UUID.
Search term to filter links (searches in URL and short code).
Response Returns an array of link objects with the same structure as the Create Link response.
Example Request curl -X GET "https://api.example.com/links?clientId=123e4567-e89b-12d3-a456-426614174000&search=example" \ -H "Authorization: Bearer YOUR_TOKEN"
Example Response [ { "id" : "550e8400-e29b-41d4-a716-446655440000" , "originalUrl" : "https://example.com/page" , "shortCode" : "abc123" , "userId" : "7c9e6679-7425-40de-944b-e07fc1f90ae7" , "clientId" : "123e4567-e89b-12d3-a456-426614174000" , "campaignId" : null , "createdAt" : "2026-03-09T10:30:00.000Z" , "updatedAt" : "2026-03-09T10:30:00.000Z" , "client" : { "name" : "Acme Corp" }, "campaign" : null , "_count" : { "clicks" : 42 }, "tags" : [] } ]
Get Link Path Parameters UUID of the link to retrieve.
Response Returns a single link object with the same structure as the Create Link response.
Example Request curl -X GET https://api.example.com/links/550e8400-e29b-41d4-a716-446655440000 \ -H "Authorization: Bearer YOUR_TOKEN"
Error Responses Link not found. { "message" : "Link not found" }
Update Link Path Parameters UUID of the link to update.
Request Body Updated URL. Must be a valid URL format.
Updated campaign UUID. Set to null to remove campaign association.
Updated array of tag names (strings).
All fields are optional. Only provided fields will be updated.
Response Returns the updated link object with the same structure as the Create Link response.
Example Request curl -X PUT https://api.example.com/links/550e8400-e29b-41d4-a716-446655440000 \ -H "Authorization: Bearer YOUR_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "originalUrl": "https://example.com/updated-url", "tags": ["updated", "newTag"] }'
Error Responses Link or client not found. { "message" : "Link not found" }
Delete Link Path Parameters UUID of the link to delete.
Response Returns 204 No Content on success.
Example Request curl -X DELETE https://api.example.com/links/550e8400-e29b-41d4-a716-446655440000 \ -H "Authorization: Bearer YOUR_TOKEN"
Error Responses Link not found. { "message" : "Link not found" }
This operation is irreversible. All click analytics associated with this link will also be deleted.
Get Link Metrics Path Parameters UUID of the link to get metrics for.
Query Parameters Number of days to include in the metrics (1-365). Defaults to 30.
Response Click counts grouped by date. Date in YYYY-MM-DD format.
Number of clicks on that date.
Click counts grouped by browser. Browser name (e.g., “Chrome”, “Firefox”).
Number of clicks from that browser.
Click counts grouped by country. Country name or null if not detected.
Number of clicks from that country.
Click counts grouped by city. City name or null if not detected.
Number of clicks from that city.
Example Request curl -X GET "https://api.example.com/links/550e8400-e29b-41d4-a716-446655440000/metrics?days=7" \ -H "Authorization: Bearer YOUR_TOKEN"
Example Response { "clicksByDate" : [ { "date" : "2026-03-09" , "count" : 15 }, { "date" : "2026-03-08" , "count" : 23 } ], "topBrowsers" : [ { "browser" : "Chrome" , "count" : 85 }, { "browser" : "Safari" , "count" : 42 }, { "browser" : "Firefox" , "count" : 18 } ], "topCountries" : [ { "country" : "United States" , "count" : 95 }, { "country" : "United Kingdom" , "count" : 32 }, { "country" : null , "count" : 8 } ], "topCities" : [ { "city" : "New York" , "count" : 45 }, { "city" : "London" , "count" : 28 }, { "city" : null , "count" : 12 } ] }
Error Responses Link not found. { "message" : "Link not found" }
