API v2.1

BrB.kr API Docs

Integrate link shortening into your service with just a few lines of code. All you need is an API Key to get started.

Overview

The BrB.kr API is designed using RESTful principles. All requests and responses use JSON format.

Base URL

https://brb.kr

Authentication

API requests require API Key authentication. You can obtain an API Key from the admin dashboard.

Request Header

Include the X-API-Key header in all API requests.

X-API-Key: brbkr_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Security Notes

Never expose your API Key in client-side code
Use environment variables or secret management services
Regenerate your API Key immediately if compromised

Endpoints

POST/api/shorten

Convert a long URL into a shortened URL.

Request

{
  "url": "https://example.com/very/long/url",
  "mode": "common",  // Optional
  "lang": "ko"       // Optional
}

Parameter	Type	Description
url *	string	Original URL to shorten (required)
mode	string	Code generation mode (optional, defaults to first allowedModes from API Key) commonkoreantimefile

Response

{
  "success": true,
  "data": {
    "code": "Ab3xYz",
    "fullUrl": "https://brb.kr/Ab3xYz",
    "originalUrl": "https://example.com/very/long/url",
    "createdAt": "2025-01-14T12:00:00.000Z",
    "mode": "common"
  }
}

GET/api/redirect/[code]

Retrieve original URL information for a short code.

Calling this endpoint increments the click count.

Response

{
  "success": true,
  "data": {
    "code": "Ab3xYz",
    "originalUrl": "https://example.com/very/long/url",
    "shortUrl": "https://brb.kr/Ab3xYz",
    "createdAt": "2025-01-14T12:00:00.000Z",
    "lang": "ko",
    "stats": {
      "clicks": 1234,
      "uniqueVisitors": 892,
      "lastClickedAt": "2025-01-14T15:30:00.000Z",
      "referrers": {
        "twitter.com": 245,
        "facebook.com": 180,
        "direct": 156
      },
      "devices": {
        "mobile": 620,
        "desktop": 580,
        "tablet": 34
      },
      "browsers": {
        "Chrome": 540,
        "Safari": 380,
        "Firefox": 120
      }
    }
  }
}

Stats Fields

Field	Type	Description
clicks	number	Total click count
uniqueVisitors	number	Unique visitors (IP-based)
lastClickedAt	string \| null	Last click timestamp (ISO 8601)
referrers	object	Clicks by referrer domain (top 5)
devices	object	Clicks by device type
browsers	object	Clicks by browser

Error Handling

Errors return a consistent response format.

Error Response Format

{
  "success": false,
  "error": {
    "code": "MODE_NOT_ALLOWED",
    "message": "허용되지 않은 mode입니다.",
    "details": {
      "requestedMode": "korean",
      "allowedModes": ["common", "timefile"]
    }
  }
}

Error Codes

Code	Status	Description
INVALID_API_KEY	401	Invalid API Key
EXPIRED_API_KEY	401	Expired API Key
REVOKED_API_KEY	403	Revoked API Key
INSUFFICIENT_PERMISSION	403	Insufficient permission
MODE_NOT_ALLOWED	403	Mode not allowed
RATE_LIMIT_EXCEEDED	429	Rate limit exceeded

Rate Limit

Each API Key has its own rate limit. The default is 1,000 requests per hour.

Response Headers

X-RateLimit-LimitMaximum allowed requests
X-RateLimit-RemainingRemaining requests
X-RateLimit-ResetReset time (Unix timestamp)
Retry-AfterWait time before retry (seconds)

Code Examples

Basic Usage

const API_KEY = 'brbkr_live_xxx';

async function createShortUrl(url) {
  const response = await fetch('https://brb.kr/api/shorten', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'X-API-Key': API_KEY,
    },
    body: JSON.stringify({ url }),
  });

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

// Usage
const shortUrl = await createShortUrl('https://example.com/long/url');
console.log(shortUrl); // https://brb.kr/Ab3xYz

API Playground

Test the API directly.

Request Preview

curl -X POST https://brb.kr/api/shorten \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/very/long/url/path"}'

Response

// Response will appear here...