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アドレスごとに1時間あたり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}を返します。

エラー

常に機械可読なコード付きの固定形式です。APIのエラー形式とエラーコードをご覧ください。

#ページネーション

ページネーションの方式は1つではありません。ほとんどのリストは小さく、すべてが返されます。パラメータがあるのは一部のエンドポイントだけです。

短縮リンクの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呼び出し回数の枠はありません。適用されるのは1分あたりのレート制限だけです。ページ、リンク、ページあたりのブロック数など、プランのコンテンツの上限は、ダッシュボードと同じく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でページを更新するにあります。