How do I get an API key?

Sign up, then press 'Issue API key' on this page. One key per account, free of charge.

What are the rate limits?

60 requests per minute and 5,000 per day by default. The X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset (seconds) response headers show your remaining quota.

Do links created via the API show up in the dashboard?

Yes. API keys belong to your account, so links created through the API appear in your dashboard list and statistics.

Can I shorten links straight from the browser?

Yes. Drag the bookmarklet at the bottom of this page to your bookmarks bar, then click it on any page to shorten it. Chrome extension source code is also provided.

VRL API

Create, list, delete, and get click statistics for short URLs from your own code with the VRL.KR public API (api.vrl.kr/v1). API keys are free for every member.

API key

One per account, free. The key is shown only once when issued; the server stores only a hash.

API keys are issued free of charge after you sign in.

One per account for every member. No payment or plan required.

Getting started

Base URL

https://api.vrl.kr

Authorization header

Authorization: Bearer vrl_live_…

curl -X POST "https://api.vrl.kr/urls" \
  -H "Authorization: Bearer vrl_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/very/long/path"}'

# Response
{"success":true,"data":{"code":"Ab3xYz","shortUrl":"https://vrl.kr/Ab3xYz","originalUrl":"https://example.com/very/long/path","status":"ACTIVE","clickCount":0,...}}

Every response is either { success, data } or { success:false, error:{ code, message } }.
Rate limit: 60 per minute · 5,000 per day. Check the X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset (seconds) headers.
OpenAPI spec: https://api.vrl.kr/openapi.json

Endpoints

Generated automatically from the server's OpenAPI specification.

get/v1/urls— 내 단축 URL 목록

최신순. page는 1부터, limit 최대 100.

Parameters

Name	In	Type	Description
page	query	integer	페이지(1부터)
limit	query	integer	페이지 크기(1~100)
q	query	string	코드·원본 URL·제목 검색어
status	query	ACTIVE \| EXPIRED \| BLOCKED	상태 필터: ACTIVE \| EXPIRED \| BLOCKED

Example

curl -X GET "https://api.vrl.kr/v1/urls?page=1&limit=20" \
  -H "Authorization: Bearer vrl_live_YOUR_API_KEY"

Responses: 200 OK

post/v1/urls— 단축 URL 생성

원본 URL을 단축합니다. 커스텀 별칭·제목·만료 시각·최대 클릭 수를 지정할 수 있습니다.

Request body (application/json)

Field	Type	Description
url*	string	단축할 원본 URL(http/https)e.g. `https://example.com/very/long/path?x=1`
customAlias	stringnull	커스텀 별칭 3~30자 [A-Za-z0-9_-]. 생략하면 6자 랜덤 코드e.g. `my-link`
title	stringnull	제목(메모)
expiresAt	datetime (ISO-8601)	만료 시각(ISO-8601). 이후 접속 시 만료 안내e.g. `2027-01-01T00:00:00Z`
maxClicks	integernull	최대 클릭 수. 도달 시 만료e.g. `1000`

Example

curl -X POST "https://api.vrl.kr/v1/urls" \
  -H "Authorization: Bearer vrl_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/very/long/path","customAlias":"my-link"}'

Responses: 201 생성됨 · 400 INVALID_REQUEST — URL 형식·별칭 규칙 위반, 예약어 · 409 CONFLICT — 이미 사용 중인 별칭

get/v1/urls/{code}— 단축 URL 상세

코드로 내 링크 하나를 조회합니다.

Parameters

Name	In	Type	Description
code*	path	string

Example

curl -X GET "https://api.vrl.kr/v1/urls/abc123" \
  -H "Authorization: Bearer vrl_live_YOUR_API_KEY"

Responses: 200 OK

delete/v1/urls/{code}— 단축 URL 삭제

링크와 클릭 기록을 삭제합니다. 되돌릴 수 없습니다.

Parameters

Name	In	Type	Description
code*	path	string

Example

curl -X DELETE "https://api.vrl.kr/v1/urls/abc123" \
  -H "Authorization: Bearer vrl_live_YOUR_API_KEY"

Responses: 200 OK

get/v1/urls/{code}/stats— 클릭 통계

기간별 총 클릭·순 클릭·일별 추이·국가·기기·OS·브라우저·유입경로 상위 10개.

Parameters

Name	In	Type	Description
code*	path	string
period	query	string	7d \| 30d \| 90d \| all

Example

curl -X GET "https://api.vrl.kr/v1/urls/abc123/stats?period=30d" \
  -H "Authorization: Bearer vrl_live_YOUR_API_KEY"

Responses: 200 OK

Error codes

HTTP	code	Description
400	INVALID_REQUEST	Malformed request (URL format, alias rules, reserved words, expiry date, etc.)
401	UNAUTHORIZED	API key missing or invalid
403	FORBIDDEN	Not allowed (e.g. editing a blocked link)
404	NOT_FOUND	No such code in your account
409	CONFLICT	Alias already in use
429	RATE_LIMIT	Per-minute or daily limit exceeded. See the Retry-After header
500	SERVER_ERROR	Server error

Shorten from your browser

Drag the button below to your bookmarks bar to save the bookmarklet. On any page, click the bookmark: VRL.KR opens with the address filled in and shortens it right away. If you are signed in, the link is saved to your account and appears in your dashboard.

Shorten with VRL

Drag this button to your bookmarks bar

Drag the button above to your browser's bookmarks bar. (On Safari or mobile, create a bookmark and replace its address with the code below.)
On the page you want to shorten, click the saved bookmark.

Bookmarklet code

javascript:(function(){location.href='https://vrl.kr/en?auto=1&url='+encodeURIComponent(location.href)})()

Chrome extension

A Manifest V3 extension is available in the repository's extension/ folder. Enter your API key in its options to shorten and copy the current tab's URL from the popup. Install it via Developer mode → 'Load unpacked'.

FAQ

How do I get an API key?: Sign up, then press 'Issue API key' on this page. One key per account, free of charge.
What are the rate limits?: 60 requests per minute and 5,000 per day by default. The X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset (seconds) response headers show your remaining quota.
Do links created via the API show up in the dashboard?: Yes. API keys belong to your account, so links created through the API appear in your dashboard list and statistics.
Can I shorten links straight from the browser?: Yes. Drag the bookmarklet at the bottom of this page to your bookmarks bar, then click it on any page to shorten it. Chrome extension source code is also provided.

For other questions see the API guide or email [email protected].