Build with warplo

01Quick start

1. Create an API key in the API keys section below. It starts with wpl_ and is shown once.
2. Save it as an environment variable on your server or in CI:

   export WARPLO_API_KEY=wpl_your_key_here

3. Shorten a link from Node, or straight from your terminal:

   import { Warplo } from "warplo";
   
   const warplo = new Warplo();
   const link = await warplo.create({ url: "https://example.com/spring-sale", slug: "spring" });
   console.log(link.shortUrl); // https://warplo.link/spring

   npx warplo https://example.com/spring-sale --slug spring

02API keys

Keys act as your account, so keep them secret. Use them from servers, scripts and CI, never in a web page or an app people can download. If a key leaks, delete it here and it stops working straight away.

Checking your account…

03npm package

The warplo package has no dependencies and is fully typed. The SDK only needs fetch, which is built into Node 18 and later.

import { Warplo, WarploError } from "warplo";

const warplo = new Warplo({ apiKey: process.env.WARPLO_API_KEY });

// Shorten, with an optional ending and expiry
const link = await warplo.create({ url: "https://example.com/page", slug: "launch", expiresInDays: 30 });

// Just the short URL
const short = await warplo.shorten("https://example.com/other");

// Every link, page by page
for await (const l of warplo.links()) console.log(l.slug, l.url);

// Clicks by day and country (30 days by default, up to 90 on Free and 365 on Pro)
const stats = await warplo.stats("launch", { days: 90 });

// Delete
await warplo.delete("launch");

// Errors have a code you can check
try {
  await warplo.create({ url: "https://example.com", slug: "launch" });
} catch (err) {
  if (err instanceof WarploError && err.code === "slug_taken") {
    // try another slug
  }
}

// Calls left today, updated after each request
console.log(warplo.rateLimit); // { limit: 100, remaining: 96 }

04Command line

The same package includes a warplo command. It reads your key from WARPLO_API_KEY, or pass --key. Add --json for machine-readable output.

npx warplo https://example.com/a/very/long/page
npx warplo shorten example.com/launch --slug launch --expires 30
npx warplo list
npx warplo stats launch --days 90
npx warplo delete launch
npx warplo whoami

05REST API

Any language works. Send JSON to https://warplo.link with your key in the Authorization header. Every response says how many calls you have left today in X-RateLimit-Limit and X-RateLimit-Remaining.

curl https://warplo.link/api/links \
  -H "Authorization: Bearer $WARPLO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/page","slug":"launch","expiresInDays":30}'

{
  "slug": "launch",
  "shortUrl": "https://warplo.link/launch",
  "url": "https://example.com/page",
  "expiresAt": 1795219200
}

Each destination is checked against phishing and malware lists before the link is saved. Expiry times are Unix seconds; null means the link never expires.

06Limits

Daily calls reset at midnight UTC. Links created through the API count towards the same link limit as the dashboard. Need more? Upgrade to Pro or talk to us.

07Errors

Errors come back as JSON with an error code, and a limit when you've hit one: {"error":"link_limit","limit":50}. The npm package throws them as WarploError with the same code.