# APIリファレンス

ポストメッシュのREST APIリファレンスです。ブラウザで操作できるSwagger UIは https://post-mesh.com/api-reference にあります。

- ベースURL: `https://post-mesh.com/api/v1`
- OpenAPI仕様（YAML）: https://post-mesh.com/openapi.yaml
- OpenAPI仕様（JSON）: https://post-mesh.com/openapi.json

機械可読な仕様が必要な場合は、このページではなく上記のOpenAPI仕様を直接取得してください。すべてのオペレーションに一意のoperationId、summary、description、型付きのリクエスト・レスポンススキーマが定義されています。

## 認証

```
Authorization: Bearer <APIキー>
```

APIキーはログイン後のダッシュボード「APIキー」画面から発行します。

## オペレーション一覧

| メソッド | パス | 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 | 予約投稿をキャンセルする |

## レスポンス形式

単一リソースは`data`に包んで返します。

```json
{ "data": { "id": "...", "status": "scheduled" } }
```

一覧は`data`と`pagination`を返します。

```json
{ "data": [], "pagination": { "total": 0, "page": 1, "limit": 20, "has_next": false } }
```

エラーは`error.code`と`error.message`を返します。

```json
{ "error": { "code": "VALIDATION_ERROR", "message": "..." } }
```

プロパティ名はスネークケースです。日時はISO 8601形式の文字列で返します。

## 投稿の流れ

1. `GET /connections` で投稿先のSNSアカウントIDを取得する
2. 画像・動画を投稿する場合は `POST /media/upload-url` でアップロードURLを取得し、そのURLへファイルをアップロードする
3. `POST /posts` で投稿を作成する。即時投稿と日時指定の予約投稿のどちらも指定できる
4. `GET /posts/{id}` でプラットフォームごとの結果を確認する

関連: [開発者向け](https://post-mesh.com/developers.md) / [AIエージェント連携](https://post-mesh.com/agents.md)