ourl.dev

API 문서

개인 API 키로 링크 관리하기

내 프로그램에서 링크를 만들고, 목록을 보고, 지울 수 있어요. 키는 대시보드 설정에서 발급받으며, 플랜에 API 기능이 켜져 있어야 합니다.

대시보드 설정에서 API 키 발급받기

시작하기

기본 주소

https://ourl.dev/api/v1

인증 — 모든 요청에 발급받은 키를 X-API-Key 헤더로 보내세요.Authorization: Bearer <키> 형태도 쓸 수 있어요.

X-API-Key: aB3xYz9QkLm2Nw8RtVp4Hc7DsEf6JgUa

키는 비밀번호처럼 다뤄 주세요. 브라우저나 공개 저장소에 넣지 말고, 노출됐다면 설정에서 바로 재설정하세요.

요청 한도

키 하나당 1분에 보낼 수 있는 요청 수가 엔드포인트마다(링크 만들기·목록·조회·삭제), 그리고 플랜마다 따로 정해져 있어요. 한도를 넘으면 잠시 차단되고 아래처럼 429가 돌아옵니다.

429 응답

{
  "statusCode": 429,
  "message": "요청 한도를 초과했습니다. 1분 후 다시 시도해 주세요.",
  "retryAfterSeconds": 60
}

한도를 계속 넘기면 일정 시간동안 차단됩니다.

POST/shorturl

링크 만들기

긴 주소를 단축 링크로 만듭니다. 웹에서 만들 때와 같은 검사(차단된 도메인·IP, 플랜의 최대 링크 수와 주소 길이 한도)를 거칩니다.

이름타입설명
originalUrl필수string단축할 원본 주소. https:// 처럼 프로토콜을 포함해야 합니다.
customCodestring직접 정할 단축 코드. 영문 대소문자와 숫자만 쓸 수 있고 6자 이상 50자 이하예요. 이미 쓰는 코드면 409가 돌아옵니다. 생략하면 자동으로 만들어요.
expiresAtstring링크가 만료되는 시각. 한국 시간(KST)으로, 시간대 없이 YYYY-MM-DDTHH:mm:ss 형식으로 적어 주세요. (예: 2026-12-31T23:59:59) 지금보다 이후여야 해요. 생략하면 만료되지 않아요.
maxClicksnumber최대 방문 수. 누적 방문 수가 이 숫자에 닿으면 링크가 닫혀 더 이상 이동하지 않아요. 1 이상 100,000,000 이하의 정수. 생략하면 제한이 없어요.
passwordstring링크 비밀번호. 설정하면 방문자가 비밀번호를 입력해야 원본 주소로 이동해요. 4자 이상, 플랜의 최대 길이 이하. 응답에는 설정 여부(hasPassword)만 돌아오고 비밀번호는 다시 볼 수 없어요.
memostring나만 보는 메모. 방문자에게는 보이지 않아요. 한 줄, 200자 이하이고 줄바꿈은 공백으로 바뀌어요.

요청 · cURL

curl -X POST https://ourl.dev/api/v1/shorturl \
  -H "X-API-Key: 내_API_키" \
  -H "content-type: application/json" \
  -d '{"originalUrl":"https://example.com/very/long/url"}'

응답 200

{
  "id": "clx9f2k0a0000abcd1234",
  "code": "aB3xYz",
  "shortUrl": "https://ourl.dev/aB3xYz",
  "expiresAt": null,
  "memo": null,
  "maxClicks": null,
  "hasPassword": false
}
GET/shorturl

내 링크 목록

내가 만든 링크를 최신순으로 한 페이지씩 가져옵니다. 한 번에 최대 50개까지 요청할 수 있어요.

이름타입설명
pagenumber페이지 번호. 기본값 1.
pageSizenumber한 페이지에 가져올 개수. 기본값 10, 최대 50.

요청 · cURL

curl "https://ourl.dev/api/v1/shorturl?page=1&pageSize=20" \
  -H "X-API-Key: 내_API_키"

응답 200

{
  "items": [
    {
      "id": "clx9f2k0a0000abcd1234",
      "code": "aB3xYz",
      "shortUrl": "https://ourl.dev/aB3xYz",
      "originalUrl": "https://example.com/very/long/url",
      "createdAt": "2026-11-06T05:20:00.000Z",
      "expiresAt": null,
      "memo": null,
      "maxClicks": null,
      "hasPassword": false,
      "blocked": false,
      "clicks": 42
    }
  ],
  "total": 1,
  "page": 1,
  "pageSize": 10
}
GET/shorturl/{code}

링크 하나 조회

단축 코드로 내 링크 한 개의 정보와 방문 수를 가져옵니다. 다른 사람의 링크는 조회할 수 없고 404가 돌아와요.

이름타입설명
code필수string경로에 들어가는 단축 코드.

요청 · cURL

curl https://ourl.dev/api/v1/shorturl/aB3xYz \
  -H "X-API-Key: 내_API_키"

응답 200

{
  "id": "clx9f2k0a0000abcd1234",
  "code": "aB3xYz",
  "shortUrl": "https://ourl.dev/aB3xYz",
  "originalUrl": "https://example.com/very/long/url",
  "createdAt": "2026-11-06T05:20:00.000Z",
  "expiresAt": null,
  "memo": "5월 이벤트 안내",
  "maxClicks": 1000,
  "hasPassword": false,
  "blocked": false,
  "clicks": 42
}
DELETE/shorturl/{code}

링크 삭제

내 링크를 지웁니다. 방문 기록도 함께 삭제되며 되돌릴 수 없어요.

이름타입설명
code필수string경로에 들어가는 단축 코드.

요청 · cURL

curl -X DELETE https://ourl.dev/api/v1/shorturl/aB3xYz \
  -H "X-API-Key: 내_API_키"

응답 200

{
  "ok": true
}

오류 응답

오류는 HTTP 상태 코드와 함께 message(한국어 설명)가 담긴 JSON으로 돌아옵니다.

400잘못된 요청주소·만료일·최대 방문 수·비밀번호 형식이 올바르지 않거나, 만료일이 이미 지난 시각이거나, 비밀번호가 플랜의 최대 길이를 넘었거나, 플랜의 주소 길이 한도를 넘었거나, 차단된 도메인·IP인 경우예요.
401인증 실패API 키가 없거나 올바르지 않아요.
403사용할 수 없음현재 플랜에서 API나 요청에 넣은 기능(customCode·expiresAt·maxClicks·password·memo)을 쓸 수 없거나, 계정이 정지됐거나, 플랜의 최대 링크 수에 도달했어요.
404찾을 수 없음없는 코드이거나 내 링크가 아니에요.
409중복customCode가 이미 사용 중이에요.
429요청 한도 초과분당 요청 한도를 넘었어요. retryAfterSeconds만큼 기다린 뒤 다시 시도하세요.
API 문서 — ourl.dev