開発者API

このページは現在韓国語のみです。エンドポイント・フィールド名・コード例はすべての言語で共通です（openapi.jsonもご覧ください）。

소개

chck.my API로 단축주소를 코드에서 만들고 관리할 수 있다. 요청·응답은 JSON이고, 필드 이름과 엔드포인트는 Dub API와 비슷하게 맞췄다. 서버 간 호출용이라 CORS는 지원하지 않는다 — 브라우저에서 직접 부르지 말고 키는 서버에만 둔다.

기본 URL:

https://chck.my/api/v4

인증

대시보드 → API에서 키를 만들고 Authorization 헤더에 Bearer 토큰으로 보낸다. 키는 chk_로 시작하고 만들 때 한 번만 보인다 (chck.my에는 해시만 저장). 키가 새면 대시보드에서 폐기하고 새로 만든다.

Authorization: Bearer chk_xxxxxxxxxxxxxxxx

API는 지금 비공개 베타다 — 허용된 계정의 키만 동작하고, 다른 계정의 키는 403 forbidden을 받는다. 허용된 계정은 요금제의 링크 개수·지정 코드 제한을 받지 않지만, URL 안전 검사와 예약어 제한은 똑같이 적용된다.

요청 제한

API 키마다 분당 600회. 모든 응답에 X-RateLimit-Limit: 600이 붙는다. 넘으면 429 rate_limit_exceeded와 Retry-After: 60을 돌려준다. 남은 횟수(X-RateLimit-Remaining)·리셋 시각 헤더는 없다. POST /links/bulk는 링크 개수와 상관없이 한 번으로 센다.

오류

오류는 항상 아래 형식이다. doc_url은 이 문서의 해당 항목을 가리킨다.

{
  "error": {
    "code": "not_found",
    "message": "Link not found.",
    "doc_url": "https://chck.my/developers#errors-not_found"
  }
}

링크 객체

모든 링크 응답의 모양. 시각은 ISO 8601(UTC). utm_*는 url의 쿼리에서 읽은 값이다. disabledAt이 있으면 비활성(또는 신고로 차단)된 링크다.

{
  "id": "0b6c1c0e-7f1e-4d0a-9a4e-2f1d5d6c9a10",
  "domain": "chck.my",
  "key": "Ab3xYz9",
  "url": "https://example.com/posts/42?utm_source=modagi",
  "shortLink": "https://chck.my/Ab3xYz9",
  "externalId": "post-42",
  "title": "글 제목",
  "expiresAt": null,
  "disabledAt": null,
  "utm_source": "modagi",
  "utm_medium": null,
  "utm_campaign": null,
  "utm_term": null,
  "utm_content": null,
  "clicks": 0,
  "userId": "usr_123",
  "createdAt": "2026-10-03T05:00:00.000Z",
  "updatedAt": "2026-10-03T05:00:00.000Z"
}

링크 만들기

POST /links

새 단축주소를 만든다. key나 externalId가 이미 있으면 409.

본문 (JSON)

요청 예시

curl -X POST https://chck.my/api/v4/links \
  -H "Authorization: Bearer $CHCKMY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/posts/42","externalId":"post-42","utm_source":"modagi"}'

응답 예시 (200)

{
  "id": "0b6c1c0e-7f1e-4d0a-9a4e-2f1d5d6c9a10",
  "domain": "chck.my",
  "key": "Ab3xYz9",
  "url": "https://example.com/posts/42?utm_source=modagi",
  "shortLink": "https://chck.my/Ab3xYz9",
  "externalId": "post-42",
  "title": "글 제목",
  "expiresAt": null,
  "disabledAt": null,
  "utm_source": "modagi",
  "utm_medium": null,
  "utm_campaign": null,
  "utm_term": null,
  "utm_content": null,
  "clicks": 0,
  "userId": "usr_123",
  "createdAt": "2026-10-03T05:00:00.000Z",
  "updatedAt": "2026-10-03T05:00:00.000Z"
}

링크 upsert

PUT /links/upsert

externalId가 있으면 그것으로, 없으면 같은 url로 내 링크를 찾는다. 있으면 그대로 돌려주고(url·title·expiresAt·utm이 바뀌었으면 갱신), 없으면 새로 만든다. 같은 요청을 여러 번 보내도 링크는 하나 — 다른 앱에서 자동으로 단축주소를 만들 때 이 엔드포인트를 쓰면 된다. key는 새로 만들 때만 쓰인다.

본문 (JSON) — POST /links와 같다

요청 예시

curl -X PUT https://chck.my/api/v4/links/upsert \
  -H "Authorization: Bearer $CHCKMY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/posts/42","externalId":"post-42"}'

응답 예시 (200)

{
  "id": "0b6c1c0e-7f1e-4d0a-9a4e-2f1d5d6c9a10",
  "domain": "chck.my",
  "key": "Ab3xYz9",
  "url": "https://example.com/posts/42?utm_source=modagi",
  "shortLink": "https://chck.my/Ab3xYz9",
  "externalId": "post-42",
  "title": "글 제목",
  "expiresAt": null,
  "disabledAt": null,
  "utm_source": "modagi",
  "utm_medium": null,
  "utm_campaign": null,
  "utm_term": null,
  "utm_content": null,
  "clicks": 0,
  "userId": "usr_123",
  "createdAt": "2026-10-03T05:00:00.000Z",
  "updatedAt": "2026-10-03T05:00:00.000Z"
}

링크 조회

GET /links/info

linkId, key, externalId 중 하나로 링크 하나를 찾는다. 없으면 404.

쿼리

요청 예시

curl "https://chck.my/api/v4/links/info?externalId=post-42" \
  -H "Authorization: Bearer $CHCKMY_API_KEY"

응답 예시 (200)

{
  "id": "0b6c1c0e-7f1e-4d0a-9a4e-2f1d5d6c9a10",
  "domain": "chck.my",
  "key": "Ab3xYz9",
  "url": "https://example.com/posts/42?utm_source=modagi",
  "shortLink": "https://chck.my/Ab3xYz9",
  "externalId": "post-42",
  "title": "글 제목",
  "expiresAt": null,
  "disabledAt": null,
  "utm_source": "modagi",
  "utm_medium": null,
  "utm_campaign": null,
  "utm_term": null,
  "utm_content": null,
  "clicks": 0,
  "userId": "usr_123",
  "createdAt": "2026-10-03T05:00:00.000Z",
  "updatedAt": "2026-10-03T05:00:00.000Z"
}

링크 목록

GET /links

내 링크 배열. 기본은 최신순 100개.

쿼리

요청 예시

curl "https://chck.my/api/v4/links?page=1&pageSize=50&search=example" \
  -H "Authorization: Bearer $CHCKMY_API_KEY"

응답 예시 (200)

[
  { "id": "…", "key": "Ab3xYz9", "shortLink": "https://chck.my/Ab3xYz9", … }
]

링크 개수

GET /links/count

내 링크 개수 (숫자 하나).

쿼리

요청 예시

curl "https://chck.my/api/v4/links/count" \
  -H "Authorization: Bearer $CHCKMY_API_KEY"

응답 예시 (200)

42

링크 수정

PATCH /links/{linkId}

보낸 필드만 바꾼다. 경로에 링크 id 대신 ext_{externalId}를 써도 된다. 신고로 차단된 링크는 403.

본문 (JSON) — POST /links의 필드, 모두 선택

요청 예시

curl -X PATCH https://chck.my/api/v4/links/ext_post-42 \
  -H "Authorization: Bearer $CHCKMY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"title":"새 제목"}'

응답 예시 (200)

{
  "id": "0b6c1c0e-7f1e-4d0a-9a4e-2f1d5d6c9a10",
  "domain": "chck.my",
  "key": "Ab3xYz9",
  "url": "https://example.com/posts/42?utm_source=modagi",
  "shortLink": "https://chck.my/Ab3xYz9",
  "externalId": "post-42",
  "title": "글 제목",
  "expiresAt": null,
  "disabledAt": null,
  "utm_source": "modagi",
  "utm_medium": null,
  "utm_campaign": null,
  "utm_term": null,
  "utm_content": null,
  "clicks": 0,
  "userId": "usr_123",
  "createdAt": "2026-10-03T05:00:00.000Z",
  "updatedAt": "2026-10-03T05:00:00.000Z"
}

링크 삭제

DELETE /links/{linkId}

링크와 클릭 기록을 지운다. ext_{externalId}도 된다. 신고로 차단된 링크는 403.

요청 예시

curl -X DELETE https://chck.my/api/v4/links/ext_post-42 \
  -H "Authorization: Bearer $CHCKMY_API_KEY"

응답 예시 (200)

{ "id": "0b6c1c0e-7f1e-4d0a-9a4e-2f1d5d6c9a10" }

링크 여러 개 만들기

POST /links/bulk

최대 100개. 결과 배열은 요청 순서대로 링크 또는 { "error": { … } } — 하나가 실패해도 나머지는 만들어진다.

본문 (JSON) — POST /links 본문의 배열

요청 예시

curl -X POST https://chck.my/api/v4/links/bulk \
  -H "Authorization: Bearer $CHCKMY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '[{"url":"https://example.com/a"},{"url":"http://127.0.0.1/"}]'

응답 예시 (200)

[
  { "id": "…", "key": "Ab3xYz9", "shortLink": "https://chck.my/Ab3xYz9", … },
  {
    "error": {
      "code": "unprocessable_entity",
      "message": "URL rejected (private_host): Private, local or reserved hosts are not allowed.",
      "doc_url": "https://chck.my/developers#errors-unprocessable_entity"
    }
  }
]

OpenAPI

기계가 읽을 수 있는 OpenAPI 3.1 문서: https://chck.my/api/v4/openapi.json (인증 필요 없음). 클라이언트 생성기나 Postman 등에 그대로 넣을 수 있다.