API Documentation

Create, manage, and analyze short links programmatically with the PocoLink REST API.

Base URL: api.pocolink.com/v1Format: JSONAuth: Bearer Token

Authentication

All API requests require a Bearer token in the Authorization header. Retrieve your API key from the Account Settings section of your dashboard.

Authorization: Bearer pl_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxx

Keep your API key secret. Do not commit it to version control or expose it in client-side JavaScript. If your key is compromised, you can regenerate it from the dashboard — the old key will be immediately invalidated.

Create a Link

POST/v1/links

Creates a new short link. Returns the full link object including the generated short URL.

Request Body

Parameter	Type	Required	Description
url	string	Yes	The destination URL. Must include protocol (https://).
custom_slug	string	No	Custom back-half (e.g. "spring-sale"). 3–50 chars, alphanumeric and hyphens only. If omitted, a random 6-character slug is generated.
expires_at	string	No	ISO 8601 datetime. Link will return 410 Gone after this date.

Example Request (curl)

curl -X POST https://api.pocolink.com/v1/links \
  -H "Authorization: Bearer pl_live_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://yourwebsite.com/product/summer-collection?utm_source=api",
    "custom_slug": "summer-collection",
    "expires_at": "2025-09-01T00:00:00Z"
  }'

Example Request (JavaScript)

const response = await fetch('https://api.pocolink.com/v1/links', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer pl_live_xxxxxxxxxxxx',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    url: 'https://yourwebsite.com/product/summer-collection',
    custom_slug: 'summer-collection',
  }),
});

const { link } = await response.json();
console.log(link.short_url); // "https://pocolink.com/summer-collection"

Success Response — 201 Created

{
  "success": true,
  "link": {
    "id": "lnk_7f3k9x",
    "short_url": "https://pocolink.com/summer-collection",
    "long_url": "https://yourwebsite.com/product/summer-collection?utm_source=api",
    "slug": "summer-collection",
    "clicks": 0,
    "created_at": "2025-08-20T10:00:00Z",
    "expires_at": "2025-09-01T00:00:00Z"
  }
}

Error Response — 409 Conflict (slug taken)

{
  "success": false,
  "error": {
    "code": "SLUG_TAKEN",
    "message": "The slug 'summer-collection' is already in use by another link."
  }
}

Get Link Details

GET/v1/links/{link_id}

Retrieves a single link by its ID, including total click count.

curl https://api.pocolink.com/v1/links/lnk_7f3k9x \
  -H "Authorization: Bearer pl_live_xxxxxxxxxxxx"

Link Analytics

GET/v1/links/{link_id}/analytics

Returns click analytics for a specific link. By default, returns data from the past 30 days.

Query Parameters

Parameter	Default	Description
from	30 days ago	Start date (ISO 8601)
to	now	End date (ISO 8601)
granularity	day	Time bucket: `hour`, `day`, or `week`

Example Response

{
  "link_id": "lnk_7f3k9x",
  "total_clicks": 412,
  "period": { "from": "2025-07-20", "to": "2025-08-20" },
  "timeseries": [
    { "date": "2025-08-19", "clicks": 28 },
    { "date": "2025-08-20", "clicks": 41 }
  ],
  "breakdown": {
    "countries": [
      { "code": "US", "name": "United States", "clicks": 198 },
      { "code": "GB", "name": "United Kingdom", "clicks": 67 }
    ],
    "devices": [
      { "type": "mobile", "clicks": 289 },
      { "type": "desktop", "clicks": 112 },
      { "type": "tablet", "clicks": 11 }
    ],
    "referrers": [
      { "domain": "instagram.com", "clicks": 201 },
      { "domain": "twitter.com", "clicks": 88 },
      { "domain": "(direct)", "clicks": 123 }
    ]
  }
}

Update and Delete a Link

PATCH/v1/links/{link_id}

Update the destination URL, slug, or expiry date of an existing link. Only fields you include will be updated.

curl -X PATCH https://api.pocolink.com/v1/links/lnk_7f3k9x \
  -H "Authorization: Bearer pl_live_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://yourwebsite.com/new-destination" }'

DELETE/v1/links/{link_id}

Permanently deletes a link and its associated analytics. The short URL will return 404 after deletion. This action cannot be undone.

curl -X DELETE https://api.pocolink.com/v1/links/lnk_7f3k9x \
  -H "Authorization: Bearer pl_live_xxxxxxxxxxxx"

Returns 204 No Content on success.

Rate Limiting

API requests are limited to 1,000 requests per hour per API key. The following headers are included in every response:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 847
X-RateLimit-Reset: 1724151600   # Unix timestamp when the window resets

Exceeding the rate limit returns 429 Too Many Requests. Implement exponential backoff in your client and monitor X-RateLimit-Remaining to avoid hitting the limit.

Error Codes

All error responses follow this structure: { "success": false, "error": { "code": "...", "message": "..." } }

HTTP Status	Error Code	Meaning
400	INVALID_URL	The provided URL is malformed or missing the protocol.
401	UNAUTHORIZED	Missing or invalid API key.
403	FORBIDDEN	You don't have permission to access this resource.
404	NOT_FOUND	The link ID does not exist or belongs to a different account.
409	SLUG_TAKEN	The requested custom slug is already in use.
422	VALIDATION_ERROR	A request parameter failed validation (see message for details).
429	RATE_LIMITED	You have exceeded the hourly request limit.
500	INTERNAL_ERROR	Unexpected server error. Retry after a short delay.

Need Help with the API?

If you're running into issues or need functionality not covered here, email our developer support or open a ticket through the contact form.

Email api@pocolink.com Open Contact Form