API Documentation

Complete reference for integrating Trunc into your applications

Base URL

http://localhost:8080

Production: https://api.trunc.site

Authentication

Authorization: Bearer YOUR_KEY

API keys start with us_ prefix

Rate Limits

Standard1000/hour

Configurable per API key

Endpoints

Select an Endpoint

Choose an endpoint from the list to view detailed documentation and examples.

Integration Guide

Learn how to integrate Trunc into your applications

⚠️ Prerequisites

Before you can use the API, you need a Trunc account and an API key. You cannot register or login via the API. Account creation and API key generation must be done through the web interface.

Register on the Website

Visit trunc.site and create an account if you haven't already.

Login to Dashboard

Generate API Key

Navigate to Settings → API Keys and create a new API key with the required permissions.

🚀 Quick Start

Once you have your API key from the prerequisites above, follow these steps:

Copy Your API Key

After creating an API key in the dashboard, copy it immediately. You won't be able to see it again!

Store Securely

Save your API key in a secure location (environment variables, secrets manager, etc.). Never commit it to version control!

Make Your First Request

Use the code examples below to start shortening URLs programmatically!

Code Examples

📜 Vanilla JavaScript

JavaScript

async function shortenURL(originalUrl) {
  const response = await fetch('http://localhost:8080/api/v1/shorten', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': 'Bearer YOUR_API_KEY_HERE'
    },
    body: JSON.stringify({ url: originalUrl })
  });

  if (!response.ok) {
    throw new Error('Failed to shorten URL');
  }

  const data = await response.json();
  return data.short_url;
}

// Usage
shortenURL('https://example.com/very-long-url')
  .then(shortUrl => console.log('Shortened URL:', shortUrl))
  .catch(error => console.error('Error:', error));

🔐 Security Best Practices

⛔ Never Expose API Keys in Frontend Code

API keys should NEVER be included directly in your frontend JavaScript code or committed to version control.

✅ Use Environment Variables

Store API keys in environment variables:

TRUNC_API_KEY=us_your_api_key_here

✅ Implement a Backend Proxy

Create a backend endpoint that calls the Trunc API. Your frontend calls your backend, which securely stores the API key.

✅ Use Permission Scopes

Create API keys with only the permissions they need. Don't give full access if you only need URL shortening.

💡 Common Use Cases

📝

Blog Post Sharing

Automatically generate short URLs for blog posts to share on social media.

📧

Email Newsletters

Create trackable short links for email campaigns with custom UTM parameters.

🎯

Marketing Campaigns

Generate branded short URLs for marketing materials and track click performance.

📱

QR Code Generation

Create short URLs that are perfect for encoding in QR codes.