Developers

BigSavingsDays API v1

High-performance API for deal publishers, Telegram bots, and automated affiliate syndication.

Quickstart

Create a key in Dashboard → API, then make your first request. All endpoints are under https://bigsavingsdays.com/api/v1.

curl https://bigsavingsdays.com/api/v1/links \
  -H "Authorization: Bearer bsd_sk_your_key"

Authentication

Send your key as a bearer token. Keys are scoped to one workspace, shown once at creation, and stored as a SHA-256 hash.

Authorization: Bearer bsd_sk_...

Never put a key in client-side JavaScript or a public repository. Rotate immediately if a key leaks — revoking is instant.

Create a link

POST /api/v1/links — returns 201 with the created link. url is required; slug, title and tags are optional.

curl -X POST https://bigsavingsdays.com/api/v1/links \
  -H "Authorization: Bearer bsd_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/spring-sale",
    "slug": "spring",
    "title": "Spring sale",
    "tags": "campaign,email"
  }'

// 201 Created
{
  "id": "4f2a9c01",
  "slug": "spring",
  "url": "https://example.com/spring-sale",
  "shortUrl": "https://bigsavingsdays.com/spring",
  "created_at": 1770000000000
}

If the slug is taken you get 409. If it is reserved or malformed, 400. Omit it and BigSavingsDays generates a 7-character slug.

List & fetch

GET /api/v1/links?limit=50&offset=0 returns a stable, newest-first page with lifetime click counts. limit is capped at 200. The response includes total, limit and offset. GET /api/v1/links/:slug returns one link.

GET /api/v1/links?limit=50&offset=0
GET /api/v1/links/spring

Analytics

GET /api/v1/links/:slug/stats returns totals, a 30-day daily series, countries, devices and referrers.

{
  "data": {
    "totals": { "total": 4821, "period": 1830, "unique": 3920, "last": 1770000000000 },
    "daily": [{ "date": "2026-02-01", "label": "Feb 1", "value": 64 }],
    "countries": [{ "label": "India", "n": 1220, "pct": 34 }]
  }
}

Delete a link

DELETE /api/v1/links/:slug permanently removes a link and its click history.

curl -X DELETE https://bigsavingsdays.com/api/v1/links/spring \
  -H "Authorization: Bearer bsd_sk_..."

Errors

Errors always include an error string. We use conventional status codes:

400  Invalid body, url, slug or date
401  Missing or invalid API key
403  Plan limit reached
404  Link not found
409  Slug already taken
429  Rate limit exceeded

Rate limits

120 requests per minute per key, enforced with a fixed window stored in the same SQLite database, so limits survive restarts. Responses send X-RateLimit-Remaining; a 429 includes Retry-After.