Snai.ly API

Snai.ly provides a robust API for developers and power users who want to integrate URL shortening into their own applications, workflows, or scripts (like ShareX, Shortcuts, or custom bots).

1. Authentication & Access

Important: To ensure the security of our service, the Snai.ly API is not open to the public by default. We use a strict “Client Secret” system.

• Standard credentials (username/password) do NOT work.
• Standard YOURLS signatures found in your profile do NOT work.

How to get access

Please contact the Snai.ly team (via Discord or Email) to request API access. If approved, you will receive a unique Client Secret (starting with sk_...). Treat this key like a password.

Connection Methods

Once you have your key, there are two ways to connect.

Method A: The Secret Token (Preferred)

This is the standard method for modern apps, scripts, and mobile shortcuts. It works from any location (dynamic IP).

• Parameter: Add secret to your request URL.
• Value: Your unique sk_... key.

Example Request:

Bash

https://snai.ly/yourls-api.php?secret=sk_YOUR_KEY&action=shorturl&url=https://example.com

Method B: IP Whitelisting (Legacy)

Some older applications (or “native” integrations) do not allow you to add custom parameters like secret. In this case, ask the Snai.ly team to allowlist your IP address.

• Limitation: You can only connect from that specific location (e.g., your home office). If your IP changes, the API will block you.

2. API Endpoints

The base URL for all requests is: https://snai.ly/yourls-api.php

Shorten a URL

Create a new snai.ly link.

• Action: shorturl
• Parameters:
  • url: The long URL to shorten (required).
  • keyword: Custom slug (optional, e.g., my-link).
  • secret: Your API key.

JSON Response:

JSON

{
    "url": "https://snai.ly/example",
    "status": "success",
    "message": "https://snai.ly/example",
    "title": "Example Domain",
    "shorturl": "https://snai.ly/example",
    "statusCode": 200
}

Expand a URL

Get the original long URL from a snai.ly link.

• Action: expand
• Parameters:
  • shorturl: The full short link (e.g., https://snai.ly/abc).
  • secret: Your API key.

URL Statistics

Get click counts for a specific link.

• Action: url-stats
• Parameters:
  • shorturl: The full short link.
  • secret: Your API key.

3. Integration Examples

ShareX (Windows)

1. Open ShareX -> Destinations -> Custom Uploader Settings.
2. Click New and name it Snai.ly.
3. Request URL: https://snai.ly/yourls-api.php
4. Method: POST or GET
5. Arguments:
   • action: shorturl
   • url: {input}
   • format: json
   • secret: YOUR_SK_KEY_HERE
6. Response: Select json and enter paths shorturl.

cURL (Terminal)

Bash

curl "https://snai.ly/yourls-api.php?secret=sk_YOUR_KEY&action=shorturl&format=json&url=https://google.com"

4. Error Codes

If your integration isn’t working, check the HTTP response code:

• 403 Forbidden: Your secret is incorrect, or your IP is not whitelisted.
• 429 Too Many Requests: You are sending requests too fast (Rate Limited). Please slow down.