Developer documentation
Automate professional links with the Blinkode API.
Create links, manage destinations, and generate QR codes from a clear token-authenticated API.
{
"data": {
"link": {
"id": "clx_123",
"slug": "K8m2pQzR",
"destinationUrl": "https://example.com",
"shortUrl": "https://bkode.link/K8m2pQzR",
"createdAt": "2026-05-27T20:00:00.000Z",
"expiresAt": null,
"hasPassword": false,
"clickCount": 0
}
}
}Authentication
Use an API key that is displayed only once.
Pro users create API keys from their account. The full secret is shown once; after that, Blinkode keeps only the prefix and hash.
- 1Use a Pro account with customer API access.
- 2Create a key from the signed-in API key endpoint.
- 3Save the returned secret once; Blinkode keeps only the hash.
- 4Send the key with Authorization: Bearer on /api/v1 routes.
curl -X POST "$APP_URL/api/api-keys" \
-H "Content-Type: application/json" \
-d '{ "name": "Production automation" }'Authorization: Bearer blinkode_sk_<public-token>.<secret-token>
Content-Type: application/jsonCreate links
Create links from your product.
Pro accounts can send expiration, password, domain, and custom slug values when the workflow needs them.
curl -X POST "$APP_URL/api/v1/links" \
-H "Authorization: Bearer $BLINKODE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"destinationUrl": "https://example.com",
"expiresAt": "2026-06-30T00:00:00.000Z",
"password": "launch-secret"
}'const response = await fetch(`${appUrl}/api/v1/links`, {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.BLINKODE_API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
destinationUrl: "https://example.com",
expiresAt: "2026-06-30T00:00:00.000Z",
password: "launch-secret",
}),
});
const payload = await response.json();import os
import requests
response = requests.post(
f"{os.environ['APP_URL']}/api/v1/links",
headers={
"Authorization": f"Bearer {os.environ['BLINKODE_API_KEY']}",
"Content-Type": "application/json",
},
json={
"destinationUrl": "https://example.com",
"expiresAt": "2026-06-30T00:00:00.000Z",
"password": "launch-secret",
},
)
payload = response.json()curl -X POST "$APP_URL/api/v1/links" \
-H "Authorization: Bearer $BLINKODE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"domainId": "dom_123",
"slug": "spring-campaign",
"destinationUrl": "https://example.com"
}'Manage links
List, view and delete links.
Each read or delete is limited to the API key owner. Unknown or outside-account links return the same “not found” response.
curl "$APP_URL/api/v1/links" \
-H "Authorization: Bearer $BLINKODE_API_KEY"curl "$APP_URL/api/v1/links/<link-id>" \
-H "Authorization: Bearer $BLINKODE_API_KEY"curl -X DELETE "$APP_URL/api/v1/links/<link-id>" \
-H "Authorization: Bearer $BLINKODE_API_KEY"QR codes
Generate QR codes on demand.
QR output is generated dynamically from the short URL and returned as a ready-to-use file.
curl "$APP_URL/api/v1/links/<link-id>/qr?format=png" \
-H "Authorization: Bearer $BLINKODE_API_KEY" \
-o shortlink.pngcurl "$APP_URL/api/v1/links/<link-id>/qr?format=svg" \
-H "Authorization: Bearer $BLINKODE_API_KEY" \
-o shortlink.svgcurl "$APP_URL/api/v1/links/<link-id>/qr?format=svg&download=0" \
-H "Authorization: Bearer $BLINKODE_API_KEY"Errors
Handle predictable JSON errors.
Failed API calls return an error message and a machine-readable code. Rate-limited requests include retry-after.
{
"error": "API access is not enabled for this account.",
"code": "api_access_disabled"
}missing_api_key
No Bearer token was provided.
invalid_api_key
The key is malformed, revoked, or does not match the stored hash.
api_access_disabled
The account plan does not include customer API access.
rate_limited
The API key exceeded the current limit backed by Redis.
invalid_json
The request body is not valid JSON.
invalid_destination_url
The destination is not a public http or https URL.
invalid_expires_at
expiresAt must be a valid ISO date string.
expired_expires_at
expiresAt must be at least 24 hours in the future.
invalid_password
password must be a string.
password_too_short
Password must be at least 6 characters.
unsafe_destination_url
The destination was blocked by security validation.
custom_domain_required
API-created links require an active Pro custom domain.
custom_domain_unavailable
The selected custom domain is unavailable for this account.
custom_slug_unavailable
Custom slugs require a Pro custom domain on customer API requests.
slug_unavailable
A requested custom slug already exists on that domain.
invalid_qr_format
QR format must be png or svg.
short_link_not_found
The requested link does not exist for this API key owner.
API reference
Routes available in v1.
The management of custom domains is done in the dashboard; links created through the API must use an existing Pro domain by sending `domainId`.