MiraiNote

API ドキュメント

MiraiNote Public API v1 — 外部ツールから投稿をプログラマティックに管理

認証

全てのAPIリクエストには Authorization ヘッダーが必要です。

ヘッダー

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

ベースURL

https://mirainote.vercel.app /api/v1

エラーレスポンス

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

{
  "error": "エラーメッセージ"
}
ステータス説明
400リクエストが不正
401認証エラー（トークンが無効）
403アクセス権限なし（Premiumプラン必要）
404リソースが見つからない
500サーバーエラー

投稿を作成

POST/api/v1/posts

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

リクエストボディ

フィールド型必須説明
titlestring必須記事タイトル（100文字以内）
contentstring必須Markdown本文
statusstring-"draft"（デフォルト）または "published"
categorystring-カテゴリ（ai, business, career 等）
tagsstring[]-タグ配列（最大10個）

レスポンス（201）

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

cURL 例

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

投稿一覧を取得

GET/api/v1/posts

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

クエリパラメータ

パラメータ型説明
statusstringdraft / published / archived でフィルタ
limitnumber取得件数（1〜100、デフォルト: 20）
offsetnumberオフセット（デフォルト: 0）

レスポンス（200）

{
  "posts": [
    {
      "id": "uuid",
      "slug": "記事タイトル-lq2x3k",
      "title": "記事タイトル",
      "status": "published",
      "category": "ai",
      "tags": ["AI"],
      "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://mirainote.vercel.app
/api/v1/posts?status=published&limit=10" \
  -H "Authorization: Bearer YOUR_TOKEN"

投稿の詳細を取得

GET/api/v1/posts/:id

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

cURL 例

curl https://mirainote.vercel.app
/api/v1/posts/POST_ID \
  -H "Authorization: Bearer YOUR_TOKEN"

投稿を更新

PATCH/api/v1/posts/:id

指定した投稿を部分更新します。全フィールドはオプショナルです。

リクエストボディ

{
  "title": "更新後タイトル",
  "content": "更新後の本文",
  "status": "published",
  "category": "business",
  "tags": ["新タグ"]
}

status を "published" に変更すると、published_at が自動設定されます。

cURL 例

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

投稿を削除

DELETE/api/v1/posts/:id

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

レスポンス（200）

{ "deleted": true }

cURL 例

curl -X DELETE https://mirainote.vercel.app
/api/v1/posts/POST_ID \
  -H "Authorization: Bearer YOUR_TOKEN"

トークン発行

POST/api/v1/token

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

レスポンス（200）

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

注意事項

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

Public API（認証不要）

以下のエンドポイントは認証なしでアクセスできます。公開済みの投稿・ランキング・ユーザー情報を取得できます。

公開投稿一覧

GET/api/v1/public/posts

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

クエリパラメータ

パラメータ型説明
sortstringlatest / popular / trending（デフォルト: latest）
categorystringカテゴリでフィルタ（ai, business 等）
tagstringタグでフィルタ
limitnumber取得件数（1〜100、デフォルト: 20）
offsetnumberオフセット（デフォルト: 0）

レスポンス（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://mirainote.vercel.app
/api/v1/public/posts?sort=popular&category=ai&limit=5"

公開投稿詳細

GET/api/v1/public/posts/:id

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

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

cURL 例

curl https://mirainote.vercel.app
/api/v1/public/posts/POST_ID

ランキング

GET/api/v1/public/ranking

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

クエリパラメータ

パラメータ型説明
typestringtrending / weekly / monthly / saved（デフォルト: trending）
limitnumber取得件数（1〜100、デフォルト: 20）

ランキングタイプ

タイプ説明
trending時間減衰付きエンゲージメントスコア（15分更新）
weekly直近7日間のエンゲージメント合計（1時間更新）
monthly直近30日間のエンゲージメント合計（6時間更新）
saved保存数ランキング（6時間更新）

レスポンス（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://mirainote.vercel.app
/api/v1/public/ranking?type=weekly&limit=10"

カテゴリ一覧

GET/api/v1/public/categories

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

レスポンス（200）

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

cURL 例

curl https://mirainote.vercel.app
/api/v1/public/categories

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

GET/api/v1/public/users/:username

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

レスポンス（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://mirainote.vercel.app
/api/v1/public/users/yuho_ito
ホームに戻る