WoNS REST API Documentation
Programmatically create, manage, and delete short links with sub-millisecond global resolution, custom domains, and automated SSL.
Base URL
https://api.wons.in/v1
Response Format
JSON (application/json)
Resolution Latency
< 2ms (Direct Index)
GET
/api/v1/...Authentication Header
Authenticate all requests by supplying your developer API key in either the x-api-key header or Authorization: Bearer header.
cURL Code
curl -X GET "https://api.wons.in/v1/links" \
-H "x-api-key: YOUR_API_KEY"HTTP Response
200
{
"success": true,
"count": 1,
"links": [
{
"domain": "wons.in",
"slug": "github",
"destination": "https://github.com",
"redirectType": 301,
"status": "active",
"clicks": 42
}
]
}GET
/api/v1/linksList All Short Links
Retrieve a list of short links. Optionally filter by custom domain or limit results.
Query Parameters
| Field | Type | Required | Description |
|---|---|---|---|
| domain | string | Optional | Filter links by domain (e.g. wons.in or link.subhm.in) |
| limit | number | Optional | Maximum number of items to return (default: 100) |
cURL Code
curl -X GET "https://api.wons.in/v1/links?domain=wons.in&limit=25" \
-H "x-api-key: YOUR_API_KEY"HTTP Response
200
{
"success": true,
"count": 2,
"links": [
{
"domain": "wons.in",
"slug": "github",
"destination": "https://github.com",
"redirectType": 301,
"status": "active",
"clicks": 128,
"createdAt": "2026-08-23T03:00:00.000Z"
},
{
"domain": "wons.in",
"slug": "docs",
"destination": "https://wons.in/docs",
"redirectType": 301,
"status": "active",
"clicks": 64,
"createdAt": "2026-08-23T03:05:00.000Z"
}
]
}POST
/api/v1/linksCreate Short Link
Create or update a short link. Redirections become active globally in under 2ms.
Request Body JSON
| Field | Type | Required | Description |
|---|---|---|---|
| slug | string | Required | Unique path slug (alphanumeric, hyphens) |
| destination | string | Required | Target destination URL |
| domain | string | Optional | Domain to attach (default: wons.in) |
| redirectType | number | Optional | HTTP redirect code: 301, 302, 307, 308 (default: 301) |
| status | string | Optional | active | disabled (default: active) |
| description | string | Optional | Optional internal memo/notes |
| tags | string[] | Optional | Array of tag strings |
cURL Code
curl -X POST "https://api.wons.in/v1/links" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{
"domain": "wons.in",
"slug": "promo2026",
"destination": "https://example.com/special-offer",
"redirectType": 301
}'HTTP Response
201
{
"success": true,
"link": {
"domain": "wons.in",
"slug": "promo2026",
"destination": "https://example.com/special-offer",
"redirectType": 301,
"status": "active",
"clicks": 0,
"createdAt": "2026-08-23T08:45:00.000Z"
},
"shortUrl": "https://wons.in/promo2026"
}GET
/api/v1/links/:slugGet Link Details
Retrieve real-time link information, destination URL, status, and click count.
Query Parameters
| Field | Type | Required | Description |
|---|---|---|---|
| domain | string | Optional | Domain name (default: wons.in) |
cURL Code
curl -X GET "https://api.wons.in/v1/links/promo2026?domain=wons.in" \
-H "x-api-key: YOUR_API_KEY"HTTP Response
200
{
"success": true,
"link": {
"domain": "wons.in",
"slug": "promo2026",
"destination": "https://example.com/special-offer",
"redirectType": 301,
"status": "active",
"clicks": 89,
"createdAt": "2026-08-23T08:45:00.000Z",
"updatedAt": "2026-08-23T08:45:00.000Z"
}
}PUT
/api/v1/links/:slugUpdate Short Link
Update destination URL, HTTP redirection code, status, or description.
Request Body JSON
| Field | Type | Required | Description |
|---|---|---|---|
| destination | string | Optional | New destination URL |
| status | string | Optional | active | disabled |
| redirectType | number | Optional | 301 | 302 | 307 | 308 |
| description | string | Optional | Updated memo |
cURL Code
curl -X PUT "https://api.wons.in/v1/links/promo2026" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{
"destination": "https://example.com/updated-offer",
"status": "active"
}'HTTP Response
200
{
"success": true,
"message": "Updated /promo2026"
}DELETE
/api/v1/links/:slugDelete Short Link
Permanently remove a short link from the database. Requests to this link immediately stop resolving and serve a 404 response.
Query Parameters
| Field | Type | Required | Description |
|---|---|---|---|
| domain | string | Optional | Domain name (default: wons.in) |
cURL Code
curl -X DELETE "https://api.wons.in/v1/links/promo2026?domain=wons.in" \
-H "x-api-key: YOUR_API_KEY"HTTP Response
200
{
"success": true,
"message": "Deleted /promo2026 successfully"
}GET
/api/v1/domainsList Custom Domains
Retrieve all configured custom domains, SSL status, and verification states.
cURL Code
curl -X GET "https://api.wons.in/v1/domains" \
-H "x-api-key: YOUR_API_KEY"HTTP Response
200
{
"success": true,
"domains": [
{
"domain": "wons.in",
"status": "active",
"verified": true,
"sslStatus": "active",
"isDefault": true
},
{
"domain": "link.subhm.in",
"status": "active",
"verified": true,
"sslStatus": "active",
"cnameTarget": "wons.in"
}
]
}POST
/api/v1/domainsAdd Custom Domain
Register a new custom domain or subdomain. Point your DNS CNAME record to wons.in for automated SSL provisioning.
Request Body JSON
| Field | Type | Required | Description |
|---|---|---|---|
| domain | string | Required | Fully-qualified domain name (e.g. link.subhm.in) |
| rootRedirect | string | Optional | Optional redirect URL for root path visitors |
cURL Code
curl -X POST "https://api.wons.in/v1/domains" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{
"domain": "link.subhm.in",
"rootRedirect": "https://subhm.in"
}'HTTP Response
201
{
"success": true,
"domain": {
"domain": "link.subhm.in",
"status": "active",
"verified": true,
"cnameTarget": "wons.in",
"rootRedirect": "https://subhm.in"
}
}