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 と カスタムドメイン を参照してください。

