# tny.dev

> URL shortener API with analytics, custom domains, and webhook support. Create short links programmatically with our developer-friendly API.

tny.dev is a URL shortening service that offers both free and paid tiers. Our API allows developers to create short links, track analytics, use custom domains, and receive webhook notifications for link events.

## API Documentation

- [Getting Started](https://www.tny.dev/api-docs#getting-started): Quick start guide, API key setup, and basic examples
- [Authentication](https://www.tny.dev/api-docs#authentication): API key authentication and security best practices
- [Create Short Link](https://www.tny.dev/api-docs#create-short-link): POST /api/v1/shorten - Create a shortened URL
- [Bulk Shorten](https://www.tny.dev/api-docs#bulk-shorten): POST /api/v1/shorten/bulk - Create multiple shortened URLs (Developer tier)
- [List Links](https://www.tny.dev/api-docs#list-links): GET /api/v1/links - List all links created with your API key
- [Get Analytics](https://www.tny.dev/api-docs#get-analytics): GET /api/v1/analytics/{slug} - Retrieve comprehensive analytics data
- [Webhooks](https://www.tny.dev/api-docs#webhooks): Real-time notifications for link events (Developer tier)
- [Custom Slugs](https://www.tny.dev/api-docs#custom-slugs): Create memorable, branded short links (Developer tier)
- [Custom Domains](https://www.tny.dev/api-docs#custom-domains): Use your own domain for short links (Developer tier)

## Key Features

- **Free Tier**: 50 requests/hour, 2 API keys, basic analytics
- **Developer Tier**: 500 requests/hour, 5 API keys, custom domains, custom slugs, bulk operations, webhooks
- **Safety**: All URLs checked against Google Web Risk API for malware and phishing
- **Analytics**: Device types, browsers, countries, referrers, UTM parameters, hourly click data
- **Tracking**: Automatic tracking of clicks, QR scans, and link previews

## API Endpoints

### Core Endpoints

- **POST /api/v1/shorten**: Create a short link
  - Required: url (string) - The URL to shorten
  - Optional: customSlug (string), domain_id (string) - Developer tier only
  - Returns: short_url, slug, long_url, created_at

- **GET /{slug}**: Redirect to original URL and track click
  - Public endpoint, no authentication required
  - Returns 301 redirect or 404 if not found

- **POST /api/v1/shorten/bulk**: Create multiple links (Developer tier)
  - Required: links array (max 100)
  - Each link: url (required), customSlug (optional), domain_id (optional)

- **GET /api/v1/links**: List your created links
  - Query params: page (number), limit (number, max 100)
  - Returns paginated list with click counts

- **GET /api/v1/analytics/{slug}**: Get detailed analytics
  - Returns: total clicks, devices, countries, referrers, hourly data, recent clicks

### Webhook Endpoints (Developer Tier)

- **GET /api/v1/webhooks**: List all webhooks
- **POST /api/v1/webhooks**: Create webhook
- **GET /api/v1/webhooks/{id}**: Get webhook details
- **PUT /api/v1/webhooks/{id}**: Update webhook
- **DELETE /api/v1/webhooks/{id}**: Delete webhook

## Error Codes

- **400**: Bad Request - Invalid URL, unsafe content, or invalid request body
- **401**: Unauthorized - Missing or invalid API key
- **402**: Payment Required - Feature requires Developer subscription
- **403**: Forbidden - No access to resource
- **404**: Not Found - Link, webhook, or resource not found
- **409**: Conflict - Custom slug already exists
- **422**: Unprocessable Entity - Invalid custom slug format
- **429**: Too Many Requests - Rate limit exceeded
- **500**: Internal Server Error

## Rate Limiting

All API responses include rate limit headers:
- X-RateLimit-Limit: Your hourly request limit
- X-RateLimit-Remaining: Requests remaining this hour
- X-RateLimit-Reset: Time when limit resets (Unix timestamp)

## Example Usage

### Create a short link:
curl -X POST https://www.tny.dev/api/v1/shorten \\
  -H "Content-Type: application/json" \\
  -H "X-API-Key: tnyl_your_api_key_here" \\
  -d '{"url": "https://github.com/vercel/next.js"}'

### Bulk create short links:
curl -X POST https://www.tny.dev/api/v1/shorten/bulk \\
  -H "Content-Type: application/json" \\
  -H "X-API-Key: tnyl_your_api_key_here" \\
  -d '{
    "links": [
      {"url": "https://github.com/vercel/next.js"},
      {"url": "https://example.com", "customSlug": "example"}, // Error: custom slug without domain_id
      {"url": "https://docs.example.com", "customSlug": "docs", "domain_id": "your-domain-uuid"}
    ]
  }'

### List your links:
# Get links created by current API key only (default)
curl https://www.tny.dev/api/v1/links \\
  -H "X-API-Key: tnyl_your_api_key_here"

# Get all links across all user's API keys
curl "https://www.tny.dev/api/v1/links?scope=all" \\
  -H "X-API-Key: tnyl_your_api_key_here"

# Get page 2 with 50 items per page
curl "https://www.tny.dev/api/v1/links?page=2&limit=50" \\
  -H "X-API-Key: tnyl_your_api_key_here"

### Get analytics for a link:
# Get analytics data (requires authentication)
curl https://www.tny.dev/api/v1/analytics/abc123 \\
  -H "X-API-Key: tnyl_your_api_key_here"

### Manage webhooks:
No example available

### Redirect and link verification:
No example available

## All cURL Examples

### Create Short Link:
```bash
curl -X POST https://www.tny.dev/api/v1/shorten \\
  -H "Content-Type: application/json" \\
  -H "X-API-Key: tnyl_your_api_key_here" \\
  -d '{"url": "https://github.com/vercel/next.js"}'
```

### Bulk Short Link:
```bash
curl -X POST https://www.tny.dev/api/v1/shorten/bulk \\
  -H "Content-Type: application/json" \\
  -H "X-API-Key: tnyl_your_api_key_here" \\
  -d '{
    "links": [
      {"url": "https://github.com/vercel/next.js"},
      {"url": "https://example.com", "customSlug": "example"}, // Error: custom slug without domain_id
      {"url": "https://docs.example.com", "customSlug": "docs", "domain_id": "your-domain-uuid"}
    ]
  }'
```

### List Links:
```bash
# Get links created by current API key only (default)
curl https://www.tny.dev/api/v1/links \\
  -H "X-API-Key: tnyl_your_api_key_here"

# Get all links across all user's API keys
curl "https://www.tny.dev/api/v1/links?scope=all" \\
  -H "X-API-Key: tnyl_your_api_key_here"

# Get page 2 with 50 items per page
curl "https://www.tny.dev/api/v1/links?page=2&limit=50" \\
  -H "X-API-Key: tnyl_your_api_key_here"
```

### Get Analytics:
```bash
# Get analytics data (requires authentication)
curl https://www.tny.dev/api/v1/analytics/abc123 \\
  -H "X-API-Key: tnyl_your_api_key_here"
```

### Redirect and Link Verification:
```bash
# Follow redirect
curl -L https://www.tny.dev/abc123

# Check headers only (no redirect)
curl -I https://www.tny.dev/abc123

# See redirect location
curl -I https://www.tny.dev/abc123 | grep Location
```

## Optional

- [Interactive API Explorer](https://www.tny.dev/api-docs/explorer): Test API endpoints in your browser
- [Developer Portal](https://www.tny.dev/developers): Get API keys and manage custom domains
- [Pricing Plans](https://www.tny.dev/plans): Compare free and developer tiers
- [MCP Integration](https://www.tny.dev/mcp): Model Context Protocol integration for AI assistants
- [Compare Features](https://www.tny.dev/compare): Compare tny.dev with other URL shorteners
- [About](https://www.tny.dev/about): Learn about tny.dev's mission and philosophy