API 문서

POST /api/v1/shorten

URL을 단축합니다. 요청 본문은 JSON 또는 폼 형식을 지원합니다.

파라미터

• original_url — 단축할 원본 URL (필수). http:// 또는 https:// 로 시작해야 하며 2048자 이하. 한글 등 ASCII 밖의 문자는 퍼센트 인코딩해 주세요.
• custom_code — 원하는 단축 코드 (선택, 생략 시 자동 생성). 한글·영문·숫자·-·_ 1~64자. 문자열로 보내야 합니다.
• expire_duration — 만료 기간: 24h, 48h, 1week, 1month (선택, 기본 1week). 이 네 값 밖이면 400 으로 거절합니다.

한 IP 에서 1시간에 100개까지 만들 수 있습니다. 초과하면 429 와 Retry-After 헤더를 돌려줍니다.

요청 예시

POST https://syo.kr/api/v1/shorten
Content-Type: application/json

{
  "original_url": "https://example.com/very-long-url",
  "custom_code": "sale",
  "expire_duration": "1week"
}

성공 응답 (201)

{
  "status": "success",
  "message": "URL이 성공적으로 단축되었습니다.",
  "data": {
    "short_url": "https://syo.kr/sale",
    "original_url": "https://example.com/very-long-url",
    "code": "sale",
    "expiration_date": "2026-07-29 14:30:05"
  }
}

expiration_date 는 UTC 기준 YYYY-MM-DD HH:MM:SS 입니다. 영구 링크(회원 전용)에서는 null 이 됩니다.

오류 응답

실패는 항상 아래 형태이고 Content-Type 은 application/json 입니다.

{ "status": "error", "message": "이미 사용 중인 단축 코드입니다." }

• 400 — 입력이 잘못됨
  • http(s):// 로 시작하는 올바른 URL을 입력해 주세요. — 스킴이 없거나 형식 오류. 필수 파라미터를 빠뜨린 경우도 이 메시지입니다.
  • URL이 너무 깁니다. 2048자 이하로 입력해 주세요.
  • 단축 코드는 한글·영문·숫자·(-,_) 1~64자만 사용할 수 있습니다.
  • 단축 코드는 64자 이하로 입력해 주세요.
  • custom_code 는 문자열이어야 합니다.
  • 이미 사용 중인 단축 코드입니다. / 사용할 수 없는 단축 코드입니다. (예약어)
  • 차단된 도메인이에요. 다른 URL을 사용해 주세요.
  • expire_duration 은 24h, 48h, 1week, 1month 중 하나여야 합니다.
• 403 — 관리자가 공개 API 를 잠시 닫아둔 상태
• 404 — 없는 엔드포인트 (/api/ 로 시작하는 경로는 JSON 으로 답합니다)
• 405 — 허용되지 않은 메서드. Allow 헤더에 쓸 수 있는 메서드가 옵니다.
• 429 — 시간당 생성 한도 초과. Retry-After 초 단위.

GET /api/v1/shorten

API 정보와 사용 가능한 파라미터를 JSON으로 반환합니다. HEAD 도 같은 헤더를 돌려줍니다(본문 없음).

브라우저에서 직접 호출

모든 응답에 Access-Control-Allow-Origin: * 가 붙어 있어 어느 도메인의 웹페이지에서도 바로 호출할 수 있습니다. OPTIONS 프리플라이트는 204 로 답합니다. 인증 토큰이 없으므로 공개해도 되는 용도로만 사용해 주세요.

cURL 예시

curl -X POST https://syo.kr/api/v1/shorten \
  -H "Content-Type: application/json" \
  -d '{"original_url":"https://example.com","expire_duration":"48h"}'