UrlShortener
API reference v1

Shorten links from your own code

Create and look up your short links without opening the dashboard. The API is REST, returns JSON and uses standard HTTP codes.

Base URL
https://api.urlshortener.com/v1

Your first request in three steps

  1. 1

    Get the Developer Plan

    The API is not part of the Free or Pro plans.

    USD 15

    per month

    1,000

    short links per month

    60

    requests per minute

    Everything in the Pro Plan, plus API access to the shortener with your own keys.

    See plans
  2. 2

    Create a key

    In the account dashboard, API section. It is shown only once.

    Production keysk_live_9f2c••••••••created today
  3. 3

    Create your first short link

    Copy the request, swap in your key and run it.

    cURL
    curl -X POST https://api.urlshortener.com/v1/shorten \
  -H "Authorization: Bearer sk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://www.example.com/very-long-url",
    "alias": "summer-promo"
  }'
    Response · 200 OK
    {
  "id": "link_89f2a4",
  "short_url": "https://sho.rt/summer-promo",
  "destination": "https://www.example.com/very-long-url",
  "clicks": 0,
  "created_at": "2026-10-13T10:30:00Z"
}

Authentication

Every request carries your secret key in the Authorization header. Keys are created and revoked in the account dashboard.

A key gives full access to your account: keep it out of browser code and public repositories.

Authorization header
Authorization: Bearer sk_live_your_api_key

Rate limits

The limit is counted per key. Past it the API responds 429 and the Retry-After header says how many seconds to wait.

429
HTTP/1.1 429 Too Many Requests
Retry-After: 12

Errors

Errors return an HTTP code and a JSON body with a stable identifier.

400invalid_request
A parameter is missing or invalid.
401invalid_key
The key does not exist or was revoked.
403plan_required
The account is not on the Developer Plan.
404not_found
The short link does not exist.
429rate_limited
The request limit was exceeded.
403
{
  "error": "plan_required",
  "message": "API access requires the Developer Plan."
}

Create a short link

POST/shorten

Creates a short link for a destination URL. You can pick a custom alias instead of the short code.

Parameters

urlstringrequired

The destination URL.

aliasstringoptional

Custom alias, for example summer-promo.

curl -X POST https://api.urlshortener.com/v1/shorten \
  -H "Authorization: Bearer sk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://www.example.com/very-long-url",
    "alias": "summer-promo"
  }'
Response · 200 OK
{
  "id": "link_89f2a4",
  "short_url": "https://sho.rt/summer-promo",
  "destination": "https://www.example.com/very-long-url",
  "clicks": 0,
  "created_at": "2026-10-13T10:30:00Z"
}

List short links

GET/urls

Returns the short links in your account, paginated.

Parameters

limitnumberoptional

Maximum number of short links to return.

cursorstringoptional

Cursor returned by the previous request.

curl https://api.urlshortener.com/v1/urls?limit=20 \
  -H "Authorization: Bearer sk_live_your_api_key"
Response · 200 OK
{
  "data": [
    {
      "id": "link_89f2a4",
      "short_url": "https://sho.rt/summer-promo",
      "destination": "https://www.example.com/very-long-url"
    }
  ],
  "next_cursor": null
}

Get a short link

GET/urls/{id}

Returns a short link and a summary of its activity.

Parameters

idstringrequired

The identifier of the short link.

curl https://api.urlshortener.com/v1/urls/link_89f2a4 \
  -H "Authorization: Bearer sk_live_your_api_key"
Response · 200 OK
{
  "id": "link_89f2a4",
  "short_url": "https://sho.rt/summer-promo",
  "destination": "https://www.example.com/very-long-url",
  "clicks": 248
}