SnpurlAPI Reference

Snpurl API v1

Programmatically shorten URLs, manage links, and retrieve analytics. JSON API with API-key authentication.

vpn_key Get API Key No account? Sign up free →

Base URL

https://api.snpurl.com/v1

Auth

X-API-Key header

Format

JSON

Version

v1 (stable)

rocket_launch Quick Start

Two steps to shorten your first URL via the API.

Generate an API key

Go to Dashboard → API Keys and click New Key. Copy it immediately — it's shown only once.

Make your first request

curl -X POST https://api.snpurl.com/v1/shorten \
  -H "X-API-Key: snp_your_key" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/very/long/path"}'

lock Authentication

Pass your API key in the X-API-Key header on every request.

infoKeys are prefixed snp_. They are stored hashed — if you lose a key, revoke it and generate a new one.

# Add to every request
X-API-Key: snp_your_api_key_here

dns Base URL

All v1 endpoints are relative to this base URL. All request and response bodies use JSON.

# Production
https://api.snpurl.com/v1

# Local development
http://localhost:3009/v1

speed Rate Limits

Limits are enforced per API key and reset daily at midnight UTC.

Plan	Daily Limit	API Access	Use Case
Free	—	✗ Blocked	Upgrade to access the API
Basic	1,000 requests/day	✓ Enabled	Side projects, personal tools
Pro	10,000 requests/day	✓ Enabled	Production apps, integrations

Rate limit response headers

Header	Description
X-RateLimit-Limit	Your plan's daily request ceiling
X-RateLimit-Remaining	Requests remaining today
X-RateLimit-Reset	Unix timestamp when the counter resets (midnight UTC)

warningWhen the limit is exceeded the API returns 429 Too Many Requests. Implement exponential back-off and check X-RateLimit-Reset to know when to retry.

error_outline Error Codes

All errors return a JSON body with an error string.

Status	Meaning	Common cause
400	Bad Request	Missing required field or invalid value
401	Unauthorized	Missing or invalid `X-API-Key` header
403	Forbidden	Free plan key, or resource belongs to another user
404	Not Found	Resource does not exist
409	Conflict	Custom alias is already taken
429	Too Many Requests	Daily rate limit exceeded
500	Server Error	Something went wrong on our end

// 401 — invalid key
{
  "error": "Invalid or revoked API key"
}

// 429 — rate limit hit
{
  "error":  "Daily API rate limit exceeded. Resets at midnight UTC.",
  "limit":  1000,
  "used":   1000,
  "reset":  "2026-05-08T00:00:00.000Z"
}

Shorten URL

POST/v1/shorten

Creates a new short URL. Returns the short code, full short URL, and a delete token for later removal.

Request Body (JSON)

Field	Type		Description
url	string	required	The long URL to shorten
alias	string	optional	Custom short code — must be unique, alphanumeric + hyphens
expiry_date	string	optional	Link expiry — ISO date e.g. `2026-12-31`

Code Examples

curl -X POST https://api.snpurl.com/v1/shorten \
  -H "X-API-Key: snp_your_key" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/long/path","alias":"my-link","expiry_date":"2026-12-31"}'

Response — 201

{
  "id":           42,
  "short_url":    "https://snpurl.com/abc12345",
  "short_code":   "abc12345",
  "original_url": "https://your-long-url.com/path?query=value",
  "delete_token": "xK9mQ3nP7rLs",
  "expiry_date":  null,
  "created_at":   "2026-05-07T10:00:00.000Z"
}

List URLs

GET/v1/urls

Returns a paginated list of all short URLs belonging to the authenticated user.

Query Parameters

Param	Type	Default	Description
page	integer	1	Page number (1-based)
limit	integer	20	Items per page — max 100

Code Examples

curl "https://api.snpurl.com/v1/urls?page=1&limit=20" \
  -H "X-API-Key: snp_your_key"

Response — 200

{
  "data": [
    {
      "id":           42,
      "short_url":    "https://snpurl.com/abc12345",
      "short_code":   "abc12345",
      "original_url": "https://your-long-url.com",
      "click_count":  17,
      "delete_token": "xK9mQ3nP7rLs",
      "created_at":   "2026-05-07T10:00:00.000Z",
      "expiry_date":  null
    }
  ],
  "total": 84,
  "page":  1,
  "limit": 20
}

Delete URL

DELETE/v1/urls/:delete_token

Permanently deletes a short URL and all associated analytics. Use the delete_token from the create or list response.

delete_foreverThis action is irreversible. All click analytics for the URL will also be deleted.

Code Examples

curl -X DELETE \
  https://api.snpurl.com/v1/urls/xK9mQ3nP7rLs \
  -H "X-API-Key: snp_your_key"

Response — 200

{ "message": "URL deleted" }

URL Analytics

GET/v1/analytics/:id

Returns click logs for a URL (up to 1,000 most recent entries). Use the numeric id from the list or create response.

Path Parameter

Param	Type	Description
id	integer	Numeric URL id from create or list response

Code Examples

curl https://api.snpurl.com/v1/analytics/42 \
  -H "X-API-Key: snp_your_key"

Response — 200

{
  "url_id":       "42",
  "short_url":    "https://snpurl.com/abc12345",
  "total_clicks": 17,
  "logs": [
    {
      "clicked_at":   "2026-05-07T09:45:00.000Z",
      "ip_address":   "203.0.113.42",
      "device_type":  "mobile",
      "browser_name": "Chrome",
      "os_info":      "Android",
      "referer":      "https://twitter.com"
    }
  ]
}