API Documentation

The Xpolink REST API lets you create, manage, and track branded short links programmatically. Available on all plans.

Authentication

All API requests require an API key passed in the Authorization header:

Authorization: Bearer xpo_your_api_key_here

Generate an API key from your dashboard under Settings → API Keys. Keys start with xpo_ and cannot be viewed again after creation — store them securely.

Base URL

https://xpolink.app/api/v1

All endpoints below are relative to this base URL.

Error Handling

Errors return a JSON object with an error field:

{
  "error": "Monthly link limit reached (50)"
}

Common status codes:

• 400 — invalid request (missing fields, bad URL)
• 401 — missing or invalid API key
• 403 — plan limit reached or feature not available
• 404 — resource not found
• 429 — rate limited

Links

Create a link

Request body:

Example:

curl -X POST https://xpolink.app/api/v1/links \
  -H "Authorization: Bearer xpo_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/my-long-url",
    "shortCode": "promo",
    "title": "Spring promo"
  }'

Response:

{
  "id": "abc123",
  "shortCode": "promo",
  "longUrl": "https://example.com/my-long-url",
  "title": "Spring promo",
  "domainHostname": "go.yourbrand.com",
  "clickCount": 0,
  "isActive": true,
  "createdAt": "2026-04-12T00:00:00.000Z"
}

List links

Query parameters:

Get link details

Update a link

Delete a link

Get link analytics

Returns clicks over time, top countries, referrers, device/browser/OS breakdowns, and cities. The depth of data depends on your plan.

Export clicks (CSV)

Downloads raw click events as a CSV file. Business plan only.

List captured emails

Returns emails collected via the email gate feature. Paginated.

Export captured emails (CSV)

Bulk import

Import up to 500 links at once. Accepts a JSON array of link objects with the same fields as the create endpoint.

Domains

List domains

Add a domain

Verify a domain

Delete a domain

API Keys

List API keys

Returns key metadata (name, prefix, last used). The full key is never returned after creation. Available to all team members.

Create an API key

Only team owners can create API keys. Returns the raw key once — store it securely.

Delete an API key

Only team owners can revoke API keys.

Rate Limits

API requests are subject to your plan's monthly link creation limit. Creating a link via the API counts against the same quota as the dashboard. If you exceed your limit, the API returns a 403 error.

General rate limiting is applied per API key. If you receive a 429 response, wait and retry.