URL shortener API
Create short links from an application, scheduled job or publishing workflow. Start with one authenticated request, then add bulk creation and reporting.
The ShortFreeURL REST API accepts JSON and uses API keys. API access is included on Free, whose current API-created-link allowance is 1,000; the account link allowance also applies. Plan-gated settings still require the corresponding plan when sent through the API.
Use POST /api/links to create a link, GET /api/links/:id to read it, and the statistics endpoints to retrieve click reports. The API is useful when a product, CRM or content system needs to save the resulting short URL alongside its own record.
Shorten your link
Free, instant, no ads. A QR code comes with it.
A quick anonymous link cannot be edited or measured. Create a free account first if you need to change its destination or see clicks.
- 1,000 links free
- 6 custom domains free
- No credit card
How to do it in three steps
- 1
Prepare a domain and key
Connect a domain in your account. Open Integrations & API → API and choose Create secret key for a server integration. Select the least scope the job needs and save the key when it is shown.
- 2
Send a JSON create request
POST to /api/links on your API origin with Authorization: Bearer followed by the key and Content-Type: application/json. Set originalURL and, when needed, domainId and path.
- 3
Store and verify the result
A successful create returns HTTP 201. Store id and secureShortURL with your application record, confirm originalURL and path, and test the returned short URL before publishing it.
Choose the key for the job
Keep secret keys in server-side environment variables or a secrets manager. A read-only key cannot create a link; a create-only key cannot update existing records. A domain-scoped key must use its permitted domain. Public create-only keys exist for client integrations, but they can still consume your link allowance, so use the narrowest available scope and review the public-key documentation before exposing one.
Fields and response handling
originalURL is the destination. path is the optional custom slug; omitting it generates a slug according to the domain settings. domainId selects a workspace domain; omitting it uses the default domain selection. Check upgradeRequired if it is returned: a successful response can identify unsupported optional fields that were removed. QR images are requested separately, rather than assumed to be part of the create response.
A repeatable bulk job
POST /api/links/bulk accepts an array of link objects, or an object containing a links array, with at most 1,000 items per request. Its HTTP 200 response is an array: successful entries contain link data, while failed entries contain error. Inspect every entry and retain the successes. A batch is not an all-or-nothing transaction, and sending it again can create unintended duplicate work.
Retrying without creating extra links
The link API does not implement an Idempotency-Key header. Store a chosen path and the returned link ID with each job. If a request times out, inspect the existing link before creating another. A duplicate-destination response can be HTTP 409 with an existing record under duplicate; a taken slug can produce a validation error. Verify domain, path and destination before treating an existing record as the completed operation.
Troubleshooting an integration
For 401, check the key, its expiry and the authorization header. For 403, check write access and the permitted domain. For 402, read the plan or quota details; repeating the same request does not grant access. For 404, check that the domain or link belongs to the workspace. For 429, wait for Retry-After and reduce concurrency. Read error on failed requests and keep credentials out of browser bundles, URLs and logs.
Example request: create one named link
POST /api/links HTTP/1.1
Authorization: Bearer YOUR_SECRET_KEY
Content-Type: application/json
{
"domainId": 42,
"originalURL": "https://example.com/catalog?utm_source=email",
"path": "catalog-email",
"tags": ["email", "catalog"]
}Replace 42 with a domain ID from your workspace and YOUR_SECRET_KEY with a server-side credential. GET /api/domains with a read-capable key lists your domains. With a connected go.yourdomain.com domain, the requested path would produce https://go.yourdomain.com/catalog-email if available. The response includes id, originalURL, path, shortURL and secureShortURL; it does not embed a QR image.
Guides and documentation
Related guides
Bulk URL shortener
Turn a campaign or catalogue list into short links with named slugs and tags. Preview a CSV in the dashboard, or process the list through the API.
URL shortener with analytics
Measure requests to your short links, separate detected bots from human clicks and compare campaign traffic with the right reporting context.
Google URL shortener (goo.gl) alternative
goo.gl no longer creates links — here is a free, drop-in replacement with your own domain and an API.
Self-hosted URL shortener or your own domain on a managed one?
Want your own URL shortener? You can build or self-host one — or get the same control on your own domain without running a server.
Firebase Dynamic Links alternative
Firebase Dynamic Links shut down on 25 August 2025. Replace them with short links that send each device to the right place.
Start Free — no credit card
The free plan includes 1,000 links, 6 custom domains and 50,000 tracked clicks a month, free forever. Choose a free subdomain from six shared domains. Paid plans start at $4 a month when you outgrow it, and you keep everything you have built.
Frequently asked questions
Does Free include API access?
Yes. Free currently allows 1,000 API-created links, subject to the overall account link allowance. Paid feature settings remain subject to their own plan requirements.
Can I authenticate without putting the key in a URL?
Yes. Send Authorization: Bearer followed by your API key, or use the x-api-key header. API keys in query strings are not accepted.
Does a 200 bulk response mean every link was created?
No. Inspect each response entry for link data or error. Keep successful results and reconcile failed or uncertain rows before retrying.
Can I change a destination through the API?
Yes, with a key that permits writes to that link. Send the changed fields to the link update endpoint and read the record again to verify the saved destination.
Which API address and request format should I use?
Use the HTTPS API origin shown in your deployment’s developer reference. Send JSON with Content-Type: application/json and replace sample domain IDs and credentials with your own.