jo4

# Jo4 - URL Shortener & Analytics API

Jo4 is a modern URL shortening service with QR code generation and detailed link analytics.

## Authentication

All protected endpoints require an API key. Set your API key as an environment variable:

```bash
export JO4_API_KEY="your-api-key"
```

Get your API key from: https://jo4.io/api-keys

## API Base URL

```
https://jo4-api.jo4.io/api/v1
```

## Endpoints

### Create Short URL (Authenticated)

```bash
curl -X POST "https://jo4-api.jo4.io/api/v1/protected/url" \
  -H "X-API-Key: $JO4_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "longUrl": "https://example.com/very-long-url",
    "title": "My Link"
  }'
```

**Request Body:**
- `longUrl` (required) - The destination URL (max 2048 chars)
- `title` (optional) - Link title (max 200 chars)
- `description` (optional) - Link description (max 500 chars)
- `shortUrl` (optional) - Custom alias (max 16 chars, alphanumeric/hyphen/underscore)
- `expirationTime` (optional) - Unix timestamp for link expiration
- `passwordProtected` (optional) - Boolean to enable password protection
- `password` (optional) - Password if protected (4-128 chars)

**UTM Parameters:**
- `utmSource`, `utmMedium`, `utmCampaign`, `utmTerm`, `utmContent`

**Response:**
```json
{
  "response": {
    "id": 123,
    "slug": "abc123",
    "shortUrl": "abc123",
    "fullShortUrl": "https://jo4.io/a/abc123",
    "longUrl": "https://example.com/very-long-url",
    "title": "My Link",
    "qrCodeUrl": "https://jo4.io/qr/abc123"
  }
}
```

### Create Anonymous Short URL (No Auth Required)

```bash
curl -X POST "https://jo4-api.jo4.io/api/v1/public/url" \
  -H "Content-Type: application/json" \
  -d '{"longUrl": "https://example.com"}'
```

Limited features, no analytics access.

### Get URL Details

```bash
curl -X GET "https://jo4-api.jo4.io/api/v1/protected/url/{slug}" \
  -H "X-API-Key: $JO4_API_KEY"
```

### Get URL Analytics

```bash
curl -X GET "https://jo4-api.jo4.io/api/v1/protected/url/{slug}/...

# Jo4 - URL Shortener & Analytics

🔗 **[jo4.io](https://jo4.io)** - Modern URL shortening with QR codes and detailed analytics.

## Features

- **Short URLs** - Custom aliases, branded links
- **QR Codes** - Auto-generated for every link
- **Analytics** - Clicks, geography, devices, referrers
- **UTM Tracking** - Built-in campaign parameters
- **Password Protection** - Secure sensitive links
- **Expiring Links** - Time-limited access

## Quick Examples

```bash
# Shorten a URL
curl -X POST "https://jo4-api.jo4.io/api/v1/protected/url" \
  -H "X-API-Key: $JO4_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"longUrl": "https://example.com", "title": "My Link"}'

# Get analytics
curl "https://jo4-api.jo4.io/api/v1/protected/url/{slug}/stats" \
  -H "X-API-Key: $JO4_API_KEY"
```

## Links

- **Website**: https://jo4.io
- **API Docs**: https://jo4-api.jo4.io/swagger-ui/index.html
- **Get API Key**: https://jo4.io/api-keys