---
title: HTTP API
description: >-
  https://api.linkdash.dev/v1 の REST API で、ダッシュボードで発行したベアラーキーを使用します。CLI や MCP
  と同じ操作を行えます。
sidebar:
  label: HTTP API
  order: 4
---
ベース URL: `https://api.linkdash.dev/v1`

認証: `Authorization: Bearer ldash_...`（キーは [ダッシュボード → API キー](https://linkdash.dev/dashboard/keys) で作成します）。キーを捏造しないでください。

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

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

## 規約

- 特に記載がない限り、JSON（`Content-Type: application/json`）を使用します。
- 作成時には、`url`、`text`、または `POST /uploads` 後の `storageId` のいずれか 1 つ、**または** `variants` 配列（[バリアント](#variants) を参照）、**または** `name` を伴う `"kind": "folder"`（[フォルダー](#folders) を参照）を指定します。発行（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` になります（[アクセスと共有](#access-and-sharing) を参照）。レスポンスの `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" }` | `{ "id", "email", "role" }` |
| `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 リンクを作成する

```bash
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 してから、同じフローでリンクを作成します:

```bash
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` でマルチパートを使用できます:

```bash
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）は訪問者のクエリ文字列を転送します。詳しくは [クエリパラメーターの転送](#forward-query-parameters) を参照してください。`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" }]`）は、リンクを取得したボットとリンクプレビューの記録で、訪問としてはカウントされません。詳しくは [クローラーログ](https://linkdash.dev/pricing.md) を参照してください。

`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 }` の件数を集計します。

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

```bash
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` 以外では必須です。キーは大文字と小文字が区別され、値は完全一致で比較されます。

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

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

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

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

## フォルダー

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

```bash
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"` を指定してください。フォルダーと閲覧者の仕組みについては [共有とアクセス](/ja/sharing) を参照してください。

```bash
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](/ja/webhooks) と [カスタムドメイン](/ja/domains) を参照してください。
