Quick Start

Overview

Plume URL is an API that allows you to create shortened URLs and retrieve them later.

All API endpoints follow the OpenAPI v3 specification and return data in JSON format.

API Versioning

Version	Base URL	Release Date	Deprecation Date
v1	https://url.sodiumlabs.xyz/api	08/03/2025	Not deprecated

Error Handling

You may encounter errors if you send an invalid or malformed request. Errors always use non-2XX status codes and typically contain a JSON object with a message field explaining the issue.

Common codes you may encounter are:

Code	Reason
400	Something with your request was invalid. The reason should be explained in the API docs or in the `message` field.
422	Validation of your query parameters failed. Required parameters are missing or invalid. Check the `errors` field in the response, which is an array of objects like `{ message: string }`.
429	You are being rate-limited. Wait before querying the API again.
5XX	The endpoint or the API is down. Try again later.

Rate Limits

Plume URL has a rate-limiting system to prevent abuse. Every response from the API includes three special headers so you know how close you are to the limit.

Header	Meaning
`X-Ratelimit-Limit`	The maximum number of requests you can make in the window.
`X-Ratelimit-Remaining`	The number of requests remaining until the next reset.
`X-Ratelimit-Reset`	Seconds until the `Remaining` count resets.

Please avoid making unnecessary requests to our API, as they can degrade service for other users.

How to use the API

If you are using JavaScript or TypeScript, check out the official NPM package

Here is a basic example to create a shortened URL:

import { PlumeURL } from "@sodiumlabs/plume-url";

const plumeURL = new PlumeURL({ apiKey: "YOUR-API-KEY" });

const data = await plumeURL.createURL({
    url: "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
    description: "A cool video"
});

console.log("Shortened URL:", data.shorten);

const response = await fetch("https://url.sodiumlabs.xyz/api/create", {
    headers: {
        "Authorization": "YOUR_API_KEY",
        "Content-Type": "application/json"
    },
    method: "POST",
    body: JSON.stringify({
        url: "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
        description: "A cool video"
    })
});

if(!response.ok) {
    throw new Error(response.statusText);
}

const data = await response.json();
console.log("Shortened URL:", data.shorten);

import requests
import json

api_url = "https://url.sodiumlabs.xyz/api/create"

headers = {
    "Authorization": "YOUR_API_KEY",
    "Content-Type": "application/json"
}

payload = {
    "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
    "description": "A cool video"
}

response = requests.post(api_url, headers=headers, data=json.dumps(payload))

if response.status_code != 200:
    raise Exception(response.reason)

data = response.json()
print("Shortened URL:", data["shorten"])

When you create a URL, you can add a customId in the body. It's a custom ID that can allow you to store data. In the case of a Discord bot, you can for example store the Discord ID of the user who created the URL, which later allows you to use the /search endpoint and filter with ?customId=user_id to retrieve URLs created by a specific user.

If you need more help, join the Discord.