본문 바로가기
cutty.dev
개발자를 위한

API 및 MCP 서버

REST API로, 또는 AI 어시스턴트의 MCP 서버를 통해 직접 코드에서 짧은 링크를 만들고 관리하세요.

cutty에는 공개 API와 MCP 서버가 있습니다. 앞쪽은 코드에서 링크를 만들고 바꿀 수 있게 해주고, 뒤쪽은 MCP 프로토콜을 쓰는 AI 어시스턴트에서 바로 동작합니다. 둘 다 같은 API 키를 씁니다.

API 키

모든 호출은 헤더로 인증합니다:

Authorization: Bearer ck_your_key

키 받는 곳: 로그인한 뒤 대시보드 → API keys → Create key. 전체 키(ck_로 시작)는 생성할 때 딱 한 번만 보여줍니다. 바로 안전한 곳에 저장해 두세요. 제한은 키당 분당 120회 요청입니다.

기본 URL

모든 REST 엔드포인트는 https://cutty.dev/api/v1 아래에 있습니다. 요청과 응답은 JSON입니다.

링크 만들기

POST /api/v1/links — JSON 본문에는 최소한 url이 필요합니다. 나머지는 선택입니다:

  • url — 목적지 주소 (필수)
  • slug — 직접 정하는 끝부분, 3~40자. 비우면 무작위로 생성
  • expiresAt — 만료 날짜, ISO 8601 형식
  • maxHits — 클릭 제한 (1~1,000,000)
  • password — 링크를 보호하는 비밀번호
  • tags — 대시보드에서 정리하기 위한 쉼표로 구분한 라벨
  • folder — 링크를 넣을 폴더 이름
  • utmSource, utmMedium, utmCampaign — 리디렉트 시 붙는 UTM 파라미터

응답으로 slug, shortUrl, target이 돌아옵니다.

curl -X POST https://cutty.dev/api/v1/links \
  -H "Authorization: Bearer ck_your_key" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/a/very/long/address","slug":"offer","tags":"campaign,summer"}'

목록과 단일 링크

GET /api/v1/links는 내 링크를 모두 돌려줍니다. GET /api/v1/links/{slug} — 하나의 상세 정보.

curl https://cutty.dev/api/v1/links/offer \
  -H "Authorization: Bearer ck_your_key"

수정과 삭제

PATCH /api/v1/links/{slug}는 넘긴 필드를 업데이트하고, DELETE /api/v1/links/{slug}는 링크를 지웁니다.

curl -X PATCH https://cutty.dev/api/v1/links/offer \
  -H "Authorization: Bearer ck_your_key" \
  -H "Content-Type: application/json" \
  -d '{"maxHits":500}'

PATCH로는 무엇보다 targetUrl, expiresAt, maxHits, status, password, tags, folder에 더해 아래의 고급 필드까지 설정할 수 있습니다. 필드를 null(또는 빈 문자열)로 두면 그 속성이 지워집니다.

타게팅, A/B, 고급 필드

링크 편집기에서 쓰던 것들을 API로도 똑같이 쓸 수 있습니다:

  • rules — 국가나 기기별 리디렉트 규칙의 배열, 예: [{"kind":"country","match":"PL","url":"https://shop.pl"},{"kind":"device","match":"ios","url":"https://apps.apple.com/..."}]
  • abUrls — A/B 순환: [{"url":"https://a.com","weight":1},{"url":"https://b.com","weight":1}] 배열. 맞는 규칙이 없을 때 쓰입니다
  • startsAt — 링크가 활성화되는 날짜(ISO 8601). 그 전에는 링크가 425를 반환합니다
  • webhookUrl — 클릭이 있을 때마다 POST 알림을 받는 주소 (보내고 잊는 방식)
  • serveOg와 ogTitle, ogDescription, ogImageUrl — 소셜 크롤러용 맞춤 미리보기 카드 (사람은 여전히 리디렉트됩니다)
curl -X PATCH https://cutty.dev/api/v1/links/offer \
  -H "Authorization: Bearer ck_your_key" \
  -H "Content-Type: application/json" \
  -d '{"rules":[{"kind":"country","match":"DE","url":"https://example.de"}]}'

일괄 작업

POST /api/v1/bulk는 요청 한 번으로 여러 링크를 만듭니다. links 배열을 넘기면 되고(각 항목은 일반 생성과 같은 형태), 한 번에 최대 500개까지 가능합니다. 응답은 행마다 결과를 돌려줍니다.

curl -X POST https://cutty.dev/api/v1/bulk \
  -H "Authorization: Bearer ck_your_key" \
  -H "Content-Type: application/json" \
  -d '{"links":[{"url":"https://a.com"},{"url":"https://b.com","slug":"b"}]}'

링크 통계

GET /api/v1/links/{slug}/stats는 클릭 요약을 돌려줍니다. 총합, 기기와 브라우저별 분포, 그리고 최근 24시간의 분포까지.

curl https://cutty.dev/api/v1/links/offer/stats \
  -H "Authorization: Bearer ck_your_key"

MCP 서버

AI 어시스턴트를 쓴다면 MCP(Model Context Protocol)로 cutty를 연결해, 대화 중에 바로 링크를 줄이고 정리하라고 시킬 수 있습니다. 서버는 https://mcp.cutty.dev/mcp에서 Streamable HTTP로 동작하고, 인증은 같은 API 키 — Authorization: Bearer ck_... 헤더로 합니다.

전체 도구 목록, 바로 쓸 수 있는 연결 스니펫, 예제는 별도 페이지에 있습니다: cutty MCP 서버.

잘 안 되나요?

[email protected]로 메일 주세요. 같은 날 답장드립니다.