API Documentation

Build with OrangeURL API

Integrate powerful URL shortening, analytics, and webhooks into your application. Get started in minutes with our comprehensive API.

Get API Key

Quick Start

1

Create an API Key

Generate your API key from the dashboard. Pro and Premium plans only.

Create Key
2

Make Your First Request

Use your API key to shorten URLs, retrieve analytics, and more.

View Examples
3

Set Up Webhooks

Receive real-time notifications when URLs are created or clicked.

Learn More

Authentication

Using API Keys

All API requests require authentication using an API key. Include your API key in the Authorization header or X-API-Key header.

Authorization Header (Recommended)
Authorization: Bearer oran_live_your_api_key_here
X-API-Key Header (Alternative)
X-API-Key: oran_live_your_api_key_here

Keep Your API Keys Secret

Never expose your API keys in client-side code, public repositories, or logs. Always use environment variables and secure storage.

Common Operations

Create Short URL

Shorten a URL with optional custom ID and expiration.

POST/api/v1/urlsurls:write
curl -X POST https://api.orangeurl.live/api/v1/urls \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/very-long-url",
    "custom_id": "my-link",
    "expiry": 24
  }'

Additional Endpoints

GET/api/v1/urls

List all your shortened URLs

urls:read
GET/api/v1/analytics/urls/:shortId

Get analytics for a specific URL

analytics:read
DELETE/api/v1/urls/:shortId

Delete a shortened URL

urls:write

Webhooks

Real-Time Event Notifications

Webhooks allow your application to receive real-time notifications when events occur in OrangeURL. Perfect for automation, analytics, and integrations.

url.created

Pro + Premium

Triggered when a new short URL is created

url.clicked

Pro + Premium

Triggered when someone clicks a short URL

url.deleted

Premium Only

Triggered when a short URL is deleted

url.expired

Premium Only

Triggered when a short URL expires

Tier Differences: Pro subscribers can use basic events (url.created, url.clicked). Premium subscribers get access to all events plus automatic retry logic for failed webhook deliveries.

Creating a Webhook

curl -X POST https://api.orangeurl.live/api/v1/webhooks \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://myapp.com/webhooks/orangeurl",
    "events": ["url.created", "url.clicked"]
  }'

Webhook Handler Example

Implement a webhook endpoint in your application to receive events. Always verify the signature to ensure the request is from OrangeURL.

// Express.js webhook handler
const crypto = require('crypto');

app.post('/webhooks/orangeurl', (req, res) => {
  // Verify webhook signature
  const signature = req.headers['x-orangeurl-signature'];
  const hmac = crypto.createHmac('sha256', WEBHOOK_SECRET);
  const digest = hmac.update(JSON.stringify(req.body)).digest('hex');

  if (signature !== digest) {
    return res.status(401).send('Invalid signature');
  }

  // Handle the event
  const { event, data } = req.body;

  switch(event) {
    case 'url.created':
      console.log('New URL created:', data.short_url);
      break;
    case 'url.clicked':
      console.log('URL clicked:', data.short_id);
      console.log('Location:', data.location);
      break;
  }

  res.status(200).send('OK');
});

Security Best Practices

  • Always verify webhook signatures before processing events
  • Store webhook secrets securely in environment variables
  • Use HTTPS endpoints only for webhook URLs
  • Implement retry logic for failed webhook deliveries

Rate Limits

API rate limits vary by subscription tier to ensure fair usage and system stability. API access is only available for Pro and Premium plans.

Pro

$5/month
Basic API Access
5,000

requests per hour

120,000 requests/month
2.4x more than Bitly Core ($8/mo)

  • Up to 5 API keys
  • Standard webhooks (url.created, url.clicked)
  • No webhook retry logic
RECOMMENDED

Premium

$15/month
Advanced API Access
20,000

requests per hour

480,000 requests/month
3.2x more than Bitly Enterprise

  • Unlimited API keys
  • All webhook events + retry logic
  • Priority API support
  • SLA guarantees

Free Plan: API access is not available on the Free plan. Upgrade to Pro or Premium to use the API.

Rate limit headers: Check the X-RateLimit-Limit and X-RateLimit-Remaining headers in API responses to monitor your usage.

Feature Comparison

FeatureProPremium
API Rate Limit5,000/hour20,000/hour
Monthly Requests~120,000~480,000
Max API Keys5Unlimited
Webhook Events2 basic eventsAll events
Webhook Retry Logic
Priority SupportStandard✓ Priority
SLA Guarantee✓ 99.9%
Custom Rate Limits✓ On request
Price$5/month$15/month

Additional Resources

Interactive API Reference

Try out all API endpoints with our Swagger UI documentation. Test requests in your browser.

Open Swagger Docs

Manage API Keys

Create, view, and manage your API keys. Configure permissions and set expiration dates.

Go to Dashboard