API ドキュメント

認証

MiraiPage APIは2つの認証方式をサポートしています。

1. Bearer Token（外部ツール / Premium）

• Premium プラン限定機能です
• トークンは設定ページから発行できます
• トークンは64文字のランダム文字列です
• 再発行すると既存のトークンは無効になります

2. Cookieセッション（内部Webアプリ）

• ブラウザからログイン済みセッションで自動認証
• プラン不問（active userなら利用可能）

ベースURL

エラーレスポンス

エラー時は以下の構造化形式でレスポンスが返ります。

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request validation failed",
    "fields": [
      {
        "field": "title",
        "code": "REQUIRED",
        "message": "title is required"
      }
    ]
  }
}

一部のエンドポイントでは後方互換のため { "error": "文字列" } 形式も返される場合があります。

認証ユーザー情報

認証済みユーザーのプロフィール情報を取得します。

レスポンス（200）

{
  "id": "uuid",
  "username": "yuho_ito",
  "display_name": "伊東雄歩",
  "subscription_plan": "premium",
  "avatar_url": "https://..."
}

cURL 例

curl https://www.miraipage.net/api/v1/me \
  -H "Authorization: Bearer YOUR_TOKEN"

画像をアップロード

サムネイル / カバー画像を直接アップロードします。返ってきた url を thumbnail_url などに渡してください。

リクエスト (multipart/form-data)

レスポンス (201)

{
  "url": "https://abhrgewzglubansbyitm.supabase.co/storage/v1/object/public/mirainote/posts/<userId>/<uuid>.jpg",
  "path": "posts/<userId>/<uuid>.jpg",
  "file_name": "cover.jpg",
  "file_size": 245678,
  "mime_type": "image/jpeg"
}

curl例

curl -X POST https://www.miraipage.net/api/v1/uploads \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -F "file=@cover.jpg"

投稿を作成

新しい記事を作成します。

リクエストボディ

レスポンス（201）

{
  "id": "uuid",
  "slug": "記事タイトル-lq2x3k",
  "title": "記事タイトル",
  "status": "draft",
  "visibility": "public",
  "post_type": "article",
  "is_paid": false,
  "published_at": null,
  "scheduled_for": null,
  "created_at": "2026-03-15T10:00:00.000Z"
}

cURL 例

curl -X POST https://www.miraipage.net/api/v1/posts \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "AIエージェント実験録",
    "content": "## はじめに\n\n本日の実験結果を報告する。",
    "status": "draft",
    "tags": ["AI", "実験"]
  }'

予約投稿の例

status に "scheduled" を指定し、scheduled_for に未来の ISO 8601 日時を渡します。指定時刻を過ぎると、5分おきに実行されるジョブが自動で published に切り替えます。

curl -X POST https://www.miraipage.net/api/v1/posts \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "木曜の19時に出したい記事",
    "content": "## 本文",
    "status": "scheduled",
    "scheduled_for": "2026-04-16T10:00:00Z"
  }'

投稿一覧を取得

自分の投稿一覧を取得します（削除済みを除く）。

クエリパラメータ

レスポンス（200）

{
  "posts": [
    {
      "id": "uuid",
      "slug": "記事タイトル-lq2x3k",
      "title": "記事タイトル",
      "status": "published",
      "visibility": "public",
      "post_type": "article",
      "is_paid": false,
      "category": "ai",
      "tags": ["AI"],
      "subtitle": null,
      "salon_id": null,
      "salon_only": false,
      "excerpt": "記事の抜粋...",
      "published_at": "2026-03-15T10:00:00.000Z",
      "created_at": "2026-03-15T10:00:00.000Z",
      "updated_at": "2026-03-15T10:00:00.000Z",
      "view_count": 42,
      "like_count": 5,
      "comment_count": 2
    }
  ],
  "total": 42
}

cURL 例

curl "https://www.miraipage.net/api/v1/posts?status=published&post_type=article&limit=10" \
  -H "Authorization: Bearer YOUR_TOKEN"

投稿の詳細を取得

指定した投稿の全フィールドを取得します。

cURL 例

curl https://www.miraipage.net/api/v1/posts/POST_ID \
  -H "Authorization: Bearer YOUR_TOKEN"

サムネイルを設定

指定した投稿のサムネイルを1回でアップロード＋設定します。 既存のサムネイルは上書きされます（ストレージ側のファイルは残ります）。

リクエスト (multipart/form-data)

レスポンス (200)

{
  "post": {
    "id": "...",
    "slug": "...",
    "title": "...",
    "thumbnail_url": "https://abhrgewzglubansbyitm.supabase.co/storage/v1/object/public/mirainote/posts/<userId>/<postId>/thumbnail-<uuid>.jpg",
    "updated_at": "..."
  },
  "upload": {
    "url": "...",
    "path": "...",
    "file_name": "cover.jpg",
    "file_size": 245678,
    "mime_type": "image/jpeg"
  }
}

curl例

curl -X POST https://www.miraipage.net/api/v1/posts/POST_ID/thumbnail \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -F "file=@cover.jpg"

サムネイルを外す場合は同じパスに DELETE を投げてください。

投稿を更新

指定した投稿を部分更新します。投稿作成と同じフィールドが全てオプショナルで指定可能です。

リクエストボディ

{
  "title": "更新後タイトル",
  "content": "更新後の本文",
  "status": "published",
  "category": "business",
  "tags": ["新タグ"],
  "is_paid": true,
  "price_jpy": 500,
  "scheduled_for": "2026-04-20T10:00:00Z"
}

status を "published" に変更すると published_at が自動設定されます。 status を "scheduled" にする場合は scheduled_for（未来のISO 8601日時）も併せて指定してください。 予約を解除する場合は scheduled_for に null を渡します。is_paid の変更には Pro+ プランが必要です。

cURL 例

curl -X PATCH https://www.miraipage.net/api/v1/posts/POST_ID \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"status": "published"}'

投稿を削除

指定した投稿をソフトデリートします（status が "deleted" に変更）。

レスポンス（200）

{ "deleted": true }

cURL 例

curl -X DELETE https://www.miraipage.net/api/v1/posts/POST_ID \
  -H "Authorization: Bearer YOUR_TOKEN"

トークン発行

APIトークンを発行（または再発行）します。このエンドポイントのみセッション認証（ブラウザログイン）で動作します。 通常は設定ページのUIから操作してください。

レスポンス（200）

{ "token": "64文字のAPIトークン" }

Webhook登録

新しいWebhookエンドポイントを登録します。

リクエストボディ

レスポンス（201）

{
  "id": "uuid",
  "url": "https://example.com/webhooks",
  "secret": "64文字のHMACシークレット",
  "event_types": ["post.created", "post.published"],
  "status": "active",
  "description": "My webhook",
  "created_at": "2026-04-13T12:00:00.000Z"
}

secret は作成時のレスポンスでのみ返却されます。安全に保管してください。

cURL 例

curl -X POST https://www.miraipage.net/api/v1/webhooks \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/webhooks",
    "event_types": ["post.created", "post.published"],
    "description": "Notify on new posts"
  }'

Webhook一覧

登録済みWebhookの一覧を取得します（secretは含まれません）。

Webhook詳細

指定したWebhookの詳細を取得します（secretは含まれません）。

Webhook更新

Webhookの設定を更新します。url, event_types, status, description を変更可能です。

disabled → active への変更時に consecutive_failures がリセットされます。

Webhook削除

Webhookを完全削除します（配信ログも削除されます）。

配信ログ

Webhookの配信ログを取得します。

クエリパラメータ

テストイベント送信

pingイベントを送信してWebhookの疎通確認を行います。

レスポンス（200）

{
  "success": true,
  "http_status": 200,
  "response_time_ms": 150
}

Webhookイベント一覧

Webhookペイロード形式

{
  "event": "post.created",
  "event_id": "post.created:uuid",
  "created_at": "2026-04-13T12:00:00.000Z",
  "data": {
    "post": {
      "id": "uuid",
      "slug": "記事タイトル-lq2x3k",
      "title": "記事タイトル",
      "status": "published",
      "post_type": "article",
      "visibility": "public",
      "is_paid": false,
      "published_at": "2026-04-13T12:00:00.000Z",
      "created_at": "2026-04-13T12:00:00.000Z"
    }
  }
}

• post.updated: data.changes に変更フィールド名のリストが追加
• post.deleted: data.post に削除前の id, title を含む
• content（本文）はペイロードに含まれません

署名検証（HMAC-SHA256）

各Webhook配信には X-MiraiPage-Signature ヘッダーが含まれます。

Node.js での検証例:

const crypto = require('crypto');

const expected = crypto
  .createHmac('sha256', WEBHOOK_SECRET)
  .update(rawBody)
  .digest('hex');

const actual = req.headers['x-miranote-signature']
  .split('sha256=')[1];

const valid = crypto.timingSafeEqual(
  Buffer.from(expected),
  Buffer.from(actual)
);

タイミングセーフ比較を使用してください（timing attack対策）。

リトライポリシー

• 2xxレスポンスで成功判定
• 失敗時は最大5回までリトライ（バックオフ: 1分 → 5分 → 30分 → 2時間 → 12時間）
• 5回連続失敗でWebhookが自動無効化（status → disabled）

制限事項

• 1ユーザーあたり最大10件のWebhook登録
• レスポンスタイムアウト: 10秒
• ペイロードに content（本文）は含まれません

注意事項

• APIは自分の投稿のみ操作可能です（他ユーザーの投稿にはアクセスできません）
• トークンは秘密情報です。公開リポジトリやクライアントサイドコードに含めないでください
• slug は投稿作成時に自動生成されます（更新不可）
• excerpt（抜粋）は content から自動抽出されます

公開投稿一覧

公開済みの投稿一覧を取得します。

クエリパラメータ

レスポンス（200）

{
  "posts": [
    {
      "id": "uuid",
      "slug": "AIエージェントの今-lq2x3k",
      "title": "AIエージェントの今",
      "excerpt": "記事の抜粋...",
      "category": "ai",
      "tags": ["AI", "エージェント"],
      "published_at": "2026-03-15T10:00:00.000Z",
      "view_count": 120,
      "like_count": 15,
      "save_count": 5,
      "comment_count": 3,
      "resonated_count": 2,
      "author": {
        "username": "yuho_ito",
        "display_name": "伊東雄歩",
        "avatar_url": "https://..."
      }
    }
  ],
  "total": 42
}

cURL 例

curl "https://www.miraipage.net/api/v1/public/posts?sort=popular&category=ai&limit=5"

公開投稿詳細

指定した公開投稿の詳細を取得します。本文（content）を含みます。

有料記事の場合は free_preview_length 分の本文のみ返されます。

cURL 例

curl https://www.miraipage.net/api/v1/public/posts/POST_ID

ランキング

ランキングを取得します。4種類のランキングタイプに対応。

クエリパラメータ

ランキングタイプ

レスポンス（200）

{
  "type": "trending",
  "period_start": "2026-03-08T00:00:00.000Z",
  "period_end": "2026-03-15T12:00:00.000Z",
  "rankings": [
    {
      "rank": 1,
      "score": 42.5,
      "post": {
        "id": "uuid",
        "title": "AIエージェントの今",
        "slug": "AIエージェントの今-lq2x3k",
        "like_count": 15,
        "author": {
          "username": "yuho_ito",
          "display_name": "伊東雄歩",
          "avatar_url": "https://..."
        }
      }
    }
  ]
}

cURL 例

curl "https://www.miraipage.net/api/v1/public/ranking?type=weekly&limit=10"

カテゴリ一覧

利用可能なカテゴリの一覧を取得します。

レスポンス（200）

{
  "categories": [
    { "value": "ai", "label": "AI・テクノロジー" },
    { "value": "business", "label": "ビジネス・起業" },
    ...
  ]
}

cURL 例

curl https://www.miraipage.net/api/v1/public/categories

ユーザー公開プロフィール

ユーザーの公開プロフィールと最新投稿を取得します。

レスポンス（200）

{
  "profile": {
    "username": "yuho_ito",
    "display_name": "伊東雄歩",
    "bio": "AI文明設計者",
    "avatar_url": "https://...",
    "follower_count": 120,
    "post_count": 42,
    "is_verified": true
  },
  "posts": [
    {
      "id": "uuid",
      "title": "記事タイトル",
      "slug": "記事タイトル-lq2x3k",
      "published_at": "2026-03-15T10:00:00.000Z",
      "like_count": 5
    }
  ]
}

cURL 例

curl https://www.miraipage.net/api/v1/public/users/yuho_ito