Guides

Quick Start Guides

Step-by-step tutorials to get you up and running with the Snipy API. Each guide includes code examples in cURL, JavaScript, and Python.

Guide 1

Shorten Your First Link

The simplest API call: create a short link from a long URL. This guide covers authentication, the request format, and handling the response.

Prerequisites

A Snipy account (any plan)
An API key or access token

cURL

curl -X POST https://api.snipy.com/api/url/add \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/my-long-page-url",
    "alias": "my-link",
    "domain": "snipy.to"
  }'

JavaScript

const response = await fetch("https://api.snipy.com/api/url/add", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_TOKEN",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    url: "https://example.com/my-long-page-url",
    alias: "my-link",
    domain: "snipy.to",
  }),
});

const result = await response.json();

if (result.error === 0) {
  console.log("Short URL:", result.data.shorturl);
  // => https://snipy.to/my-link
} else {
  console.error("Error:", result.message);
}

Python

import requests

response = requests.post(
    "https://api.snipy.com/api/url/add",
    headers={
        "Authorization": "Bearer YOUR_TOKEN",
        "Content-Type": "application/json",
    },
    json={
        "url": "https://example.com/my-long-page-url",
        "alias": "my-link",
        "domain": "snipy.to",
    },
)

result = response.json()

if result["error"] == 0:
    print("Short URL:", result["data"]["shorturl"])
else:
    print("Error:", result["message"])

Response

{
  "error": 0,
  "data": {
    "id": 456,
    "alias": "my-link",
    "shorturl": "https://snipy.to/my-link",
    "longurl": "https://example.com/my-long-page-url",
    "clicks": 0,
    "domain": "snipy.to",
    "date": "2026-03-04T12:00:00Z"
  }
}

Tip: Custom alias

If you omit the alias field, Snipy will auto-generate a random 6-character alias. Custom aliases require thecustom_alias plan feature (Starter plan and above).

Guide 2

Generate QR Codes via API

Create customized QR codes programmatically and download them in PNG, SVG, or PDF format.

Step 1: Create a QR code

cURL

curl -X POST https://api.snipy.com/api/qr/add \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Product Landing",
    "url": "https://example.com/product",
    "foreground": "#1a1a1a",
    "background": "#ffffff",
    "errorCorrection": "H",
    "size": 400
  }'

Step 2: Download the QR image

Download as PNG

curl -X GET "https://api.snipy.com/api/qr/78/download?format=png&size=600" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -o qr-code.png

Download as SVG

curl -X GET "https://api.snipy.com/api/qr/78/download?format=svg" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -o qr-code.svg

JavaScript: Create and download

// Create QR code
const createRes = await fetch("https://api.snipy.com/api/qr/add", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_TOKEN",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    name: "Product Landing",
    url: "https://example.com/product",
    foreground: "#1a1a1a",
    size: 400,
  }),
});

const { data: qr } = await createRes.json();
console.log("QR ID:", qr.id);

// Download as PNG
const downloadRes = await fetch(
  `https://api.snipy.com/api/qr/${qr.id}/download?format=png&size=600`,
  { headers: { "Authorization": "Bearer YOUR_TOKEN" } }
);

const buffer = await downloadRes.arrayBuffer();
// Save buffer to file or send to client

Customization options

Option	Default	Description
`foreground`	#000000	QR module color
`background`	#FFFFFF	Background color
`errorCorrection`	M	L (7%), M (15%), Q (25%), H (30%)
`size`	300	Output size in pixels
`margin`	4	Quiet zone modules

Guide 3

Track Clicks and Conversions

Use the analytics endpoints to retrieve click data, geographic distribution, referrer sources, and A/B test results for your links.

Get click summary

cURL

curl -X GET "https://api.snipy.com/api/url/456/stats?from=2026-01-01&to=2026-03-01" \
  -H "Authorization: Bearer YOUR_TOKEN"

Get time-series data for charts

JavaScript

// Fetch daily click data for the past 30 days
const from = new Date();
from.setDate(from.getDate() - 30);

const response = await fetch(
  `https://api.snipy.com/api/url/456/stats/clicks?` +
  `from=${from.toISOString()}&granularity=day`,
  { headers: { "Authorization": "Bearer YOUR_TOKEN" } }
);

const { data } = await response.json();

// data.clicks = [
//   { date: "2026-02-02", count: 45 },
//   { date: "2026-02-03", count: 52 },
//   ...
// ]

Geographic breakdown

Python

import requests

response = requests.get(
    "https://api.snipy.com/api/url/456/stats/countries",
    headers={"Authorization": "Bearer YOUR_TOKEN"},
)

countries = response.json()["data"]["countries"]
for country in countries:
    print(f"{country['name']}: {country['clicks']} clicks")

A/B test results

If you have set up A/B testing variants for a link, use the variants endpoint to see the performance of each variant.

cURL

curl -X GET https://api.snipy.com/api/url/456/stats/variants \
  -H "Authorization: Bearer YOUR_TOKEN"

Guide 4

Set Up Webhooks

Subscribe to real-time events so your application is notified the instant something happens in your Snipy account.

Step 1: Create your endpoint

Express.js

const express = require("express");
const crypto = require("crypto");
const app = express();

app.use(express.json());

const WEBHOOK_SECRET = process.env.SNIPY_WEBHOOK_SECRET;

app.post("/snipy/webhook", (req, res) => {
  // Verify signature
  const sig = req.headers["x-snipy-signature"];
  const hmac = crypto
    .createHmac("sha256", WEBHOOK_SECRET)
    .update(JSON.stringify(req.body))
    .digest("hex");

  if (sig !== hmac) {
    return res.status(401).json({ error: "Invalid signature" });
  }

  const { event, data } = req.body;

  switch (event) {
    case "link.clicked":
      console.log(`Link ${data.alias} clicked from ${data.country}`);
      break;
    case "subscriber.added":
      console.log(`New subscriber: ${data.email}`);
      break;
  }

  res.status(200).json({ received: true });
});

app.listen(3000);

Step 2: Subscribe via API

cURL

curl -X POST https://api.snipy.com/api/webhooks/subscribe \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://yourapp.com/snipy/webhook",
    "events": ["link.clicked", "link.created", "subscriber.added"],
    "secret": "whsec_my_secret_123"
  }'

Step 3: Test it

Create a short link to trigger the link.created event and verify your endpoint receives the payload.

Guide 5

Build a Custom Integration

This guide walks through building a complete integration that creates short links, attaches them to campaigns, monitors clicks via webhooks, and exports analytics.

Step 1: Create a campaign

const campaign = await fetch("https://api.snipy.com/api/campaign/add", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_TOKEN",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    name: "Product Launch 2026",
    description: "Q1 product launch tracking",
  }),
}).then(r => r.json());

const campaignId = campaign.data.id;

Step 2: Create links in the campaign

const links = [
  { url: "https://example.com/landing", alias: "launch-main" },
  { url: "https://example.com/pricing", alias: "launch-pricing" },
  { url: "https://example.com/demo", alias: "launch-demo" },
];

const created = await Promise.all(
  links.map(link =>
    fetch("https://api.snipy.com/api/url/add", {
      method: "POST",
      headers: {
        "Authorization": "Bearer YOUR_TOKEN",
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        ...link,
        domain: "snipy.to",
        campaignId,
        utm_source: "email",
        utm_campaign: "product-launch-2026",
      }),
    }).then(r => r.json())
  )
);

console.log("Created", created.length, "links");

Step 3: Subscribe to click events

await fetch("https://api.snipy.com/api/webhooks/subscribe", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_TOKEN",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    url: "https://yourapp.com/hooks/snipy",
    events: ["link.clicked", "link.expired"],
    secret: "whsec_your_secret",
  }),
});

Step 4: Pull campaign analytics

const stats = await fetch(
  `https://api.snipy.com/api/campaign/${campaignId}/stats?from=2026-01-01`,
  { headers: { "Authorization": "Bearer YOUR_TOKEN" } }
).then(r => r.json());

console.log("Campaign clicks:", stats.data.totalClicks);
console.log("Top country:", stats.data.topCountry);
console.log("Top referrer:", stats.data.topReferrer);