LinkHarbor API 한눈에 보기

REST API를 쓰면 자체 프로그램으로 LinkHarbor를 제어할 수 있습니다. 페이지와 링크를 만들고, 초안을 편집하고 게시하고, 단축 링크를 만들거나 통계를 자체 보고서로 가져올 수 있습니다. 이 글은 개발자를 위한 것이며 모든 엔드포인트에 적용되는 기본 규칙을 설명합니다.

#어떤 방법이 맞을까요?

#기본 URL과 버전 관리

기본 URL

https://dock.at-harbor.com입니다. 모든 제품 엔드포인트는 /v1 아래에 있습니다. 예: https://dock.at-harbor.com/v1/pages.

버전

현재는 v1 버전만 있습니다. 버전 번호는 경로의 일부입니다.

프로토콜

HTTPS만 지원합니다.

OpenAPI

기계가 읽을 수 있는 명세(OpenAPI 3.1)는 https://dock.at-harbor.com/openapi.yaml에 있습니다. Postman, Insomnia, 코드 생성기에 불러올 수 있습니다.

#샌드박스에서 테스트하기

개발과 테스트를 위한 별도의 샌드박스가 있습니다. 실제 API처럼 동작하지만 완전히 분리되어 있습니다. 계정도 데이터도 따로이며, 어떤 것도 실제 워크스페이스에 들어가지 않습니다.

API

https://drydock.at-harbor.com이며 경로는 위와 같습니다. 예: https://drydock.at-harbor.com/v1/pages.

대시보드

https://sandbox-deck.linkharbor.com이며, 예를 들어 API 키를 만들 때 씁니다.

페이지

게시된 페이지는 https://<handle>.sandbox.linkharbor.com에 나타납니다.

계정

실제 LinkHarbor 계정은 그곳에서 작동하지 않습니다. 별도의 샌드박스 계정을 만드세요.

샌드박스는 이메일을 보내지 않습니다. API로 가입하면(POST /v1/auth/register) 인증 코드가 응답의 _dev_verification 필드에 바로 돌아옵니다. 비밀번호 재설정과 이메일 변경도 마찬가지입니다. 이 필드는 샌드박스에만 있으므로 코드에서 의존하지 마세요.

• 푸시 알림은 꺼져 있음
• 결제는 Stripe의 테스트 모드로 처리되며 실제 돈은 오가지 않음
• 요청 한도는 실제 값의 약 3분의 1이며, 새 계정은 IP 주소당 시간당 5개로 제한됨
• 매월 1일 3:00 UTC에 샌드박스가 완전히 초기화되며, 그 뒤 모든 계정과 데이터가 사라짐
• 모든 응답에 X-Environment: sandbox 헤더가 붙음

#인증 요약

1. 소유자나 관리자가 대시보드의 “콜백 및 API”에서 필요한 스코프로 API 키를 만듭니다(Creator Pro부터)
2. POST /v1/token으로 키 ID와 키 시크릿을 액세스 토큰으로 교환합니다
3. 모든 요청에 Authorization: Bearer … 헤더로 토큰을 보냅니다
4. 15분이 지나면 새 토큰을 받습니다

자세한 내용은 API 키와 토큰에, 권한은 스코프에 있습니다.

#요청과 응답

형식

요청과 응답은 UTF-8 JSON입니다. 파일 업로드에는 multipart/form-data도 씁니다.

Content-Type

본문이 있는 모든 요청에 Content-Type: application/json 헤더를 보내세요. 다른 유형은 400 bad_request로 거부되며, 이 헤더가 없을 때 curl이 -d에 자동으로 설정하는 유형도 마찬가지입니다.

알 수 없는 필드

엔드포인트가 모르는 필드는 422 validation_failed가 됩니다. 응답에 알 수 없는 필드가 나옵니다.

깨진 JSON

400 invalid_json이 됩니다.

크기

엔드포인트에 따라 본문은 최대 64 KB, 1 MB, 2 MB이며 파일 업로드는 10 MB입니다. 더 크면 API가 413 request_too_large로 응답합니다. 모든 한도는 요청 한도에 정리되어 있습니다.

목록

items 필드가 있는 객체로 옵니다. 예: {"items":[…]}.

생성

HTTP 201과 새 ID로 응답합니다. 예: {"id":123}.

반환값이 없는 작업

{"ok":true}로 응답합니다.

오류

항상 기계가 읽을 수 있는 코드가 있는 고정된 형식입니다. 오류 형식과 오류 코드를 참고하세요.

#페이지네이션

하나로 통일된 페이지네이션 방식은 없습니다. 대부분의 목록은 작아서 한 번에 모두 돌아오며, 일부 엔드포인트에만 파라미터가 있습니다.

단축 링크의 sort에는 created_desc, created_asc, redirects_desc, redirects_asc가 있으며, q는 슬러그, 제목, 대상 URL을 검색합니다(최대 100자, 대소문자 구분 없음). 통계의 period에는 24h, 7d, 30d, 90d, this_month, last_month, last_30d, custom을 쓸 수 있으며, 대신 from과 to를 보낼 수도 있습니다. granularity는 hour 또는 day입니다.

#요청 ID와 언어

• 모든 응답에 X-Request-Id 헤더가 붙음. 지원팀에 문의할 때 함께 알려 주기
• X-Request-Id 헤더를 직접 보내면 API가 그 값을 사용함
• message의 오류 텍스트는 워크스페이스 소유자의 계정 언어로, 그것이 없으면 Accept-Language를 따름. error의 코드는 항상 같음

#브라우저에서 호출하나요?

기술적으로 API는 브라우저에서의 호출(CORS)을 허용합니다. 하지만 키 시크릿은 웹사이트든 앱이든 방문자 쪽에서 실행되는 코드에 절대 넣으면 안 됩니다. API는 항상 자체 서버에서 호출하세요.

#플랜

플랜별 API 호출 할당량은 없습니다. 분당 요청 한도만 적용됩니다. 페이지, 링크, 페이지당 블록 같은 플랜의 콘텐츠 한도는 대시보드와 마찬가지로 API에도 적용됩니다. 플랜 비교를 참고하세요.

#첫 번째 호출

# 키를 토큰으로 교환
curl -X POST https://dock.at-harbor.com/v1/token \
  -H "Content-Type: application/json" \
  -d '{"key_id":"6F668EA6598B0692","key_secret":"lt_…"}'
# → {"token":"eyJ…","expires_in":900}

export LH_TOKEN="eyJ…"

# 페이지 목록 가져오기(스코프 read:pages)
curl https://dock.at-harbor.com/v1/pages \
  -H "Authorization: Bearer $LH_TOKEN"

링크를 추가하고 디자인을 바꾸고 게시하는 전체 예시는 API로 페이지 업데이트하기에 있습니다.