# 開発者向け

ポストメッシュのAPIとMCPサーバーを使って、外部システムやAIエージェントからSNS投稿を自動化できます。

## クイックスタート

1. https://post-mesh.com でアカウントを作成し、投稿したいSNSアカウントをOAuthで連携する
2. ダッシュボードの「APIキー」画面からAPIキーを発行する
3. 発行したキーをBearerトークンとして送る

```bash
curl https://post-mesh.com/api/v1/connections \
  -H "Authorization: Bearer $POST_MESH_API_KEY"
```

APIキーの発行はセルフサービスです。営業への問い合わせや事前審査はありません。7日間の無料トライアル中でも利用できます。

## エンドポイント

ベースURL: `https://post-mesh.com/api/v1`

| メソッド | パス | operationId | 説明 |
|---|---|---|---|
| GET | /connections | listConnections | 有効なSNSアカウント連携を返す |
| POST | /media/upload-url | createMediaUploadUrl | メディアアップロードURLを生成する |
| GET | /posts | listPosts | 投稿一覧を返す（ページネーション付き） |
| POST | /posts | createPost | 投稿を作成・予約する |
| GET | /posts/{id} | getPost | 投稿の詳細を返す |
| DELETE | /posts/{id} | cancelPost | 予約投稿をキャンセルする |

## OpenAPI仕様

- YAML: https://post-mesh.com/openapi.yaml
- JSON: https://post-mesh.com/openapi.json
- Swagger UI: https://post-mesh.com/api-reference

すべてのオペレーションに一意のoperationId、summary、descriptionが付いており、LLMのfunction callingへそのまま変換できます。

## MCPサーバー

```
https://post-mesh.com/api/mcp
```

REST APIと同等の6つのツールを提供します。認証はOAuth（`/oauth/authorize`で同意）と、APIキーのBearerヘッダーの2種類です。OAuthのメタデータはRFC 8414 / RFC 9728に従って以下で配信しています。

- https://post-mesh.com/.well-known/oauth-authorization-server
- https://post-mesh.com/.well-known/oauth-protected-resource

## Agent Skill

```
npx skills add hid3h/post-mesh-agent-skills
```

公開リポジトリ: https://github.com/hid3h/post-mesh-agent-skills

## 認証とエラー

認証は`Authorization: Bearer <APIキー>`ヘッダーのみです。ヘッダーが無い、または不正な場合は401とJSONを返します。

```json
{ "error": { "code": "UNAUTHORIZED", "message": "Missing or invalid Authorization header" } }
```

エラーは常に`error.code`と`error.message`を持つJSONで返します。主なコード:

| HTTPステータス | code | 意味 |
|---|---|---|
| 400 | VALIDATION_ERROR | リクエストのバリデーションに失敗 |
| 400 | TIKTOK_PRIVACY_LEVEL_UNAVAILABLE | そのTikTokアカウントでは選べない公開範囲を指定した |
| 401 | UNAUTHORIZED | APIキーが未指定または無効 |
| 403 | SUBSCRIPTION_REQUIRED | 有効なサブスクリプションが必要 |
| 404 | NOT_FOUND | リソースが見つからない |
| 409 | POSTING_READINESS_RECONNECT_REQUIRED | 投稿作成時、投稿先のSNS連携が切れており再連携が必要 |
| 409 | POSTING_READINESS_UNAVAILABLE | 投稿作成時、SNS側の一時的なエラーで投稿準備を確認できなかった |
| 409 | CONFLICT | 予約投稿をキャンセルできない状態（処理中・キャンセル済み・即時投稿） |
| 500 | INTERNAL_ERROR | 内部サーバーエラー |

## 制限

- 1回の投稿で配信できるSNSは投稿種別ごとに決まっています。テキストはX・Threads・Facebook、画像はX・Instagram・Threads・TikTok・Facebook、動画はX・Instagram・Threads・TikTok・YouTube、ツリー投稿はX・Threadsです。対応していないプラットフォームを投稿先に含めると400 VALIDATION_ERRORになります。
- ツリー投稿（1回の操作でXの連続ポスト・Threadsのスレッドを作る形式）はREST APIとMCPツールの`category: tree`で作成できます。
- Xへの投稿はスタータープランで月30件までです。X以外のSNSへの投稿に件数制限はありません。
- 接続できるSNSアカウント数はスタータープランで10です。
- サンドボックス環境は提供していません。7日間の無料トライアルで本番環境をそのままお試しください。

## 動作確認用エンドポイント

認証なしで到達できます。

```bash
curl https://post-mesh.com/health
# {"status":"ok"}
```

関連: [AIエージェント連携](https://post-mesh.com/agents.md) / [料金](https://post-mesh.com/pricing.md) / [お問い合わせ](https://post-mesh.com/contact.md)