Server

Create, update and delete your app's links from your backend with its API key, in curl, Node.js, Python and C#.

Your backend creates links when it has something to share, such as a product, an invitation or a post, and stores each link's shortUrl and id with it. Keep the API key in your secrets manager or environment, never in a web page: use the live key in production and the sandbox key in staging.

Create a link

POST /api/links takes your app's id, the destination in your app and the preview's details. title, description, imageUrl and fallbackUrl are required but may be empty.

curl

curl -X POST https://dev.thedbl.ink/api/links \
  -H "Api-Key: $DBL_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "appId": 42,
    "fullUrl": "/products/1234",
    "title": "Spring sale",
    "description": "Up to 50% off this week only.",
    "imageUrl": "https://example.com/images/spring-sale.png",
    "fallbackUrl": "https://example.com/spring-sale"
  }'

Node.js

const response = await fetch('https://dev.thedbl.ink/api/links', {
  method: 'POST',
  headers: { 'Api-Key': process.env.DBL_API_KEY!, 'Content-Type': 'application/json' },
  body: JSON.stringify({
    appId: 42,
    fullUrl: '/products/1234',
    title: 'Spring sale',
    description: 'Up to 50% off this week only.',
    imageUrl: 'https://example.com/images/spring-sale.png',
    fallbackUrl: 'https://example.com/spring-sale',
  }),
})
if (!response.ok) throw new Error(`Deep Blue Links answered ${response.status}: ${await response.text()}`)
const link = await response.json()
console.log(link.shortUrl)

Python

import os
import requests

response = requests.post(
    "https://dev.thedbl.ink/api/links",
    headers={"Api-Key": os.environ["DBL_API_KEY"]},
    json={
        "appId": 42,
        "fullUrl": "/products/1234",
        "title": "Spring sale",
        "description": "Up to 50% off this week only.",
        "imageUrl": "https://example.com/images/spring-sale.png",
        "fallbackUrl": "https://example.com/spring-sale",
    },
    timeout=10,
)
if not response.ok:
    raise RuntimeError(f"Deep Blue Links answered {response.status_code}: {response.text}")
print(response.json()["shortUrl"])

using System.Net.Http.Json;

using var http = new HttpClient { BaseAddress = new Uri("https://dev.thedbl.ink/") };
http.DefaultRequestHeaders.Add("Api-Key", Environment.GetEnvironmentVariable("DBL_API_KEY"));

var response = await http.PostAsJsonAsync("api/links", new
{
    appId = 42,
    fullUrl = "/products/1234",
    title = "Spring sale",
    description = "Up to 50% off this week only.",
    imageUrl = "https://example.com/images/spring-sale.png",
    fallbackUrl = "https://example.com/spring-sale",
});
response.EnsureSuccessStatusCode();
var link = await response.Content.ReadFromJsonAsync<LinkResponse>();
Console.WriteLine(link!.ShortUrl);

record LinkResponse(int Id, string FullUrl, string ShortUrl);

The response is the link: its id, shortUrl and fullUrl and what you sent. To pick the short code yourself, add customShortCode, such as a handle like jane.doe; a code in use answers 400. For a short URL on your custom domain, send fullUrl on that domain: https://link.example.com/products/1234.

Update and delete

PUT /api/links/{id} replaces every field of a link, so send the whole body again. DELETE /api/links/{id} deletes it for good, and its short URL stops working.

curl -X PUT https://dev.thedbl.ink/api/links/1001 \
  -H "Api-Key: $DBL_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{ "appId": 42, "fullUrl": "/products/1234", "title": "Spring sale, extended", "description": "", "imageUrl": "", "fallbackUrl": "" }'

curl -X DELETE https://dev.thedbl.ink/api/links/1001 -H "Api-Key: $DBL_API_KEY"

Handle errors

An error answers with its status, and a 400, 403 or 404 also with { "message": "..." }. The ones a backend should expect:

400 when a field is missing, a short code is taken, or the organization's links for the month are used up. A full quota lasts until the next month or a plan change, so retrying doesn't help; queue the link or alert your team.
401, with an empty body, when the key is wrong or was regenerated.

See Authentication for the full list.