Public API

このページは、現在 /api/v1 で実際に公開されているルートだけを対象にしています。現時点の公開 v1 API は、posts、sites、webhooks のみです。

クイックスタート

ベース URL

https://postion.app/api/v1

認証

すべてのリクエストで Bearer Token が必要です。

Authorization: Bearer pk_your_api_key_here

レート制限

各 API キーは、各 endpoint ごとに 100 リクエスト/分に制限されます。レスポンスには以下のヘッダーが含まれます。

• X-RateLimit-Limit
• X-RateLimit-Remaining
• X-RateLimit-Reset

スコープ

連携ごとに最小限のスコープを付与してください。

レスポンスの基本形

多くの成功レスポンスは data ラッパーを使います。

{
  "data": {}
}

一覧系では pagination も返ります。

{
  "data": [],
  "pagination": {
    "page": 1,
    "limit": 10,
    "total": 42,
    "pages": 5
  }
}

バリデーション失敗や認証失敗では error が返り、一部のレスポンスには details や resetTime が含まれます。

エンドポイント

GET /api/v1/posts

認証済みユーザー自身の投稿一覧を返します。

クエリパラメータ

例

curl "https://postion.app/api/v1/posts?page=1&limit=10&published=true" \
  -H "Authorization: Bearer pk_your_api_key_here"

各投稿には以下が含まれます。

• id、title、description、slug、image
• status、published、public、isPaid
• pricing
• site
• tags
• stats.likes、stats.comments、stats.bookmarks
• createdAt、updatedAt

POST /api/v1/posts

自分のサイトに新しい投稿を作成します。

ボディ

注意点

• slug は同一サイト内で一意です。重複時は 409 Conflict を返します。
• status: "published" または status: "draft" だけを送り、published を省略した場合、API は boolean 側も自動で同期します。
• title から有効な slug を生成できない場合は、自動生成 slug にフォールバックします。
• pricing 内の Decimal 値は、レスポンスで文字列として返る場合があります。

例

{
  "title": "API launch checklist",
  "siteId": "site_123",
  "description": "公開 API のロールアウト前に確認すること",
  "published": true,
  "tags": ["api", "launch"],
  "public": true
}

GET /api/v1/posts/{id}

単一投稿を返します。content、tags、pricing、site、stats を含みます。

PUT /api/v1/posts/{id}

自分の投稿を更新します。

現在更新できるフィールド：

• title
• content
• description
• slug
• image
• status
• published
• tags

tags を送った場合、既存タグはすべてその配列で置き換えられます。status だけを draft または published に更新した場合も、published フラグは自動で同期されます。

DELETE /api/v1/posts/{id}

投稿をソフトデリートします。レスポンスは以下です。

{
  "message": "Post deleted successfully"
}

GET /api/v1/sites

認証ユーザーが所有するサイト一覧を返します。

各サイトには以下が含まれます。

• id、name、description、logo
• subdomain、customDomain
• createdAt、updatedAt
• stats.posts

GET /api/v1/webhooks

認証ユーザーの Webhook 一覧を返します。

クエリパラメータ

レスポンスには以下が含まれます。

• data: Webhook 一覧
• availableEvents: サポートされているイベント一覧

セキュリティ上、一覧 API では webhook secret は返しません。

POST /api/v1/webhooks

新しい Webhook を作成します。

ボディ

サポートイベント

• post.created
• post.published
• post.deleted
• user.registered
• user.updated
• site.created
• subscription.created
• subscription.cancelled
• test.event

作成レスポンスには webhook の secret が含まれます。一覧 API では再取得できないため、作成時に保存してください。

Webhook 配信

Webhook は生のリクエストボディに対する HMAC-SHA256 で署名され、X-Webhook-Signature ヘッダーで送信されます。

各配信には以下のヘッダーが付きます。

• X-Webhook-Signature
• X-Webhook-Event
• X-Webhook-Delivery
• User-Agent: Position-Webhooks/1.0

Payload 形式：

{
  "id": "delivery_payload_id",
  "event": {
    "type": "post.published",
    "data": {},
    "timestamp": "2026-04-04T12:00:00.000Z",
    "site_id": "site_123",
    "user_id": "user_123"
  },
  "webhook": {
    "id": "webhook_123",
    "name": "Production Listener"
  }
}

検証方法やハンドラ実装の詳細は Webhooks を参照してください。

エラーコード

実装のヒント

• API キーは必ずサーバー側だけに保存してください。
• Webhook 作成時に secret を保存してください。
• 連携の同期はポーリングより Webhook を優先してください。
• DELETE /posts/{id} は物理削除ではなくソフトデリートです。

バージョニング

API は URL パスでバージョン管理されます。破壊的変更は /api/v2 のような新しいパスで公開されます。