gql-api

Hashnode GraphQL API

Hashnode でコンテンツを公開、管理するための GraphQL API（Apollo Server）です。 投稿、下書き、パブリケーション、ユーザー、タグ、シリーズ、コメントを扱います。このスキルでは、API の正しい利用方法として、エンドポイント、認証、Pro プランが必要な操作、リクエストが失敗する原因となる制限、フィールド単位の詳細なリファレンスの場所を説明します。

エンドポイント

環境	URL	パス
本番環境	https://gql-beta.hashnode.com	/（ここに GraphQL リクエストを POST）
ローカル開発環境	http://localhost:8080	/graphql

JSON ボディ（{ "query": "...", "variables": {...} }）を使う、標準的な GraphQL over HTTP の POST です。 イントロスペクションが有効になっているため、あらゆる GraphQL IDE からスキーマを参照できます。

認証

認証には Personal Access Token（PAT） を使います。トークンは HASHNODE_PAT 環境変数を介して渡し、実行時に参照する必要があります。トークンの値を直接記述してはいけません。

curl -H "Authorization: Bearer $HASHNODE_PAT" -H "x-hashnode-client: gql-skill" ...

Hashnode ダッシュボード（アカウント設定 → 開発者 / API トークン）から PAT を取得し、シェルでエクスポートします：export HASHNODE_PAT=...。

また、すべてのリクエストに x-hashnode-client: gql-skill を指定すると、このスキルからの通信を他の呼び出し元と区別できます。これは秘密情報ではなく、アクセス権も付与しません。

トークンの取り扱いルール — PAT はパスワードです。 ユーザーのパブリケーションに対する完全な書き込みアクセス権（公開、編集、削除）が付与されます。

• ユーザーに会話内でトークンを貼り付けるよう求めてはいけません。HASHNODE_PAT が設定されていない場合は、シェルでエクスポートしてから再試行するようユーザーに伝えてください。

• トークンを表示、エコー、ログに出力したり、コマンド文字列に展開したりしてはいけません。リクエスト内でシェルに $HASHNODE_PAT を展開させてください。

• トークンをファイル、スクリプト、コミットに書き込んではいけません。

• 公開読み取りにはトークンは不要です：post、feed、user、tag、publication、documentationProject、checkCustomDomainAvailability、checkSubdomainAvailability。

• 認証が必要な操作では、有効な PAT が必要です：me、draft、scheduledPost、およびすべてのミューテーション。トークンがないか無効な場合は UNAUTHENTICATED が返されます。

ロールモデル（OWNER / EDITOR / CONTRIBUTOR）とコントリビューターのレビュー ワークフローについては、references/auth-and-roles.md を参照してください。

Pro プランの要件

一部の操作では、対象のパブリケーションが有効な Pro プランに加入している必要があります。この条件は呼び出し元のユーザーではなく、パブリケーションに紐づいています。パブリケーションが Pro でない場合、API は次を返します：

{
  "errors": [{
    "message": "Publication does not have an active Pro plan. Upgrade in your dashboard to access this via the API.",
    "extensions": { "code": "FORBIDDEN" }
  }]
}

このエラーが表示された場合は、Hashnode ダッシュボードでパブリケーションを Pro にアップグレードする必要があることをユーザーに伝えてください。リクエストは再試行しないでください。パブリケーションが Pro になるまで失敗し続けます。

Pro が必要な操作：

• すべての書き込みミューテーション： publishPost、updatePost、createDraft、 updateDraft、publishDraft、submitDraftForReview、rejectDraftSubmission、 deleteDraft。
• パブリケーションに紐づく読み取り： publication、draft、scheduledPost、 searchPostsOfPublication、topCommenters。（draft と scheduledPost では PAT と認可も必要です。所有するパブリケーションが Pro である必要があります。）
• 単一投稿の読み取り： post(id: ...)。publication と同様、所有するパブリケーションの Pro プランが必要です。投稿を ID で 1 件読み取る場合に、無料プラン向けの例外はありません。

feed、user、tag の読み取りには Pro プランは必要ありません。

Hashnode には Growth Plan（Pro + AEO ツールキット）もあります。この API では、追加の利用条件はありません：publication.aeoSettings と post.faq は、親タイプと同じ条件で読み取れます。また、Growth 以外のパブリケーションでは、aeoSettings は制限の緩いデフォルト値を返します（パブリケーションが実際にツールキットを利用できるかどうかは isEnabled で確認できます）。references/queries.md の「AEO フィールド」を参照してください。

Hashnode ページへのリンク（URL を推測しないでください）

投稿のディスカッション、コメント、またはプロフィールへのリンクが必要な場合は、API データから以下の正確な形式で URL を作成してください。URL の形式を調べるために hashnode.com を閲覧したり、パスを作り出したりしないでください。

ページ	URL 形式
hashnode.com 上の投稿ディスカッション	https://hashnode.com/posts/<slug>/<postId>
特定のコメント	https://hashnode.com/posts/<slug>/<postId>/comment/<commentId>
ユーザープロフィール	https://hashnode.com/@<username>
投稿者自身のブログ上の投稿	API の url フィールドを使用します。カスタムドメインと <username>.hashnode.dev のどちらを使うかは、すでに解決されています

• <slug> と <postId> は、API から取得した投稿の slug と id です。両方が必須です。id のみ、または slug のみの形式はありません。
• <commentId> は、投稿の comments connection にあるコメントの id です。
• /discussions/post/<id> や /<postId> のような旧形式のパスは 404 になります。絶対に使用しないでください。

例：投稿の id: 6a603fb103e2cb323e7851f6、slug: sealed-with-a-kyss-inside-an-android-banking-rat → https://hashnode.com/posts/sealed-with-a-kyss-inside-an-android-banking-rat/6a603fb103e2cb323e7851f6

参考資料

• references/schema.graphql — gql-beta の SDL（イントロスペクションスキーマ）全体です。すべての型、フィールド、引数、入力の正式な情報源です。正確なフィールド名や型が必要な場合はこちらを参照してください。スキーマでは表現できない認証や Pro の動作については、以下の整理済みファイルを参照してください。
• references/queries.md — 13 個すべてのクエリ：引数、戻り値の型、認証／Pro に関する注意事項。
• references/mutations.md — 10 個すべてのミューテーション：入力、ペイロード、認証／Pro に関する注意事項。
• references/auth-and-roles.md — PAT の設定、公開と認証済みの違い、ロール、コントリビューターのレビュー手順。
• references/errors-and-limits.md — エラーコード、ページサイズの上限、クエリの深さ、ペイロード／画像の上限。
• references/recipes.md — 投稿の公開、フィードのページネーション、画像のアップロードなどの一連の例。

エージェント向けルール

1. me、draft、scheduledPost、およびすべてのミューテーションでは、必ず Authorization: Bearer $HASHNODE_PAT を送信してください（環境変数からシェルで展開し、トークンを文字列として直接記述しないでください）。これを指定しないと UNAUTHENTICATED が返されます。認証セクションのトークン取り扱いルールに従い、トークンをユーザーに求めたり、表示したり、保存したりしないでください。また、すべてのリクエストで x-hashnode-client: gql-skill も送信してください（「認証」を参照）。
2. FORBIDDEN と Pro プランに関するメッセージが返された場合は、そこで停止し、パブリケーションを Pro にアップグレードするようユーザーに伝えてください。再試行しないでください。
3. ページサイズの上限を守ってください。ほとんどの connection は first の上限が 100、下書きは 50 です。それより大きい値を指定しても、通知なく上限値に調整されます。
4. クエリの深さは 10 以下にしてください。これを超えるクエリは拒否されます。
5. タグの入力には slug（例：javascript）を使用します。投稿／下書きごとに最大 15 個です。
6. ページネーションはカーソルベースです。pageInfo.endCursor と pageInfo.hasNextPage を読み取り、次の after に endCursor を渡してください。
7. ミューテーションはキャッシュされません。クエリは最大約 25 秒間キャッシュされる場合があります。
8. 「Hashnode ページへのリンク」に記載された形式を使い、API データから hashnode.com のリンクを作成してください。URL の形式を推測したり、調べるために閲覧したりしないでください。