# REST APIの概要

> ベースURL、認証、エラーの形式、冪等性、そしてBotdoorのすべてのREST APIエンドポイントを一覧で紹介します。

Source: https://docs.botdoor.co/ja/api/overview/

Botdoor REST APIは、HTTPS上でJSONをやり取りします。ベースURLは`https://botdoor.co/api/v1`です。

## 認証

APIキーをBearerトークンとして送信します。

```bash
curl https://botdoor.co/api/v1/accounts -H "Authorization: Bearer $BOTDOOR_KEY"
```

キーは`bd_`で始まり、表示されるのは一度だけです。アプリの**APIキー**で作成するか、[サインアップ](https://docs.botdoor.co/ja/api/signup/)で取得します。キーがない、または誤っている場合は、`WWW-Authenticate: Bearer`とともに`401 unauthorized`が返ります。同じエンドポイントはログイン済みのブラウザセッションも受け付けます。Webアプリはこの方法でAPIを呼び出しています。承認と一括承認・一括却下にはこのセッションが必要で、キーで呼び出すと`403 approval_requires_human`が返ります。キーが却下、再試行、キャンセル、日時の変更をできるのは、そのキー自身が作成した投稿だけです（それ以外は`403 reject_not_own_post`、`retry_not_own_post`、`cancel_not_own_post`、`reschedule_not_own_post`）。人間や別のキー、取り消されたキーが作成した投稿は、ログイン済みの人間が操作します。

## エンドポイント

| メソッド | パス | 内容 |
|---|---|---|
| POST | [`/signup`](https://docs.botdoor.co/ja/api/signup/) | オーナーのためにFreeワークスペースを作成（認証不要） |
| POST | [`/claim-link`](https://docs.botdoor.co/ja/api/claim-link/) | 新しい受け取りリンクをメールで送信（未受け取りのワークスペース） |
| GET | [`/accounts`](https://docs.botdoor.co/ja/api/accounts/) | 連携済みのSNSアカウントを一覧表示 |
| GET | [`/connect/{platform}`](https://docs.botdoor.co/ja/api/connect/) | アカウントを連携するためのブラウザ用URLを取得 |
| POST | [`/media`](https://docs.botdoor.co/ja/api/media/) | 画像または動画をアップロード |
| GET | [`/media/{id}/preview`](https://docs.botdoor.co/ja/api/media/) | アップロードの小さなJPEGプレビュー |
| POST | [`/posts`](https://docs.botdoor.co/ja/api/posts-create/) | 投稿の作成、予約、ドライラン |
| GET | [`/posts`](https://docs.botdoor.co/ja/api/posts-read/) | 最近の投稿を一覧表示 |
| GET | [`/posts/{id}`](https://docs.botdoor.co/ja/api/posts-read/) | 1件の投稿とアカウントごとのステータスを取得 |
| POST | [`/posts/{id}/approve`](https://docs.botdoor.co/ja/api/post-actions/) | 承認待ちの投稿を承認（人間のみ） |
| POST | [`/posts/{id}/reject`](https://docs.botdoor.co/ja/api/post-actions/) | 承認待ちの投稿を却下（キーまたは人間） |
| POST | [`/posts/{id}/cancel`](https://docs.botdoor.co/ja/api/post-actions/) | 公開前にキャンセル |
| POST | [`/posts/{id}/reschedule`](https://docs.botdoor.co/ja/api/post-actions/) | 予約日時を変更 |
| POST | [`/posts/{id}/first-comment/retry`](https://docs.botdoor.co/ja/api/post-actions/) | 失敗した最初のコメントを再試行 |

`https://botdoor.co/api/mcp`の[MCPサーバー](https://docs.botdoor.co/ja/mcp/overview/)では、同じ操作をツールとして利用できます。

## エラー

エラーはすべて同じ形式です。`code`で分岐してください。`code`は変わりません。`hint`は次に何をすべきかを示します。`retryable`は、同じリクエストが後で成功しうるかどうかを示します。

```json
{"error": {"code": "post_not_found", "message": "No post with this id in this workspace.", "hint": "List posts with GET /api/v1/posts.", "retryable": false}}
```

必要に応じて`details`が追加されます。たとえば、検証エラーでは`{"fields": ["scheduledFor"]}`、レート制限では`{"retryAfterSeconds": 3600}`です。一覧は[エラー](https://docs.botdoor.co/ja/help/errors/)をご覧ください。

## 冪等性

`POST /posts`には`Idempotency-Key`ヘッダーを付けて送信してください。同じキーと同じボディで再試行すると、二重に投稿されることはなく、元の投稿が返ります（`200`、`replayed: true`）。同じキーで異なるボディを送ると`422 idempotency_key_reused`が返ります。

## 日時

日時はISO 8601形式です。入力にはタイムゾーンのオフセットが必要です。たとえば`2026-10-12T15:00:00-04:00`や`...Z`のように指定します。出力は`Z`付きのUTCです。

## よくある質問

### SDKはありますか？

まだありません。APIはHTTPS上のシンプルなJSONです。エージェントは代わりにMCPサーバーを使うこともできます。

### 1つのキーで複数のワークスペースを使えますか？

いいえ。キーは1つのワークスペースに属します。ワークスペースごとにキーを作成してください。

### APIにレート制限はありますか？

サインアップ、受け取りリンク、ログインにはレート制限があります（Retry-Afterを伴う429 rate_limited）。Freeワークスペースの投稿は月30件までです（403 post_limit_reached）。

### OpenAPI仕様はどこにありますか？

OpenAPIファイルはまだありません。このリファレンスはサーバーのルートと照合して確認しています。また、/llms-full.txtでリファレンス全体を1つのテキストファイルとして取得できます。