Developer API

Linkly REST API

v1 · OpenAPI 3.1 · updated October 24, 2026

Create and manage short links from your own scripts, CI pipelines or apps. The API uses the same links, analytics and daily quota as the dashboard, and every request is authenticated with a key you control.

Create an API key OpenAPI spec Live demo

Authentication Quick start Endpoints Examples Rate limits Errors

1. Authentication

Open your dashboard, choose API keys from the account menu, and create a key. The raw key (lk_live_…) is shown once — store it in an environment variable or secret manager.

Send the key with either header:

Authorization: Bearer lk_live_your_key_here
# or
X-API-Key: lk_live_your_key_here

Keys are hashed at rest. Linkly stores only a SHA-256 hash, so a lost key cannot be recovered. Revoke a key from the dashboard at any time; requests using it fail immediately.

2. Quick start

Create a short link:

curl -X POST https://linkly-link.vercel.app/api/v1/links \
  -H "Authorization: Bearer $LINKLY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/a/very/long/path",
    "alias": "launch",
    "expiresIn": "30d"
  }'

Response:

{
  "data": {
    "shortCode": "launch",
    "shortUrl": "https://linkly-link.vercel.app/launch",
    "originalUrl": "https://example.com/a/very/long/path",
    "clickCount": 0,
    "createdAt": "2026-10-24T16:00:00.000Z",
    "expiresAt": "2026-11-23T16:00:00.000Z",
    "disabled": false
  }
}

3. Endpoints

Method	Path	Purpose
GET	`/api/v1/links`	List your links with pagination, search and date filters.
POST	`/api/v1/links`	Create a link (optional alias and expiry).
GET	`/api/v1/links/{code}`	Fetch one link by short code.
PATCH	`/api/v1/links/{code}`	Change the destination without changing the short code.
DELETE	`/api/v1/links/{code}`	Delete the link and its click events.

Listing accepts page (default 1), pageSize (default 25, max 100), q (URL or code search), and range (7d or 30d).

Creating accepts url, optional alias (3–12 letters, numbers, hyphens or underscores) and optional expiresIn (1d, 7d, 30d).

4. Examples

List links

curl "https://linkly-link.vercel.app/api/v1/links?range=30d&pageSize=10" \
  -H "Authorization: Bearer $LINKLY_API_KEY"

Update a destination

curl -X PATCH https://linkly-link.vercel.app/api/v1/links/launch \
  -H "Authorization: Bearer $LINKLY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://example.com/new-destination" }'

Delete a link

curl -X DELETE https://linkly-link.vercel.app/api/v1/links/launch \
  -H "Authorization: Bearer $LINKLY_API_KEY"

5. Rate limits and quota

120 requests per minute per API key.
Link creation also counts against your account's daily quota (50 links per UTC day by default).
Responses include X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset (Unix seconds).
A 429 response includes Retry-After.

6. Errors

Errors use a stable shape:

{ "error": { "code": "invalid_alias", "message": "Custom alias must be 3-12 characters…" } }

Status	Code	Meaning
400	`invalid_url`	The destination is missing, malformed, or not http(s).
400	`invalid_alias`	The alias does not match the allowed pattern.
400	`invalid_expiry`	`expiresIn` is not one of `1d`, `7d`, `30d`.
401	`invalid_api_key`	Missing, revoked or unrecognised API key.
403	`forbidden`	The key does not own that link.
404	`not_found`	No link exists with that short code.
409	`alias_taken`	The alias is already in use.
429	`rate_limited` / `quota_exceeded`	Slow down or wait for the daily quota to reset.
503	`database_unavailable`	Temporary backend outage; retry later.

7. OpenAPI

The machine-readable contract lives at /openapi.json (OpenAPI 3.1). Import it into Postman, Insomnia or your code generator.

The API is intended for the account that owns the key. Do not ship keys in client-side code; call Linkly from a server you control.