BYSL API
Documentation
Version 1.2.0.1 | Effective: April 20, 2026

Build powerful applications with our comprehensive URL shortening API. Simple, fast, and reliable with advanced analytics.

Quick Start View Examples

Navigation

Need Help?

Get support from our team

Contact Support →

Getting Started

Welcome to the BYSL API! Our RESTful API allows you to create, manage, and track short URLs programmatically with enterprise-grade reliability.

Simple & Fast

Get started in minutes with our intuitive REST API

Rich Analytics

Detailed insights and real-time tracking

Secure

Enterprise-grade security and reliability

Base URL

Production Endpoint
https://bysl.pw/api

Rate Limits

API Limits

100 requests per hour
Default limit per API Key
Unlimited short URLs

💡 Rate limits are applied per API key. Email [email protected] if you need higher limits (14 business days response).

Response Format

All API responses are returned in JSON format with a consistent structure for easy parsing and error handling.

Standard Response 
{
  "success": true,
  "data": {
    // Response data
  },
  "message": "Success message",
  "meta": {
    // Pagination and metadata
  }
}

Authentication

The BYSL API uses API keys for authentication. You can generate and manage your API keys from your dashboard.

Keep your API key secure

Never expose your API key in client-side code or public repositories.

Verified Email Requirement

As of Version 1.2.0.1, your account must have a verified email address. If your email is unverified, all API requests will return a 403 Forbidden error.

API Key Authentication

Include your API key in the request headers:

curl -H "X-API-Key: your_api_key_here" \
     -H "Content-Type: application/json" \
     https://bysl.pw/api/links

Header Authentication

X-API-Key: your_api_key

Query Parameter

?api_key=your_api_key

API Key Scopes

API keys can be restricted to specific permissions (scopes). Ensure your key has the correct scope for the endpoint you are calling:

Scope Description
links:read Permission to list and view your short links.
links:write Permission to create, update, and delete short links.
analytics:read Permission to view click statistics and analytics.

API Reference

Links

POST /api/links
Create a short link

Request Body

{
  "original_url": "https://example.com/very/long/path",
  "title": "Example Website",
  "custom_code": "my-example-link"
}

Response

{
  "success": true,
  "message": "Short link created successfully",
  "data": {
    "id": 123,
    "bysl_id": "abc123",
    "short_code": "my-example-link",
    "short_url": "https://bysl.pw/my-example-link",
    "original_url": "https://example.com/very/long/path",
    "title": "Example Website",
    "click_count": 0,
    "qr_code_url": "https://bysl.pw/qr/my-example-link",
    "created_at": "2026-03-29T00:00:00.000000Z"
  }
}
GET /api/links
List your links

Query Parameters

Parameter Type Description
page integer Page number (default: 1)
per_page integer Items per page (max: 100)
search string Search in title or URL

Response

{
  "success": true,
  "data": [
    {
      "id": 123,
      "short_code": "my-example-link",
      "short_url": "https://bysl.pw/my-example-link",
      "original_url": "https://example.com/very/long/path",
      "title": "Example Website"
    }
  ],
  "meta": {
    "current_page": 1,
    "last_page": 5,
    "per_page": 15,
    "total": 75
  }
}
PUT /api/links/{short_code}
Update a link

Request Body

{
  "original_url": "https://example.com/new/path",
  "title": "Updated Website Title",
  "is_active": true
}

Note: The custom_code cannot be updated once a shortlink is created.

Response

{
  "success": true,
  "message": "Short link updated successfully"
}
POST /api/links/{short_code}/toggle
Enable or disable a link

Response

{
  "success": true,
  "message": "Short link status updated successfully",
  "data": {
    "is_active": false
  }
}
DELETE /api/links/{short_code}
Delete a link

Response

{
  "success": true,
  "message": "Short link deleted successfully"
}
POST /api/bulk-shorten
Create multiple short links at once

Request Body

{
  "links": [
    {
      "original_url": "https://google.com",
      "title": "Google"
    },
    {
      "original_url": "https://github.com",
      "title": "GitHub",
      "custom_code": "my-gh-link"
    }
  ]
}

Response

{
  "success": true,
  "count": 2,
  "data": [ ... ]
}

Analytics

GET /api/analytics/overview
Get analytics overview

Response

{
  "success": true,
  "data": {
    "overview": {
      "total_links": 150,
      "total_clicks": 2500,
      "active_links": 140,
      "clicks_today": 45
    },
    "top_links": [
      {
        "id": 123,
        "short_code": "example",
        "title": "Example Website",
        "click_count": 500
      }
    ]
  }
}
GET /api/analytics/links/{short_code}
Get link analytics
GET /api/analytics/clicks
Get click analytics
GET /api/analytics/countries
Get country analytics
GET /api/analytics/devices
Get device analytics
GET /api/analytics/browsers
Get browser analytics

Account

GET /api/account
Get account information

Response

{
  "success": true,
  "data": {
    "user": {
      "id": 1,
      "name": "John Doe",
      "email": "[email protected]",
      "created_at": "2024-01-01T00:00:00Z"
    },
    "subscription": {
      "plan": "pro",
      "status": "active",
      "expires_at": "2024-12-31T23:59:59Z"
    }
  }
}
GET /api/account/usage
Get API usage statistics

Response

{
  "success": true,
  "data": {
    "current_period": {
      "requests": 45,
      "limit": 100,
      "percentage": 45.0,
      "reset_at": "2024-02-01T00:00:00Z"
    },
    "daily_usage": [
      {
        "date": "2024-01-15",
        "requests": 45
      }
    ],
    "weekly_usage": 180,
    "monthly_usage": 650
  }
}
GET /api/account/api-keys
List API keys

Response

{
  "success": true,
  "data": [
    {
      "id": 1,
      "name": "Production API Key",
      "key": "bysl_***************",
      "is_active": true,
      "permissions": ["links:create", "links:read", "analytics:read"],
      "rate_limit": 100,
      "current_usage": 45,
      "last_used_at": "2024-01-15T10:30:00Z",
      "created_at": "2024-01-01T00:00:00Z"
    }
  ]
}

System & Public

GET /api/info/{short_code}
Get public link information

Returns basic information about a short link. This endpoint does not require authentication.

Response

{
  "success": true,
  "data": {
    "short_code": "my-link",
    "original_url": "https://example.com",
    "title": "Example",
    "is_active": true
  }
}
GET /api/stats/public
Get platform statistics

Response

{
  "total_links": 15420,
  "total_clicks": 890532,
  "active_users": 1205
}
GET /api/health
API Health Check

Response

{
  "status": "ok",
  "timestamp": "2026-04-20T08:00:00Z",
  "version": "1.2.0.1"
}

Code Examples

cURL

# Create a short link
curl -X POST https://bysl.pw/api/links \
  -H "X-API-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com",
    "title": "Example Website"
  }'

# Get your links
curl -X GET https://bysl.pw/api/links \
  -H "X-API-Key: your_api_key_here"

JavaScript

// Create a short link
const response = await fetch('https://bysl.pw/api/links', {
  method: 'POST',
  headers: {
    'X-API-Key': 'your_api_key_here',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    url: 'https://example.com',
    title: 'Example Website'
  })
});

const data = await response.json();
console.log(data);

Python

import requests

# Create a short link
url = 'https://bysl.pw/api/links'
headers = {
    'X-API-Key': 'your_api_key_here',
    'Content-Type': 'application/json'
}
data = {
    'url': 'https://example.com',
    'title': 'Example Website'
}

response = requests.post(url, headers=headers, json=data)
result = response.json()
print(result)

PHP

<?php

$url = 'https://bysl.pw/api/links';
$data = [
    'url' => 'https://example.com',
    'title' => 'Example Website'
];

$options = [
    'http' => [
        'header' => [
            'X-API-Key: your_api_key_here',
            'Content-Type: application/json'
        ],
        'method' => 'POST',
        'content' => json_encode($data)
    ]
];

$context = stream_context_create($options);
$result = file_get_contents($url, false, $context);
$response = json_decode($result, true);

print_r($response);

Error Codes

The BYSL API uses conventional HTTP response codes to indicate the success or failure of an API request.

Code Status Description
200 OK The request was successful
201 Created The resource was successfully created
400 Bad Request The request was invalid or cannot be served
401 Unauthorized Authentication failed or API key is invalid
403 Forbidden Access denied or insufficient permissions
404 Not Found The requested resource was not found
422 Unprocessable Entity Validation errors in request data
429 Too Many Requests Rate limit exceeded
500 Internal Server Error Something went wrong on our end

Error Response Format

{
  "success": false,
  "message": "Validation failed",
  "errors": {
    "url": [
      "The url field is required."
    ]
  }
}