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 dashboardYour 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.
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.
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);
node create-link.mjs<?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);
php create-link.phpimport 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());
}
}
java CreateLink.javacurl -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.
{
"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?
For 401 or 423, check the API key, account status and allowed IP addresses.
For 400 or a nonzero code, check url, domain, the JSON format and message.
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.
For 429, wait and try again. Limits depend on your plan.