本文へスキップ
API · v1

開発者API

APIキーを使って、ほかのアプリから chck.my の短縮URLを作成・管理できます。

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

APIキーは1つのワークスペースに紐づきます。workspaceIdを省略するとそのワークスペースが使われ、別のワークスペースを指定すると403になります。セッション・アプリ・アップロードのリクエストではworkspaceIdが必須です(省略時は400)。プランと利用上限もワークスペース単位です。メンバーを削除すると、そのワークスペースのキーも無効になります。

Pro・Teamのワークスペースでは、読み取り専用または書き込み権限のAPIキーを最大10個発行できます。運営許可リストはAPIの利用条件のみを除外し、役割・席数・一括操作権限・上限は除外しません。ダウングレード後も既存キーの確認と無効化が可能です。リンク変更APIに任意のIdempotency-Keyを付けると、成功した操作IDを恒久的に予約します。異なる入力は409、削除済み・期限切れの結果は410となり、再実行しません。削除の再要求は最初の削除IDのみ返します。POST /automationはlist・preview・execute・resultsに対応し、サーバー発行の実行IDとハッシュで実行します。入力は暗号化し、プレビューと結果はパスワードを返しません。詳細は30日後に期限切れとなり、成功した最小記録は残ります。WebMCPも現在のセッションとアプリと同じ権限・承認ポリシーを利用します。キャンセル後も変更が完了している場合があるため、同じ実行IDで結果を確認してください。

소개

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와 자동화에도 적용되며, 정책이 있는 링크의 미지원 라우팅 변경은 거절됩니다. 기존 계약의 월/연 생성량을 유지하고 삭제·동일 작업 재실행으로 잔량을 복구하지 않습니다.

顧客別に制限されたキーは現在の役割と顧客grantの共通範囲に従います。公用資料の読み取りが制限ユーザーの公用資料への書き込みを許可することはなく、grantが0件でも全体アクセスに拡大しません。新規リソースのcustomerIdは作成時に検証します。基本URLの承認はAPIと自動化にも適用され、保護されたリンクの未対応ルーティング変更は拒否します。既存の月間/年間契約は維持し、削除や再実行で作成枠は復活しません。