Skip to content


Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time

Custom link shortener service using Cloudflare Workers + KV store on your domain. The Workers free tier is quite generous and perfectly suited for this since KV is optimized for high reads and infrequent writes, which is our use case.

Deploy to Cloudflare Workers

This API is easily consumed programmatically, such as through shell functions or slack slash commands, making it trivial to shorten links on the fly.

Additionally, it is possible to make a simple form to create short links right from a webpage if that is more to your liking. See this example for more info on that.


send POST request with form data url and path to redirect to url.

for authentication, pass a secret key in a x-preshared-key header.

if path exists already, the value will be overwritten (feature, not a bug).

API Example

curl --location --request POST "" \
    -H "x-preshared-key: your secret key goes here" \
    -H "Content-Type: application/x-www-form-urlencoded" \
    --data-urlencode "url=$URL" \
    --data-urlencode "path=$NAME"

passing to url, and gh to path will make redirect to it (this is a real example).

Send DELETE request to the shortlink which should be deleted.

Authentication is required; pass the secret key in the x-preshared-key header.

This method is idempotent, being that successive attempts to delete an already-deleted shortlink will result in status 200 (OK).

API Example

curl --location --request DELETE "" \
    -H "x-preshared-key: ${SECRET_KEY}"

Will delete the shortlink available at

Sending an authenticated GET request to the domain root will respond with a list of all shortlinks maintained by the service.

Authentication is required; pass the secret key in the x-preshared-key header.

API Example

curl --location --request GET "" \
    -H "x-preshared-key: ${SECRET_KEY}"

Will return a JSON array of keys with one to three properties:

  [{ name: "gh", expiration: null, metadata: ""}, ...]


expiration and metadata are optional.


this is the easy part, simply open the shortened link in your browser of choice!


Automatically deploys to Cloudflare Workers on push using GitHub Actions. You will only need to modify the account and kv namespace values in wrangler.toml, and set the repo secrets CF_API_TOKEN and SECRET_KEY (this is the preshared header authentication key) used in the workflow.

Oh, and run the worker on the route you want your shortener service to be on of course.


No releases published


No packages published

Contributors 4