Brazeno.com

Introduction

The URL Shortener API is built to support high-volume link generation for marketing, transactional, and support use cases. Each short URL maintains a persistent mapping to the original long URL and can be configured to expire after a defined period.

Use cases include:

• Embedding compact links in SMS, email, and push notifications.
• Tracking campaign engagement across multiple channels.
• Delivering short-lived links for password resets or one-time offers.

Base URL & Environments

All requests are sent to the Brazeno API endpoint:

https://api.brazeno.com/api/v1

URL Shortener endpoints live under the /url namespace.

Authentication

All requests require an API key in the x-api-key header.

Getting Your API Key

1. Contact your Brazeno representative
2. Request API access for your project
3. Receive your API key via secure communication
4. Store the API key securely in your application

Example Header:

x-api-key: YOUR_API_KEY

Requests without a valid key return 401 Unauthorized. Reach out to your Brazeno representative if you need to rotate or request a new key.

Create Short URL

Generate a short URL that redirects to the destination defined in the body. Create branded, trackable short links with customizable TTL, custom domains, and analytics tracking for enterprise-grade link management.

Endpoint

POST /url/shorten

Request Headers

Request Body

Sample Request

curl --location 'https://api.brazeno.com/api/v1/url/shorten' \
--header 'x-api-key: YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data '{
    "long": "https://example.com/products/launch?campaign=summer",
    "ttl": 31536000
}'

Sample Response

{
    "short": "https://link.brazeno.test/AbCd1234",
    "shortCode": "AbCd1234",
    "customDomain": "link.brazeno.test",
    "long": "https://example.com/products/launch?campaign=summer",
    "createdAt": "2025-01-15T12:00:00.000Z",
    "custom": false,
    "urlId": "11111111-2222-3333-4444-555555555555"
}

Response Fields

Redirect & Expand

Short URLs perform an HTTP redirect to the configured long URL. To resolve a short link, request the short domain plus the short code:

GET http://{customDomain}/{shortCode}

Example:

GET http://link.brazeno.test/AbCd1234

The service issues a 301 or 302 redirect (depending on configuration) to the original URL. Applications should follow redirects to reach the destination.

When using a custom alias, replace {shortCode} with your chosen identifier.

Link Options & TTL

By default, shortened URLs inherit the account-level expiry policy. Override the duration per link by supplying the ttl field in seconds. For example, 31536000 seconds equals 365 days.

Additional considerations:

• Expired links return 404 Not Found.
• Custom domains must be verified by Brazeno before use.

Short URL Stats

Retrieve the current configuration and usage metrics for an existing short code.

Endpoint

GET /url/{shortCode}/stats

Request Headers

Sample Request

curl --location 'https://api.brazeno.com/api/v1/url/AbCd1234/stats' \
--header 'x-api-key: YOUR_API_KEY'

Sample Response

{
    "short": "AbCd1234",
    "long": "https://example.com/products/launch?campaign=summer",
    "createdAt": "2025-01-15T11:45:00.000Z",
    "customDomain": "link.brazeno.test",
    "divisionId": "22222222-3333-4444-5555-666666666666",
    "companyId": "77777777-8888-9999-aaaa-bbbbbbbbbbbb",
    "ttl": 31536000,
    "clickCount": 12,
    "lastAccessed": "2025-02-01T09:30:00.000Z"
}

Response Fields

Error Responses

400 Bad Request

{
    "message": "The long URL is required"
}

401 Unauthorized

{
    "message": "API key is missing or invalid"
}

404 Not Found

{
    "message": "Short code not found"
}

429 Too Many Requests

{
    "message": "Rate limit exceeded"
}

500 Internal Server Error

{
    "message": "An unexpected error occurred"
}

Best Practices

URL Management

• Validate URLs: Validate long URLs on the client side to avoid unnecessary API calls
• Store identifiers: Store the urlId for future analytics, auditing, or deletion workflows
• Use HTTPS: Use HTTPS when sharing short links to preserve referrer data and user trust
• Custom domains: Leverage custom domains to align links with your brand and improve deliverability
• Monitor usage: Track click rates and engagement metrics for optimization

Security

• API key management: API keys are provided by Brazeno representatives and should be kept out of client-side code
• URL validation: Sanitize and validate destination URLs to prevent malicious redirects
• Access controls: Implement proper access controls for link management
• Audit logging: Log all link creation and access for security monitoring
• Contact Brazeno for key rotation: Contact your representative for API key rotation or security concerns

Performance

• Batch operations: Use bulk operations when creating multiple links
• Cache responses: Cache short URL mappings to reduce API calls
• Monitor TTL: Set appropriate TTL values based on use case
• Error handling: Implement proper retry logic for failed requests

Code Examples

Ready-to-use code examples in popular programming languages to help you get started quickly.

Node.js

const axios = require('axios');

const shortenUrl = async (longUrl, ttl = null, customDomain = null) => {
  try {
    const response = await axios.post('https://api.brazeno.com/api/v1/url/shorten', {
      long: longUrl,
      ttl: ttl,
      customDomain: customDomain
    }, {
      headers: {
        'x-api-key': process.env.BRAZENO_API_KEY,
        'Content-Type': 'application/json'
      }
    });
    
    console.log('URL shortened successfully:', response.data);
    return response.data;
  } catch (error) {
    console.error('Error shortening URL:', error.response?.data || error.message);
    throw error;
  }
};

// Usage
shortenUrl('https://example.com/very/long/url/with/parameters', 86400)
  .then(result => console.log('Short URL:', result.short))
  .catch(error => console.error('Failed to shorten URL:', error));

Python

import requests
import os
from datetime import datetime

def shorten_url(long_url, ttl=None, custom_domain=None):
    url = 'https://api.brazeno.com/api/v1/url/shorten'
    headers = {
        'x-api-key': os.getenv('BRAZENO_API_KEY'),
        'Content-Type': 'application/json'
    }
    data = {
        'long': long_url,
        'ttl': ttl,
        'customDomain': custom_domain
    }
    
    try:
        response = requests.post(url, headers=headers, json=data)
        response.raise_for_status()
        return response.json()
    except requests.exceptions.RequestException as e:
        print(f'Error shortening URL: {e}')
        if hasattr(e, 'response') and e.response is not None:
            print(f'Response: {e.response.text}')
        raise

# Usage
try:
    result = shorten_url('https://example.com/very/long/url/with/parameters', ttl=86400)
    print(f'Short URL: {result["short"]}')
except Exception as e:
    print(f'Failed to shorten URL: {e}')

PHP

 $longUrl,
        'ttl' => $ttl,
        'customDomain' => $customDomain
    ];
    
    $options = [
        'http' => [
            'header' => [
                'x-api-key: ' . $apiKey,
                'Content-Type: application/json'
            ],
            'method' => 'POST',
            'content' => json_encode($data)
        ]
    ];
    
    $context = stream_context_create($options);
    $result = file_get_contents($url, false, $context);
    
    if ($result === FALSE) {
        throw new Exception('Failed to shorten URL request');
    }
    
    $response = json_decode($result, true);
    if (json_last_error() !== JSON_ERROR_NONE) {
        throw new Exception('Invalid JSON response: ' . json_last_error_msg());
    }
    
    return $response;
}

// Usage
try {
    $result = shortenUrl('https://example.com/very/long/url/with/parameters', 86400);
    echo 'Short URL: ' . $result['short'] . PHP_EOL;
} catch (Exception $e) {
    echo 'Error: ' . $e->getMessage() . PHP_EOL;
}
?>

cURL

# Basic URL shortening
curl -X POST 'https://api.brazeno.com/api/v1/url/shorten' \
  -H 'x-api-key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "long": "https://example.com/very/long/url/with/parameters",
    "ttl": 86400
  }'

# With custom domain
curl -X POST 'https://api.brazeno.com/api/v1/url/shorten' \
  -H 'x-api-key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "long": "https://example.com/very/long/url/with/parameters",
    "ttl": 31536000,
    "customDomain": "links.yourdomain.com"
  }'