API

스크립트와 앱에서 짧은 링크를 만들고 관리하세요. API는 무료입니다. 대시보드의 API 키에서 키를 만든 뒤 bearer 토큰으로 보내세요.

인증

Authorization: Bearer gz_xxxxxxxx_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

키는 한 번만 표시됩니다. 비밀번호처럼 다루세요. 키를 가진 사람은 누구나 당신의 계정에서 링크를 만들고 수정할 수 있습니다. 유출된 키는 대시보드에서 폐기하세요.

제한

• 키당 분당 60회 요청.
• 계정당 하루 새 링크 500개.
• 목적지는 Google Safe Browsing과 우리 차단 목록으로 확인합니다. 다른 링크 단축 서비스는 목적지로 쓸 수 없습니다.

링크 만들기

curl -X POST https://gozi.to/api/my/links \
  -H "Authorization: Bearer $GOZI_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/launch", "code": "launch"}'

code는 선택입니다(4–32자의 영문, 숫자, - 또는 _). 비워 두면 7자리 무작위 코드가 만들어집니다. 응답 201:

{
  "link": {
    "code": "launch",
    "shortUrl": "https://gozi.to/launch",
    "url": "https://example.com/launch",
    "status": "active",
    "statusReason": null,
    "custom": true,
    "createdAt": 1790000000000,
    "expiresAt": null
  }
}

링크 목록

GET /api/my/links?limit=25&cursor=<nextCursor>&q=<search>&clicks=1

최신순입니다. 이전 페이지의 nextCursor를 넘기면 다음 페이지를 받습니다. clicks=1을 쓰면 전체 기간 사람 클릭 수가 함께 나옵니다.

조회, 수정, 삭제

GET    /api/my/links/{code}
PATCH  /api/my/links/{code}   {"url": "https://new.example"}  or  {"status": "disabled" | "active"}
DELETE /api/my/links/{code}

분석

GET /api/my/links/{code}/stats

최근 90일과 전체 기간의 사람 클릭 수, 일별 클릭 수, 상위 국가·유입 경로·기기·브라우저·운영체제를 돌려줍니다. 봇과 링크 미리보기(Slack, WhatsApp 등)는 botClicks에 따로 집계합니다. 결과는 약 5분 동안 캐시됩니다.

오류

오류는 HTTP 상태 코드와 JSON 본문으로 전달됩니다:

{ "error": { "code": "slug_taken", "message": "That custom link is already taken." } }

• 400 잘못된 입력 (invalid_url, invalid_slug, …)
• 401 키가 없거나 잘못되었거나 폐기됨
• 409 이미 사용 중인 맞춤 링크
• 422 허용되지 않는 목적지 (destination_blocked)
• 429 요청 한도 또는 하루 한도 도달

모든 엔드포인트를 기계가 읽을 수 있게 정리한 설명은 /openapi.json에 있습니다.