Create Short Links with the API

Create an API key

Open Short Links Settings, enter a recognisable key name and create the key. Copy it immediately and store it in your application's secret manager. The full key is shown only once; Yabrix stores only a secure hash and lets you revoke a key when it is no longer needed.

Authenticate the request

Send a POST request to https://www.yabrix.com/api/public/links/create. Authenticate with either Authorization: Bearer ybsl_... or the X-API-Key: ybsl_... header. Do not expose an API key in browser code, public repositories or a shared URL.

Send the link data

{
  "destinationUrl": "https://example.com/article",
  "internalName": "Newsletter August",
  "customAlias": "newsletter_august",
        "domain": "go.example.com"
}

destinationUrl is required; the other fields are optional. domain must be an active hostname that belongs to the client associated with the API key. When it is omitted, Yabrix uses the active custom default domain or ybrx.li. The API does not accept domainId.

JavaScript

Use this from a trusted server environment, such as a Node.js application or serverless function. Keep YABRIX_API_KEY in the platform's secret configuration.

const response = await fetch('https://www.yabrix.com/api/public/links/create', {
    method: 'POST',
    headers: {
        Authorization: `Bearer ${process.env.YABRIX_API_KEY}`,
        'Content-Type': 'application/json',
    },
    body: JSON.stringify({
        destinationUrl: 'https://example.com/article',
        internalName: 'Newsletter August',
        customAlias: 'newsletter_august',
    }),
});

const result = await response.json();
if (!response.ok) throw new Error(result.error);
console.log(result.link.shortUrl);

PHP

Read the key from an environment variable or a secret manager rather than placing it in source code.

$payload = json_encode([
        'destinationUrl' => 'https://example.com/article',
        'internalName' => 'Newsletter August',
        'customAlias' => 'newsletter_august',
]);

$request = curl_init('https://www.yabrix.com/api/public/links/create');
curl_setopt_array($request, [
        CURLOPT_POST => true,
        CURLOPT_POSTFIELDS => $payload,
        CURLOPT_HTTPHEADER => [
                'Authorization: Bearer ' . getenv('YABRIX_API_KEY'),
                'Content-Type: application/json',
        ],
        CURLOPT_RETURNTRANSFER => true,
]);
$response = curl_exec($request);
$status = curl_getinfo($request, CURLINFO_RESPONSE_CODE);
$result = json_decode($response ?: '{}', true);
if ($status < 200 || $status >= 300) throw new RuntimeException($result['error'] ?? 'API request failed.');
echo $result['link']['shortUrl'];

Python

This example uses the Python standard library, so it does not require an additional package.

import json
import os
from urllib.error import HTTPError
from urllib.request import Request, urlopen

payload = json.dumps({
        'destinationUrl': 'https://example.com/article',
        'internalName': 'Newsletter August',
        'customAlias': 'newsletter_august',
}).encode('utf-8')

request = Request(
        'https://www.yabrix.com/api/public/links/create',
        data=payload,
        method='POST',
        headers={
                'Authorization': f"Bearer {os.environ['YABRIX_API_KEY']}",
                'Content-Type': 'application/json',
        },
)
try:
        with urlopen(request) as response:
                result = json.load(response)
                print(result['link']['shortUrl'])
except HTTPError as error:
        print(json.load(error).get('error', 'API request failed.'))
        raise

cURL

Use cURL to test an integration from a terminal after exporting the key as an environment variable.

curl --request POST 'https://www.yabrix.com/api/public/links/create' \
    --header "Authorization: Bearer $YABRIX_API_KEY" \
    --header 'Content-Type: application/json' \
    --data '{
        "destinationUrl": "https://example.com/article",
        "internalName": "Newsletter August",
        "customAlias": "newsletter_august"
    }'

List available domains

Before creating a link, an integration can request the active domains available to the API key. Send a GET request to https://www.yabrix.com/api/public/links/domains. The result includes the default hostname and only the active hostnames available to that client; it does not expose internal domain IDs.

{
    "ok": true,
    "defaultDomain": "go.example.com",
    "domains": [
        { "hostname": "go.example.com", "isDefault": true },
        { "hostname": "ybrx.li", "isDefault": false }
    ]
}

Handle the response

A successful request returns 201 Created with the created link. Your application can store shortUrl for sharing and id for its own records.

{
    "ok": true,
    "link": {
        "id": 123,
        "shortUrl": "https://ybrx.li/newsletter_august",
        "code": "newsletter_august",
        "destinationUrl": "https://example.com/article",
        "internalName": "Newsletter August",
        "domain": "ybrx.li"
    }
}

Error response

When the request cannot be processed, Yabrix returns a JSON error with an appropriate HTTP status. For example, an invalid destination URL returns 422 Unprocessable Content.

{
    "ok": false,
    "error": "Enter a valid HTTP or HTTPS destination URL."
}

A duplicate custom alias returns 409, and a missing, revoked or invalid key returns 401. The first API version creates links only; advanced redirect settings, QR configuration and link management remain available in the panel.