gql-api

Hashnode GraphQL API

用于在 Hashnode 上发布和管理内容的 GraphQL API（Apollo Server）： 文章、草稿、Publication、用户、标签、系列和评论。本技能会告诉 Agent 如何正确使用该 API——端点、身份验证、哪些操作需要 Pro 计划、 会导致请求失败的限制，以及在哪里查找完整的字段级参考。

端点

环境	URL	路径
Production	https://gql-beta.hashnode.com	/（在此处 POST GraphQL 请求）
Local dev	http://localhost:8080	/graphql

通过 HTTP POST 使用标准 GraphQL，并在 JSON 请求体中传入数据（{ "query": "...", "variables": {...} }）。 已启用内省，因此可通过任何 GraphQL IDE 浏览架构。

身份验证

身份验证使用个人访问令牌（PAT）。必须通过 HASHNODE_PAT 环境变量提供令牌，并在执行时通过引用传递—— 切勿直接写入令牌值：

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

从 Hashnode 控制面板（Account Settings → Developer / API tokens） 获取 PAT，并在 shell 中导出：export HASHNODE_PAT=...。

每次请求还要发送 x-hashnode-client: gql-skill，以便 API 区分此 技能的流量与其他调用方。这不是机密信息，不会授予任何访问权限。

令牌处理规则——PAT 就是密码。 它可完全写入用户的 Publication（发布、编辑、删除）：

• 切勿要求用户在对话中粘贴令牌。如果未设置 HASHNODE_PAT， 请告知用户在 shell 中导出该变量，然后重试。

• 切勿打印、回显或记录令牌，也切勿将其展开到命令字符串中—— 始终让 shell 在请求本身中插值 $HASHNODE_PAT。

• 切勿将令牌写入文件、脚本或提交。

• 公开读取无需令牌：post、feed、user、tag、publication、 documentationProject、checkCustomDomainAvailability、checkSubdomainAvailability。

• 需要身份验证的操作需要有效 PAT：me、draft、scheduledPost 以及所有 mutation。缺少令牌或令牌无效时会返回 UNAUTHENTICATED。

关于角色模型（OWNER / EDITOR / CONTRIBUTOR）和贡献者审核工作流，请参阅 references/auth-and-roles.md。

Pro 计划限制

某些操作要求目标 Publication拥有有效的 Pro 计划。 限制取决于 Publication，而非发起调用的用户。如果 Publication 没有 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 控制面板中将 Publication 升级到 Pro。不要重试请求——在 Publication 开通 Pro 之前，请求会持续失败。

受 Pro 计划限制的操作：

• 所有写入 mutation： publishPost、updatePost、createDraft、 updateDraft、publishDraft、submitDraftForReview、rejectDraftSubmission、 deleteDraft。
• Publication 范围内的读取： publication、draft、scheduledPost、 searchPostsOfPublication、topCommenters。（draft 和 scheduledPost 还需要 PAT 和相应授权；所属 Publication 必须开通 Pro。）
• 单篇文章读取： post(id: ...)。与 publication 一样，取决于所属 Publication 是否开通 Pro。通过 id 读取单篇文章没有免费版例外。

feed、user 和 tag 读取不受 Pro 计划限制。

Hashnode 还提供 Growth Plan（Pro + AEO 工具包）。它不会为此 API 增加任何新限制： publication.aeoSettings 和 post.faq 按其父类型的相同规则读取；对于非 Growth Publication，aeoSettings 会采用宽松默认值解析（isEnabled 用于指示 Publication 是否实际拥有该工具包）。请参阅 references/queries.md 中的“AEO 字段”。

链接到 Hashnode 页面（切勿猜测 URL）

需要链接到 hashnode.com 上的文章讨论、评论或个人资料时，请使用 API 数据按以下精确格式构建 URL。不要浏览 hashnode.com 来查找 URL 规则，也不要自行编造路径。

页面	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 连接中的评论 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 — 端到端示例：发布文章、对信息流分页、上传图片。

Agent 规则

1. 对 me、draft、scheduledPost 和任何变更操作，始终发送 Authorization: Bearer $HASHNODE_PAT（从环境变量中通过 shell 插值，绝不能使用字面量令牌）。否则会收到 UNAUTHENTICATED。遵循“身份验证”部分的令牌处理规则：不要索要、打印或持久化令牌。 每次请求还要发送 x-hashnode-client: gql-skill（参见“身份验证”）。
2. 遇到 FORBIDDEN 且消息说明需要 Pro 方案时，停止操作并告知用户将 publication 升级到 Pro。不要重试。
3. 遵守分页大小上限：大多数连接的 first 上限为 100，草稿上限为 50。超过上限的请求会被静默截断。
4. 查询深度不得超过 10；更深的查询会被拒绝。
5. 标签输入使用 slug（例如 javascript），每篇文章或草稿最多 15 个。
6. 分页基于游标：读取 pageInfo.endCursor / pageInfo.hasNextPage，并将 endCursor 作为下一个请求的 after。
7. 变更操作不会缓存；查询最多可能缓存约 25s。
8. 根据 API 数据，使用“链接到 Hashnode 页面”中的格式构建 hashnode.com 链接。切勿猜测 URL 规则或通过浏览来查找。