Developer API · Quick start

Make your first API call in 3 steps

Prepare an API key and send the example request to create your first short link. Follow the steps below.

Prepare your account and API key

First, confirm your account and get an API key to authenticate requests.

Confirm your account

Complete signup and account confirmation. You can create basic links on the free plan; features and API limits vary by plan.

Get an API key

Get a key from the Developer API page in your dashboard and store it securely on your server.

View your API key in the dashboard

Your API key is a secret. Never put it in a public web page or mobile app; use it only on your server.

Create your first short link

Choose the example for your programming language to create your first short link. All examples use a Vivoldi service domain.

Before your first call: set your own User-Agent

Vivoldi's web server blocks default User-Agent values from server-side HTTP clients such as Node.js (JavaScript) and Python, as well as requests without this header. Replace MyBrand with your company or service name and set the same header in your server-side HTTP client code.

Choose an example and replace YOUR_API_KEY, MyBrand and url. Save the Node.js, PHP or Java code under the shown filename, then enter the run command. Paste the cURL command into a terminal.

Node.js 18+create-link.mjs
const apiKey = "YOUR_API_KEY";
const response = await fetch("https://vivoldi.com/api/link/v2/create", {
  method: "POST",
  headers: {
    "Authorization": "APIKey " + apiKey,
    "Content-Type": "application/json",
    "User-Agent": "MyBrand",
    "Accept-Language": "ko"
  },
  body: JSON.stringify({
    url: "https://your-site.example/your-page",
    domain: "https://vvd.bz"
  })
});
const result = await response.json();
console.log("HTTP " + response.status, result);
Run commandnode create-link.mjs
PHP + cURLcreate-link.php
<?php
$apiKey = "YOUR_API_KEY";
$body = json_encode([
    "url" => "https://your-site.example/your-page",
    "domain" => "https://vvd.bz"
]);
$curl = curl_init("https://vivoldi.com/api/link/v2/create");
curl_setopt_array($curl, [
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => [
        "Authorization: APIKey " . $apiKey,
        "Content-Type: application/json",
        "User-Agent: MyBrand",
        "Accept-Language: ko"
    ],
    CURLOPT_POSTFIELDS => $body,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT => 10
]);
$result = curl_exec($curl);
if ($result === false) {
    exit(curl_error($curl));
}
echo "HTTP " . curl_getinfo($curl, CURLINFO_HTTP_CODE) . PHP_EOL;
echo $result . PHP_EOL;
curl_close($curl);
Run commandphp create-link.php
Java 11+CreateLink.java
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.time.Duration;

public class CreateLink {
    public static void main(String[] args) throws Exception {
        String apiKey = "YOUR_API_KEY";
        String body = "{\"url\":\"https://your-site.example/your-page\","
                    + "\"domain\":\"https://vvd.bz\"}";
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://vivoldi.com/api/link/v2/create"))
            .timeout(Duration.ofSeconds(10))
            .header("Authorization", "APIKey " + apiKey)
            .header("Content-Type", "application/json")
            .header("User-Agent", "MyBrand")
            .header("Accept-Language", "ko")
            .POST(HttpRequest.BodyPublishers.ofString(body))
            .build();
        HttpResponse<String> response = HttpClient.newHttpClient()
            .send(request, HttpResponse.BodyHandlers.ofString());
        System.out.println("HTTP " + response.statusCode());
        System.out.println(response.body());
    }
}
Run commandjava CreateLink.java
cURL · macOS / LinuxPOST /api/link/v2/create
curl -sS -X POST "https://vivoldi.com/api/link/v2/create" \
  -H "Authorization: APIKey YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "User-Agent: MyBrand" \
  -H "Accept-Language: ko" \
  -d '{"url":"https://your-site.example/your-page","domain":"https://vvd.bz"}'

Values to replace: Use your own key for YOUR_API_KEY and the destination page for url. For your first test, keep domain as https://vvd.bz.

Response language: To receive error messages in another language, change ko in Accept-Language to the desired language code.

Running this link creation request again may create another short link. Avoid accidental duplicates while testing.

Check whether the request succeeded

If code in the response body is 0, the link was created. The new short link appears in result.

Example success response
{
  "code": 0,
  "message": "",
  "result": "https://vvd.bz/jH3d"
}

Check these two fields

code: 0 means success; result is the new short link. The sample address is illustrative; your actual result will differ.

Even if the HTTP status is 200, a nonzero code in the response body means an error. Check both code and message.

Having trouble?

Authentication error

For 401 or 423, check the API key, account status and allowed IP addresses.

Request error

For 400 or a nonzero code, check url, domain, the JSON format and message.

Access blocked

For 403, first check whether User-Agent is missing or still set to your tool's default. Set it to your company or service name and retry.

Rate limit

For 429, wait and try again. Limits depend on your plan.

Explore the next guides