API tutorial: creating short links from Node, Python and PHP

Authentication

Send your key in the Authorization header. Secret keys have full access and belong on a server. Public keys can only create links and are safe to expose in a browser — use them for in-product "share this" buttons, never for anything that reads data.

Create one link

POST to /api/links with a JSON body containing originalURL, and optionally path, title, tags, domainId and any of the targeting fields. Omit path and the server generates one according to the domain's slug rule. The response contains the full link object including shortURL.

Node.js

const res = await fetch("https://api.shortfreeurl.com/api/links", { method: "POST", headers: { "Content-Type": "application/json", Authorization: process.env.MS_KEY }, body: JSON.stringify({ originalURL: "https://example.com/page", path: "spring", tags: ["promo"] }) }); const link = await res.json();

Python

import os, requests r = requests.post("https://api.shortfreeurl.com/api/links", headers={"Authorization": os.environ["MS_KEY"]}, json={"originalURL": "https://example.com/page", "path": "spring"}) link = r.json()

PHP

$ch = curl_init("https://api.shortfreeurl.com/api/links"); curl_setopt_array($ch, [CURLOPT_POST => true, CURLOPT_RETURNTRANSFER => true, CURLOPT_HTTPHEADER => ["Content-Type: application/json", "Authorization: " . getenv("MS_KEY")], CURLOPT_POSTFIELDS => json_encode(["originalURL" => "https://example.com/page"])]); $link = json_decode(curl_exec($ch), true);

Bulk and errors

POST an array to /api/links/bulk for up to a thousand links in one request; the response is a parallel array where failed entries carry an error field instead of a link. Handle 409 for a slug that is taken, 402 for a plan limit, and 429 for rate limiting — the Retry-After header tells you how long to wait.

Rate limits

Fifty requests per second per key. For large jobs, use bulk endpoints rather than parallel single calls: one bulk request of a thousand links costs one request against your budget instead of a thousand.