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.