コンテンツにスキップ
LinkdashLinkdash
日本語
Esc
↑↓移動↵開く⌘Jプレビュー
このページの内容

HTTP API

https://api.linkdash.dev/v1 の REST API で、ダッシュボードで発行したベアラーキーを使用します。CLI や MCP と同じ操作を行えます。

ベース URL: https://api.linkdash.dev/v1

認証: Authorization: Bearer ldash_...(キーは ダッシュボード → API キー で作成します)。キーを捏造しないでください。

CLI リファレンス: CLI。MCP: MCP。料金 / クォータ: 料金。ディスカバリー(認証不要): GET https://api.linkdash.dev/v1。プレーンな Markdown: api.md。

公開 ID はスラッグ(deck、k3m9xq)であり、Convex の _id ではありません。JSON のフィールド名は CLI の標準出力と同じです(id、url、kind、…)。

規約

  • 特に記載がない限り、JSON(Content-Type: application/json)を使用します。
  • 作成時には、url、text、または POST /uploads 後の storageId のいずれか 1 つ、または variants 配列(バリアント を参照)、または name を伴う "kind": "folder"(フォルダー を参照)を指定します。発行(mint)は { "uploadUrl", "storageId" } を返します。ホストはバイト列を uploadUrl に PUT します。小さなファイルは引き続き POST /links でマルチパートの file を使用できます。
  • 期間: 7d、24h、30m、1w、または ISO 日付。フィールド: expires / expiresAt、starts / startsAt。
  • 開封回数の上限: 任意の正の整数 maxOpenings。その回数だけ開封に成功すると、リンクは一時停止します。再び配信するには、maxOpenings を引き上げるか clearMaxOpenings を指定します。無制限にするには maxOpenings を省略します。
  • オーナーの 2 つのドメインに同じスラッグが存在する場合は、?domain= / JSON の domain を渡します。
  • エラー: { "error": "..." } と、任意の code。使用済みの lida.sh スラッグは code: "slug_taken" とともに 409 を返します。
  • アクセス: 新しいリンクとフォルダーは、本文で access を設定しない限り restricted になります(アクセスと共有 を参照)。レスポンスの url は共有 URL(https://linkdash.dev/s/<token>)です。ただし、リンクが公開されている場合は短縮 URL になります。
  • 書き込みは月間イベントクォータにカウントされます(共有、共有解除、リセットを含む)。list / get / stats / export / 共有一覧 / shared / webhook の list/get はカウントされません。訪問 / ダウンロード / 再生の取り込みは引き続きカウントされます。

エンドポイント

CLI HTTP MCP
auth whoami GET /me whoami
links list GET /links (?q=&tag=&kind=&status=&folder=&limit=&cursor=) links_list
links get <id> GET /links/:id (?domain=) links_get
links create --url/--file/--text/--folder POST /links links_create
links update <id> PATCH /links/:id links_update
links move <id> POST /links/:id/move links_move
links copy <id> POST /links/:id/copy links_copy
links delete <id> DELETE /links/:id (?contents=keep|delete) links_delete
links share <id> --email <e> POST /links/:id/shares links_share
links unshare <id> --email <e> DELETE /links/:id/shares/:email links_unshare
links shares <id> GET /links/:id/shares links_shares
links shares(id なし) PATCH /links/:id/shares/:email { "role": "viewer" | "editor" }
POST /links/:id/unlock { "variant"?, "password"?, "variantPassword"? } { "_id", "variant", "unlocked": true, "minutes": 30, ...target }
GET /links/:id/activity — { "items": [{ "_id", "_creationTime", "action", "detail"?, "actor" }], "cursor" }
GET /shares links_shares(id なし)
links shared GET /shared links_shared
links leave <_id | share URL> DELETE /shared/:id links_leave
links role <id> --email <e> --role viewer|editor PATCH /links/:id/shares/:email links_share_role
links unlock <_id | share URL> POST /links/:id/unlock links_unlock
links activity <id> GET /links/:id/activity links_activity
links reset-link <id> POST /links/:id/reset-link links_update (resetShareLink: true)
links stats --last 24h GET /links/:id/stats?last=24h links_stats
links export GET /links/export links_export
links import POST /links/import links_import
links variants list <id> GET /links/:id/variants variants_list
links variants add <id> POST /links/:id/variants variants_add
links variants update <id> <name> PATCH /links/:id/variants/:name variants_update
links variants remove <id> <name> DELETE /links/:id/variants/:name variants_remove
(発行後にホストが PUT) POST /uploads files_upload_url
DELETE /uploads/:storageId files_discard
webhooks list/create/get/rotate/delete GET/POST /webhooks, GET/DELETE /webhooks/:id, POST /webhooks/:id/rotate webhooks_*
domains list/add/connect/verify/remove GET/POST /domains, GET /domains/:host/connect, POST /domains/:host/verify, DELETE /domains/:host domains_*

auth create、auth login、auth logout はブラウザーのデバイスフローです。これらは Unkey のルートではありません。

GET /me

サインイン中のアカウントを返します。{ "userId": "...", "email": "...", "name": "..." }。メールアドレスと名前は、不明な場合は省略されます。

URL リンクを作成する

curl https://api.linkdash.dev/v1/links \
  -H "Authorization: Bearer ldash_..." \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com","slug":"welcome","access":"public"}'

JSON 本文には url、text、storageId のいずれか 1 つを指定します。加えて、任意で access(restricted がデフォルト | link | public)、slug、name、tags、starts、expires、maxOpenings、password、domain、previewName、previewDescription、previewImageStorageId、sticky、forwardParams、utm(URL リンクのみ)を指定できます。フォルダー内に作成する場合は folder(+ folderDomain)を指定します。短縮形では、main という名前のバリアントが 1 つ作成されます。トップレベルの password、starts、expires、maxOpenings はリンクのゲートになります。レスポンス: { "id", "url", "access", "kind", "variants": [{ "name", "kind" }], "folder" }。

GET /links は 1 ページ分を { "items": [...], "cursor" } として返します。?limit= は 1〜100(デフォルト 50)です。前のページで得た値を ?cursor= に渡し、null になるまで繰り返します。q は単語単位で一致し(最後の単語は前方一致)、関連度順に並びます。項目は { id, kind, status, variantStatuses, variantCount, name, tags, access, url, target, folder, _id } です(フォルダーの行には items が追加されます)。kind フィルターでは folder と group を、status フィルターでは mixed を追加で指定できます。folder=<slug>|root(+ folderDomain)を指定すると、1 つのフォルダーまたはトップレベルを一覧表示します。GET /links/:id は、access と variants を含むリンク全体を返します。コンテンツ(destinationUrl / textContent / fileName)は各バリアントが持っています。

ファイルをアップロードする

アップロード URL({uploadUrl,storageId})を発行し、ホストからバイト列を PUT してから、同じフローでリンクを作成します:

curl https://api.linkdash.dev/v1/uploads \
  -H "Authorization: Bearer ldash_..." \
  -H "Content-Type: application/json" \
  -d '{"fileSize":12345}'

curl -X PUT -H "Content-Type: application/pdf" --data-binary @./deck.pdf "$uploadUrl"

curl https://api.linkdash.dev/v1/links \
  -H "Authorization: Bearer ldash_..." \
  -H "Content-Type: application/json" \
  -d '{"storageId":"…","fileName":"deck.pdf","fileType":"application/pdf","fileSize":12345}'

小さなファイルは、引き続き POST /links でマルチパートを使用できます:

curl https://api.linkdash.dev/v1/links \
  -H "Authorization: Bearer ldash_..." \
  -F "file=@./deck.pdf" \
  -F "expires=7d" \
  -F "slug=deck"

任意のマルチパートフィールド: access、slug、name、tags、starts / startsAt、password、expires、maxOpenings、domain、previewName、previewDescription、previewImage。

更新、統計、CSV

PATCH /links/:id には JSON またはマルチパートを使用します。ファイルのバイト列を置き換えるには、POST /uploads とホストからの PUT の後に storageId を指定するか、マルチパートフィールド file を使用します(単一バリアントのリンクのみ)。--status / { "status": "expired" } は拒否されます。代わりに expires を使用してください。{ "status": "scheduled" } も拒否されます。代わりに starts を使用してください。任意の maxOpenings を指定すると、その回数だけ開封された後にリンクが一時停止します。clearMaxOpenings は上限を解除します。sticky(boolean)と restartSplit(boolean)はバリアントの割り当てを制御します。forwardParams(boolean)は訪問者のクエリ文字列を転送します。詳しくは クエリパラメーターの転送 を参照してください。access はリンクを開ける人を変更し、resetShareLink: true は新しい共有 URL を発行します。レスポンス: { "id", "url", "access", "status", "variantStatuses" }。

GET /links/:id/stats?last=24h は、visits、downloads、plays、visitsInLast、countries、referrers、variants(バリアントごとの合計)、visitors、crawlers を返します。crawlers([{ "crawler", "company", "category", "hits", "lastSeen" }])は、リンクを取得したボットとリンクプレビューの記録で、訪問としてはカウントされません。詳しくは クローラーログ を参照してください。

GET /links/export は、列 slug,kind,name,variant,url,text,fileName,status,domain,tags,starts,expires,maxOpenings,weight,when,created,folder,access を持つ CSV を、バリアントごとに 1 行で返します(folder は所属するフォルダーのスラッグ、access は restricted、link、public のいずれか)。POST /links/import は生の CSV またはマルチパートの file を受け付けます。行はスラッグ + ドメインでグループ化されます。最初の行がバリアント付きでリンクを作成し、以降の行がバリアントを追加します。既存のリンクについてはフィールドを更新したうえで、名前に基づいてバリアントを更新または追加します。kind が folder の行(name 付き)はフォルダーを作成します。folder 列によるリンクの配置は、すべての行が作成された後に行われます。access が空の場合、新しいリンクは restricted になり、既存のリンクはそのまま維持されます。

フォルダーに対する DELETE /links/:id は、?contents=keep(デフォルト。項目は 1 つ上の階層に移動します)または ?contents=delete(内部の項目とフォルダーも削除されます)を受け付けます。

バリアント

すべてのリンクは、1 つ以上のバリアントを格納するコンテナーです。バリアントは、コンテンツ(url | file | text)、独自のゲート(password、paused、starts、expires、maxOpenings)、weight、任意の訪問者条件 when で構成されます。リンク側は、スラッグ、ドメイン、名前、タグ、プレビュー、リンク独自のゲート(バリアントのゲートより優先されます)、sticky(デフォルト true)、splitVersion(restartSplit でインクリメントされます)を持ちます。variants を指定しない場合、リンクは main という名前のバリアントを 1 つ持ちます。名前には英小文字、数字、およびハイフン(先頭・末尾以外)を使用でき、1〜40 文字で、リンク内で一意である必要があります。1 リンクあたりのバリアントは最大 20 個です。

訪問者には 1 つのバリアントが割り当てられます。まず when が一致するバリアントが候補になります(一致するものがない場合は、条件なしのバリアントが候補になります)。次に、候補の中から重み付きで 1 つが選ばれます(sticky の場合は訪問者 + リンク + splitVersion のハッシュ、そうでない場合はランダム)。クローラーには、最初の有効な条件なしバリアントが返されます。複数のバリアントを持つリンクの kind は group です。リンクの status は、リンクのゲートが設定されていればそのステータス、設定されていなければ全バリアントに共通のステータス、共通のステータスがなければ mixed です。variantStatuses は { active, paused, expired, scheduled } の件数を集計します。

複数のバリアントを一度に作成する例です:

curl https://api.linkdash.dev/v1/links \
  -H "Authorization: Bearer ldash_..." \
  -H "Content-Type: application/json" \
  -d '{"slug":"promo","variants":[{"name":"a","url":"https://example.com/a"},{"name":"b","url":"https://example.com/b","weight":3,"when":{"countries":["DE","AT"]}}]}'

各バリアントには、name(必須)、url | text | storageId のいずれか(+ fileName、fileType、fileSize)、password、starts、expires、maxOpenings、utm、weight、when を指定します。マルチパートでの作成は短縮形のみに対応しています。

ルート 本文 レスポンス
GET /links/:id/variants — バリアントの配列
POST /links/:id/variants JSON またはマルチパートの file: name(必須)、コンテンツ、password、starts、expires、maxOpenings、utm、weight、when バリアント
PATCH /links/:id/variants/:name name(名前の変更)、url、text、storageId / file、password、clearPassword、starts、clearStarts、expires、clearExpires、maxOpenings、clearMaxOpenings、status(active | paused)、weight、when、clearWhen、utm バリアント
DELETE /links/:id/variants/:name — { "id", "variant", "deleted": true }(最後のバリアントは削除できません)

when のキー(いずれも文字列の配列で、設定したすべてのキーが一致する必要があります): countries(ISO-2)、devices(mobile | tablet | desktop)、os(windows | macos | android | ios | linux | other)、browsers(edge | chrome | firefox | safari | other)、languages(前方一致)、referrerHosts(ホスト名の後方一致)。

クエリパラメーターのルール

when.params は、訪問者のクエリ文字列(lida.sh/promo?src=newsletter)に対する最大 10 個のルールの配列で、すべてのルールが満たされる必要があります。各ルールは { "key", "op", "value" } で、op は equals | notEquals | includes | startsWith | endsWith | in(value は | 区切りまたはカンマ区切りのリスト)| exists | missing のいずれかです。value は exists / missing 以外では必須です。キーは大文字と小文字が区別され、値は完全一致で比較されます。

{ "params": [{ "key": "src", "op": "equals", "value": "newsletter" }, { "key": "gclid", "op": "missing" }] }

パラメーターの値はリンクを開いた時点で照合され、アナリティクスには保存されません。

クエリパラメーターの転送

forwardParams(リンクの boolean。デフォルトは false。POST /links と PATCH /links/:id で設定でき、GET /links/:id で返されます)を有効にすると、訪問者のクエリ文字列全体が URL バリアントに付加されます。utm を含め、訪問者の値が保存済みの値より優先されます。ファイルとテキストのバリアントではこの設定は無視されます。これはルーティングのための機能であり、アクセス制御ではありません。パラメーターは誰でも追加できます。パラメーターの値はアナリティクスに保存されません。

フォルダー

フォルダーは、中に入れた項目を一覧表示するリンクです。仕組みについては フォルダー を参照してください。

curl https://api.linkdash.dev/v1/links \
  -H "Authorization: Bearer ldash_..." \
  -H "Content-Type: application/json" \
  -d '{"kind":"folder","name":"Q4 launch","slug":"q4"}'

curl https://api.linkdash.dev/v1/links \
  -H "Authorization: Bearer ldash_..." \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/deck","folder":"q4"}'

curl https://api.linkdash.dev/v1/links/k3m9xq/move \
  -H "Authorization: Bearer ldash_..." \
  -H "Content-Type: application/json" \
  -d '{"folder":"q4"}'

curl "https://api.linkdash.dev/v1/links?folder=q4" -H "Authorization: Bearer ldash_..."
ルート 本文 レスポンス
POST /links { "kind": "folder", "name" } と通常のリンクフィールド。url、text、storageId、variants は指定しません 作成されたフォルダー
POST /links/:id/move { "folder": "<slug>" }、またはトップレベルに移動する場合は { "folder": null }。任意で folderDomain { "id", "folder" }
POST /links/:id/copy — { "id", "url", "access", "kind", "variants", "folder", … }(アクセス設定は同じで、共有 URL は新しく発行され、共有相手は引き継がれません)

移動とコピーは、それぞれ 1 イベントとしてカウントされます。存在しないフォルダースラッグを指定すると 404(Folder "<slug>" not found)が返されます。フォルダーではないスラッグを指定した場合や、フォルダーをそれ自身またはその配下のフォルダーに移動しようとした場合は 400 が返されます。フォルダーは最大 32 階層までネストできます。

アクセスと共有

すべてのリンクとフォルダーには access があります。restricted(デフォルト。オーナーと共有相手がサインインした状態で https://linkdash.dev/s/<token> から開けます)、link(その URL を知っている人なら誰でも)、public(誰でも、短縮 URL で開けます)のいずれかです。POST /links または PATCH /links/:id で設定します。公開の場に投稿するリンクには "access": "public" を指定してください。フォルダーと閲覧者の仕組みについては 共有とアクセス を参照してください。

curl https://api.linkdash.dev/v1/links/q4/shares \
  -H "Authorization: Bearer ldash_..." \
  -H "Content-Type: application/json" \
  -d '{"emails":["anna@example.com","ben@example.com"]}'

curl https://api.linkdash.dev/v1/links/q4/shares -H "Authorization: Bearer ldash_..."

curl -X DELETE https://api.linkdash.dev/v1/links/q4/shares/ben%40example.com -H "Authorization: Bearer ldash_..."

curl -X POST https://api.linkdash.dev/v1/links/q4/reset-link -H "Authorization: Bearer ldash_..."

curl https://api.linkdash.dev/v1/shares -H "Authorization: Bearer ldash_..."

curl -X DELETE https://api.linkdash.dev/v1/shared/<_id> -H "Authorization: Bearer ldash_..."
ルート 本文 レスポンス
POST /links/:id/shares { "emails": [...] }(メールアドレス 1〜50 件) { "id", "url", "access", "invited", "alreadyShared" }
DELETE /links/:id/shares/:email — { "id", "email", "removed": true }
GET /links/:id/shares — [{ "email", "role": "viewer", "accepted", "invitedAt", "viaFolder"?: { "id", "name"?, "slug" } }]
GET /shares — { "items": [{ "id", "name"?, "kind", "access", "url", "people": [{ "email", "accepted", "invitedAt" }] }], "cursor" }(自分が共有したすべての項目)
GET /shared — { "items": [{ "_id", "_creationTime", "kind", "title"?, "status", "hasPassword", "access", "url", "itemCount"?, "sharedBy"?, "sharedAt" }], "cursor" }
DELETE /shared/:id — { "_id", "left": true }(:id は GET /shared で取得した _id または共有トークン)
POST /links/:id/reset-link — { "id", "access", "url" }

POST /links/:id/shares で "role": "editor" を指定すると、編集者として共有できます。編集者は項目の変更や、統計とアクティビティの閲覧ができます。ただし、パスワード、スラッグ、ドメイン、アクセス、共有の操作や、削除、移動、コピーはできません(403)。編集者は :id に項目の _id または共有トークンを指定します。パスワードで保護されたバリアントは、POST /links/:id/unlock を実行するまで locked: true のままです。ロック解除は 30 分間有効で、パスワードの入力ミスが 1 時間に 10 回を超えると 429 が返されます。他の人が先に保存した後で保存すると 409 が返されますが、これはリクエストで expectedVersion を送信した場合に限られます。スラッグが重複する場合、すべての共有ルートで ?domain= を指定できます。accepted は、そのメールアドレスで認証済みのアカウントが作成されるまで false です。viaFolder は、上位のフォルダー経由でアクセス権が付与されていることを示します。1 項目あたり最大 200 人と共有でき、招待メールは 1 アカウントあたり 1 日 100 件までです。GET /shares と GET /shared は 1 ページずつ返します。?limit= は 1〜100(デフォルト 50)です。前のページで得た値を ?cursor= に渡し、cursor が null になるまで繰り返します。共有、共有解除、リセットはそれぞれ 1 イベントとしてカウントされますが、退出はカウントされません。退出した後も、上位の共有フォルダー経由のアクセス権は残ります。

エラー

ステータス 発生条件
400 バリデーションエラー、本文がない、作成種別が混在している
401 ベアラーキーがない、または無効
404 スラッグ、ドメイン、またはフォルダーが存在しない
409 スラッグが使用済み(code: "slug_taken")
429 月間イベントクォータの上限に到達
503 このデプロイメントで API キーが設定されていない

Webhook とカスタムドメインのエンドポイントについては、Webhook と カスタムドメイン を参照してください。

このページは役に立ちましたか?