본문으로 건너뛰기
API · v1

개발자 API

API 키로 다른 앱에서 chck.my 단축주소를 만들고 관리할 수 있어요.

소개

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

기본 URL:

https://chck.my/api/v4

인증

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

Authorization: Bearer chk_xxxxxxxxxxxxxxxx

API 키는 워크스페이스 하나에 묶인다. workspaceId를 생략하면 그 키의 워크스페이스를 사용하고, 다른 워크스페이스를 지정하면 403이다. 멤버십이 제거되면 키도 폐기된다. 로그인 세션 요청과 앱·업로드 요청에는 workspaceId가 필수이며 생략하면 400이다. 요금제와 사용량도 워크스페이스별로 계산한다.

공개 API는 Pro·Team 워크스페이스에서 사용할 수 있습니다. 운영 허용 목록은 API 접근 조건만 우회하며 워크스페이스 역할·좌석·생성 한도·일괄 생성 권한을 우회하지 않습니다. 키는 읽기 전용 또는 읽기·쓰기 범위로 발급하며 워크스페이스당 활성 키는 최대 10개입니다. 해지 후 신규 발급과 API 사용은 제한하지만 기존 키 목록 확인·폐기는 가능합니다.

중복 실행 방지와 자동화

기존 링크 변경 API는 선택 헤더 Idempotency-Key(8–128자)를 제공한 경우 성공한 작업을 영구 기록합니다. 같은 키의 다른 입력은 409이며, 생성·수정된 링크가 삭제되거나 30일 결과 기간이 지나면 410을 반환하고 다시 실행하지 않습니다. 삭제 재요청은 처음 삭제한 ID만 반환합니다. 키 없이 기존 API를 호출한 경우에는 이 보장이 없습니다. API 키 교체나 권한 회수 후에도 현재 역할·키 범위·구독 권한을 다시 검사합니다.

POST /automation의 preview는 최대 100개 항목을 암호화하여 저장하고 runId와 previewHash를 발급합니다. execute는 이 두 값으로 같은 작업을 실행하며 실패한 항목만 지정해 재시도할 수 있습니다. list와 results로 상태를 조회합니다. 입력·결과는 30일 후 접근을 제한하고 정리하지만 성공한 최소 중복 방지 기록은 남습니다. 비밀번호 원문은 미리보기·결과에 반환하지 않습니다.

자동화 화면의 WebMCP는 지원 브라우저에서 document.modelContext를 통해 현재 로그인 세션으로 동작합니다. 도구 설명이나 모델이 보낸 불리언은 사용자 승인 증거가 아니며 앱과 같은 서버 권한·승인 정책을 따릅니다. 요청 취소 후에도 이미 저장된 변경은 완료되었을 수 있으므로 새 실행을 만들기 전에 같은 실행 ID로 결과를 확인하세요.

요청 제한

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"
  }
}
codeHTTP뜻
workspace_read_only403좌석을 초과해 비소유자 멤버가 읽기 전용이다. 소유자에게 멤버 정리나 요금제 변경을 요청한다.
bad_request400깨진 JSON, 필수 필드 누락, 잘못된 쿼리.
unauthorized401API 키가 없거나 유효하지 않다 (폐기된 키 포함).
forbidden403API 사용이 허용되지 않은 계정, 또는 신고로 차단된 링크를 수정·삭제하려 했다.
not_found404링크(또는 엔드포인트)가 없다.
conflict409같은 key 또는 externalId가 이미 있다.
unprocessable_entity422URL이 안전 검사에 걸렸다(사설 IP, chck.my 자신, 다른 단축주소 서비스 등 — 메시지에 사유), key 형식·예약어, 과거 expiresAt.
rate_limit_exceeded429요청 제한 초과. Retry-After 헤더(초)만큼 기다린다.
internal_server_error500서버 오류. 잠시 뒤 다시 시도한다.
service_unavailable503링크 관리가 유지보수 중이거나 새 링크 모델이 아직 준비되지 않았다. 잠시 뒤 다시 시도한다.

모든 링크 응답의 모양. 시각은 ISO 8601(UTC). utm_*는 url의 쿼리에서 읽은 값이다. disabledAt이 있으면 비활성(또는 신고로 차단)된 링크다. clicks: 0은 조회 가능한 링크 이동 집계가 0건이라는 뜻이다. 동의와 수집 설정, 워크스페이스의 조회 기간 및 접근 권한이 집계 범위를 결정한다. 링크 이동은 고유 방문자 수와 다르다.

{
  "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)

이름타입설명
url (필수)string목적지 URL (http/https). 스킴이 없으면 https://를 붙인다. 최대 2048자.
keystring단축 코드 (영문·숫자·-·_ 3~32자). 생략하면 7자리 무작위.
externalIdstring | null내 서비스의 id (최대 255자). 계정 안에서 유일하다.
titlestring | null제목 (최대 100자).
expiresAtstring | nullISO 8601 만료 시각 (미래). 지나면 단축주소가 404.
utm_source … utm_contentstring | nullURL 쿼리의 utm_source / utm_medium / utm_campaign / utm_term / utm_content를 설정한다. null이면 지운다.

요청 예시

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"
}

PUT /links/upsert

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

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

이름타입설명
url (필수)string목적지 URL (http/https). 스킴이 없으면 https://를 붙인다. 최대 2048자.
keystring단축 코드 (영문·숫자·-·_ 3~32자). 생략하면 7자리 무작위.
externalIdstring | null내 서비스의 id (최대 255자). 계정 안에서 유일하다.
titlestring | null제목 (최대 100자).
expiresAtstring | nullISO 8601 만료 시각 (미래). 지나면 단축주소가 404.
utm_source … utm_contentstring | nullURL 쿼리의 utm_source / utm_medium / utm_campaign / utm_term / utm_content를 설정한다. null이면 지운다.

요청 예시

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.

쿼리

이름타입설명
linkIdstring링크 id.
keystring단축 코드.
externalIdstring내 서비스의 id (접두사 없이).

요청 예시

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개.

쿼리

이름타입설명
pageinteger페이지 (1부터, 기본 1).
pageSizeinteger페이지당 개수 (1~100, 기본 100). 범위를 넘으면 잘라 쓴다.
searchstringkey·제목·URL 부분 일치.
sortBy"createdAt"정렬 기준 (createdAt만 지원).
sortOrder"asc" | "desc"정렬 방향 (기본 desc).

요청 예시

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

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

쿼리

이름타입설명
searchstringkey·제목·URL 부분 일치.

요청 예시

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의 필드, 모두 선택

이름타입설명
urlstring목적지 URL (http/https). 스킴이 없으면 https://를 붙인다. 최대 2048자.
keystring단축 코드 (영문·숫자·-·_ 3~32자). 생략하면 7자리 무작위.
externalIdstring | null내 서비스의 id (최대 255자). 계정 안에서 유일하다.
titlestring | null제목 (최대 100자).
expiresAtstring | nullISO 8601 만료 시각 (미래). 지나면 단축주소가 404.
utm_source … utm_contentstring | nullURL 쿼리의 utm_source / utm_medium / utm_campaign / utm_term / utm_content를 설정한다. null이면 지운다.

요청 예시

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 등에 그대로 넣을 수 있다.

고객사 제한 API 키는 현재 역할과 고객사 grant의 교집합을 따릅니다. 공개 자료 읽기와 제한 사용자의 공용 쓰기는 구분하며, grant가 0개여도 workspace 전체 접근으로 바뀌지 않습니다. 새 리소스의 customerId는 생성 시 함께 검증합니다. 기본 URL 승인 정책은 API와 자동화에도 적용되며, 정책이 있는 링크의 미지원 라우팅 변경은 거절됩니다. 기존 계약의 월/연 생성량을 유지하고 삭제·동일 작업 재실행으로 잔량을 복구하지 않습니다.