API Keys & Developer Integration 💻

Unlock the full power of Wonzly by integrating our high-performance link shortening engine directly into your own applications, scripts, and workflows.

Generating an API Key

To authenticate your requests against the Wonzly API, you will need a secure API Key.

1. Log into your Wonzly Web Dashboard.
2. Navigate to Settings > API & Developers.
3. Click the Generate New Key button.
4. Securely copy your new key.

Warning: Your API key is a secret token that grants access to your account. Never commit it to public repositories (like GitHub) or expose it in client-side code. If your key is compromised, immediately revoke it from the dashboard and generate a new one.

Understanding API Credits

To protect our infrastructure and provide a fair ecosystem, the Wonzly API operates on a credit-based system.

• Every successful request to create a short link consumes 1 API Credit.
• If your account balance reaches 0 credits, the API will reject requests with a 402 Payment Required status until you top up your wallet.

You can monitor your remaining API credits in real-time from the API dashboard.

Basic Usage (cURL Example)

Shortening a link programmatically is extremely simple. You just need to send a POST request to our /api/links/shorten endpoint, passing your API key in the headers.

Here is an example using standard curl via the command line:

bash
Copy
curl -X POST "https://your-wonzly-domain.com/api/links/shorten" \
     -H "Content-Type: application/json" \
     -H "x-api-key: YOUR_SECRET_API_KEY_HERE" \
     -d '{"originalUrl": "https://example.com/very-long-url-to-shorten"}'

Expected Response

If successful, the API will respond with a 200 OK and a JSON payload containing your new short link data:

json
Copy
{
  "status": "success",
  "data": {
    "shortCode": "AbC123x",
    "shortUrl": "https://wonzly.com/AbC123x",
    "originalUrl": "https://example.com/very-long-url-to-shorten"
  }
}

Advanced Features via API

The API is fully featured and supports all advanced link attributes. You can pass the following optional parameters in your JSON payload:

• customAlias (string): Request a specific back-half for your link (e.g., summer-sale).
• password (string): Automatically encrypt and password-protect the generated link.
• domain (string): Specify which of your custom domains to use for this link.

bash
Copy
curl -X POST "https://your-wonzly-domain.com/api/links/shorten" \
     -H "Content-Type: application/json" \
     -H "x-api-key: YOUR_SECRET_API_KEY_HERE" \
     -d '{
           "originalUrl": "https://example.com/very-long-url-to-shorten",
           "customAlias": "vip-promo",
           "password": "super-secret-password"
         }'

Error Handling

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

• 200 OK: The request was successful.
• 400 Bad Request: The JSON body is malformed or the originalUrl is invalid.
• 401 Unauthorized: No API key was provided or the API key is invalid.
• 402 Payment Required: You have exhausted your API Credits.
• 403 Forbidden: Your account plan limit has been reached, or the custom domain is unauthorized.
• 409 Conflict: The requested customAlias is already taken.