Webb.in Developer API

Programmatically create, manage, and track short URLs with the Webb.in REST API. Build integrations, automate URL management, and embed URL shortening into your applications.

🔗

RESTful API

Standard JSON requests & responses with predictable resource-oriented URLs.

⚡

Fast & Reliable

Built on enterprise serverless infrastructure with global edge caching for sub-50ms redirects.

📊

Rich Analytics

Track clicks, referrers, and daily trends for every short URL you create.

Base URL

https://api.webb.in/api/v1

All API endpoints are relative to this base URL.

Authentication

Authenticate with the API using an API key. Include your key in the Authorization header of every request:

Authorization: Bearer sk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Getting your API key: Sign in to your Developer Dashboard and generate a new key. You can create up to 5 keys per account.

Key format: All API keys start with sk_live_ followed by 32 characters.

Keep your API key secure

Never expose your API key in client-side code, public repositories, or browser requests. Always use it server-side. If a key is compromised, revoke it immediately from your dashboard.

Rate Limits

API requests are rate-limited based on your account quota. Every response includes headers to help you track your usage:

Header	Description
`X-RateLimit-Limit`	Maximum requests allowed per day
`X-RateLimit-Remaining`	Requests remaining in the current window
`X-RateLimit-Reset`	UTC timestamp when the limit resets (midnight UTC)

When you exceed your rate limit, the API returns a 429 Too Many Requests status. Default quota is 100 URLs per day. Contact us if you need a higher limit.

Error Handling

All API responses use a consistent envelope format. Errors include a machine-readable code and a human-friendly message.

Response

{
  "success": false,
  "error": {
    "code": "INVALID_URL",
    "message": "The provided URL is not valid."
  }
}

Error Codes

Code	HTTP Status	Description
`INVALID_URL`	400	The target URL is not valid or is missing
`PATH_EXISTS`	409	The requested custom path is already taken
`URL_NOT_FOUND`	404	Short URL not found or you do not own it
`QUOTA_EXCEEDED`	429	Daily quota has been exhausted
`INVALID_API_KEY`	401	API key is missing, invalid, or revoked
`FORBIDDEN`	403	You do not have access to this resource
`BULK_LIMIT`	400	Bulk request exceeds max of 100 URLs
`INTERNAL_ERROR`	500	An unexpected server error occurred

Endpoints

Complete reference for all API endpoints.

Method	Endpoint	Description
POST	`/urls`	Create a short URL
GET	`/urls`	List your URLs
GET	`/urls/{domain}/{path}`	Get URL details
PATCH	`/urls/{domain}/{path}`	Update a URL
DELETE	`/urls/{domain}/{path}`	Delete a URL
GET	`/urls/{domain}/{path}/stats`	Get click statistics
POST	`/urls/bulk`	Create multiple URLs
GET	`/account`	Get account info & quota

Create Short URL

POST/urls

Create a new short URL. If customPath is not specified, a random short code will be generated.

Request Body

Name	Type	Required	Description
`url`	string	Required	The destination URL to shorten
`customPath`	string	Optional	Custom short path (3-50 chars, alphanumeric + hyphens)
`title`	string	Optional	A descriptive title for the URL
`domain`	string	Optional	Domain to use (default: webb.in)

Response

{
  "success": true,
  "data": {
    "domain": "webb.in",
    "path": "my-link",
    "shortUrl": "https://webb.in/my-link",
    "targetUrl": "https://example.com/very/long/path",
    "title": "My Example Link",
    "clickCount": 0,
    "isActive": true,
    "createdAt": "2025-01-15T10:30:00Z"
  }
}

List URLs

GET/urls

Retrieve a paginated list of your short URLs.

Query Parameters

Name	Type	Required	Description
`limit`	integer	Optional	Number of results per page (default: 20, max: 100)
`offset`	integer	Optional	Number of results to skip (default: 0)

Response

{
  "success": true,
  "data": {
    "urls": [{ "domain": "webb.in", "path": "my-link", "shortUrl": "https://webb.in/my-link", "targetUrl": "https://example.com/very/long/path", "title": "My Example Link", "clickCount": 142, "isActive": true, "createdAt": "2025-01-15T10:30:00Z" }],
    "pagination": { "total": 47, "limit": 20, "offset": 0, "page": 1, "totalPages": 3 }
  }
}

Get URL Details

GET/urls/{domain}/{path}

Retrieve details for a specific short URL including click count and metadata.

Path Parameters

Name	Type	Required	Description
`domain`	string	Required	The domain (e.g., webb.in or your custom domain)
`path`	string	Required	The short path

Response

{
  "success": true,
  "data": { "domain": "webb.in", "path": "my-link", "shortUrl": "https://webb.in/my-link", "targetUrl": "https://example.com/very/long/path", "title": "My Example Link", "clickCount": 142, "isActive": true, "createdAt": "2025-01-15T10:30:00Z" }
}

Update URL

PATCH/urls/{domain}/{path}

Update the target URL, title, or active status of an existing short URL.

Request Body

Name	Type	Required	Description
`targetUrl`	string	Optional	New destination URL
`title`	string	Optional	New title
`isActive`	boolean	Optional	Enable or disable the URL

Response

{
  "success": true,
  "data": { "domain": "webb.in", "path": "my-link", "shortUrl": "https://webb.in/my-link", "targetUrl": "https://new-destination.com", "title": "Updated Title", "clickCount": 142, "isActive": true, "createdAt": "2025-01-15T10:30:00Z" }
}

Delete URL

DELETE/urls/{domain}/{path}

Permanently delete a short URL. This action cannot be undone. The short path will become available for reuse.

Response

{
  "success": true,
  "data": { "message": "URL deleted successfully" }
}

URL Statistics

GET/urls/{domain}/{path}/stats

Retrieve click analytics for a short URL, including daily click counts and top referrers.

Query Parameters

Name	Type	Required	Description
`days`	integer	Optional	Number of days of history (default: 7, max: 90)

Response

{
  "success": true,
  "data": {
    "domain": "webb.in", "path": "my-link", "totalClicks": 1247,
    "dailyClicks": [{ "date": "2025-01-15", "clicks": 89 }, { "date": "2025-01-14", "clicks": 156 }, { "date": "2025-01-13", "clicks": 72 }],
    "topReferrers": [{ "referrer": "twitter.com", "clicks": 523 }, { "referrer": "github.com", "clicks": 312 }, { "referrer": "direct", "clicks": 198 }]
  }
}

Bulk Create URLs

POST/urls/bulk

Create multiple short URLs in a single request. Maximum 100 URLs per request. Partial failures are supported.

Request Body

Name	Type	Required	Description
`urls`	array	Required	Array of URL objects to create (max 100)
`urls[].url`	string	Required	Destination URL
`urls[].customPath`	string	Optional	Custom short path
`urls[].title`	string	Optional	URL title

Response

{
  "success": true,
  "data": {
    "succeeded": [{ "domain": "webb.in", "path": "abc123", "shortUrl": "https://webb.in/abc123", "targetUrl": "https://example.com/page1", "title": "Page 1" }],
    "failed": [{ "url": "not-a-valid-url", "error": "INVALID_URL", "message": "The provided URL is not valid." }],
    "total": 3, "successCount": 2, "failureCount": 1
  }
}

Account Information

GET/account

Retrieve your account details, quota information, and usage statistics.

Response

{
  "success": true,
  "data": {
    "username": "john", "email": "john@example.com", "createdAt": "2025-01-01T00:00:00Z",
    "quota": { "dailyLimit": 100, "todayUsage": 47, "remaining": 53, "resetAt": "2025-01-16T00:00:00Z" },
    "usage": { "totalUrls": 234, "totalClicks": 15678, "activeUrls": 198 }
  }
}

SDKs & Libraries

Official SDKs are coming soon. In the meantime, the API is simple enough to use with any HTTP client in your preferred language.

Building an SDK?

If you build an open-source SDK or library for Webb.in, we would love to feature it here! Reach out at hello@webb.in.