v1.0 to v2.0

- description: Publish, update and read blog posts on Hashnode via its GraphQL API. Use when the user mentions Hashnode, publishing a blog post to Hashnode, cross-posting an article to their Hashnode blog, saving a Hashnode draft, updating a published Hashnode post, or listing their Hashnode publications and posts.

- Trigger when the user wants to publish a Markdown article to their

- Hashnode blog, save it as a draft, update a previously published

- post, or list / inspect their own Hashnode publications and posts.

- The connector stores a Hashnode Personal Access Token with full

- account access — confirm before publishing publicly (you can save a

- draft first with the createDraft mutation).

- allowed_tools: [Bash]

- version: "1.0"

- Call the **Hashnode GraphQL API** with `curl + jq`. The user's Personal Access

- Token is in `$HASHNODE_TOKEN`. Single endpoint: `https://gql-beta.hashnode.com`

- (always `POST` a JSON body `{query, variables}`).

-

- > The old `https://gql.hashnode.com` host is **deprecated** — it now 301-redirects

- > to a changelog page and returns HTML, not JSON. Always use `gql-beta.hashnode.com`.

-

- Every request needs these headers:

- ```

- Authorization: Bearer $HASHNODE_TOKEN

- Content-Type: application/json

- ```

- GraphQL always returns HTTP `200`; real failures live in the JSON `errors`

- array — always inspect it and show it verbatim. Two error cases matter:

- - `Unauthorized` / `not authenticated` → the token is invalid → the user must

- re-connect the Hashnode connector.

- - `extensions.code == "FORBIDDEN"` with a message like *"Publication does not have

- an active Pro plan"* → this is **not** a token problem. As of 2026-05-13 Hashnode

- moved its API behind a paid plan: **every write mutation** (`publishPost`,

- `createDraft`, `updatePost`) **and publication-scoped reads require the target

- publication to be on [Hashnode Pro](https://hashnode.com/pro)**. Do NOT tell the

- user to reconnect and do NOT retry in a loop — tell them the publication owner

- must upgrade to Hashnode Pro (blog dashboard → Billing → Upgrade to Pro), after

- which the API works immediately. Public reads (posts/feeds/users/tags) stay free.

- Helper — send a query/mutation (`$1` = query string, `$2` = variables JSON):

- ```bash

- gql() {

- jq -n --arg q "$1" --argjson v "${2:-null}" '{query:$q, variables:$v}' \

- | curl -sS -X POST https://gql-beta.hashnode.com \

- -H "Authorization: Bearer $HASHNODE_TOKEN" \

- -H "Content-Type: application/json" \

- -d @-

- }

- ## Always start by confirming the token and finding the publication id

-

- `publishPost` / `createDraft` need a `publicationId`. Fetch the account and its

- publications first (a user can have several blogs):

- ```bash

- gql 'query { me { id username publications(first: 10) { edges { node { id title url } } } } }' \

- | jq '{me: .data.me.username, publications: [.data.me.publications.edges[].node | {id, title, url}], errors: .errors}'

- ```

- Pick the target blog's `id` (that is the `publicationId`). If the user has

- exactly one publication, use it; otherwise ask which blog to post to.

- ## Publish a post

- **Confirm with the user before publishing publicly.** If they are not sure, save

- a draft first (see below). `tags` is required — supply 1–5 tags, each as

- `{name, slug}` (slug lowercase, no spaces).

- ```bash

- PUB_ID="PUBLICATION_ID" # from the me query above

- TITLE="My title"

- BODY_MD="$(cat article.md)" # full Markdown body

- VARS=$(jq -n --arg p "$PUB_ID" --arg t "$TITLE" --arg b "$BODY_MD" '{

- input: {

- publicationId: $p,

- title: $t,

- contentMarkdown: $b,

- tags: [{name:"AI", slug:"ai"}, {name:"Web Development", slug:"web-development"}]

- }

- }')

- gql 'mutation PublishPost($input: PublishPostInput!) {

- publishPost(input: $input) { post { id slug url title } }

- }' "$VARS" | jq '{post: .data.publishPost.post, errors: .errors}'

- Useful optional `input` fields:

-

- - `subtitle` — post subtitle.

- - `slug` — custom URL slug (otherwise derived from the title).

- - `canonicalUrl` / `originalArticleURL` — when cross-posting, point SEO back to

- the original source. Set this whenever the same article also lives elsewhere.

- - `coverImageOptions: { coverImageURL: "https://..." }` — cover image.

- - `publishedAt` — ISO-8601 timestamp to backdate; `disableComments` etc. live

- under `settings`.

-

- ## Save a draft (safe, non-public)

-

- Use this when the user has not explicitly approved public publishing:

-

- ```bash

- VARS=$(jq -n --arg p "$PUB_ID" --arg t "$TITLE" --arg b "$BODY_MD" '{

- input: { publicationId: $p, title: $t, contentMarkdown: $b }

- }')

- gql 'mutation CreateDraft($input: CreateDraftInput!) {

- createDraft(input: $input) { draft { id slug title } }

- }' "$VARS" | jq '{draft: .data.createDraft.draft, errors: .errors}'

- ## Update a published post

-

- `updatePost` needs the post `id` (from `publishPost`, or the list query below):

- ```bash

- VARS=$(jq -n --arg id "POST_ID" --arg b "$(cat article.md)" '{

- input: { id: $id, contentMarkdown: $b }

- }')

- gql 'mutation UpdatePost($input: UpdatePostInput!) {

- updatePost(input: $input) { post { id url title } }

- }' "$VARS" | jq '{post: .data.updatePost.post, errors: .errors}'

- ## List / inspect my posts

-

- ```bash

- gql 'query { me { posts(pageSize: 20, page: 1) { nodes { id title slug url views reactionCount responseCount publishedAt } } } }' \

- | jq '[.data.me.posts.nodes[] | {id, title, url, views, reactions: .reactionCount, responses: .responseCount}]'

- ```

- Single post with full content + stats:

- ```bash

- gql 'query GetPost($id: ObjectId!) { post(id: $id) { title url views reactionCount responseCount content { markdown } } }' \

- "$(jq -n --arg id "POST_ID" '{id:$id}')" | jq '.data.post | {title, url, views, reactions: .reactionCount}'

- - **Endpoint is `https://gql-beta.hashnode.com`** — the old `gql.hashnode.com`

- host is deprecated (301 → HTML changelog page, never valid GraphQL JSON).

- - **`Authorization: Bearer $HASHNODE_TOKEN`** — send the token with the `Bearer`

- prefix (this is what Hashnode's own official skill uses).

- - **Pro plan required for writes** — since 2026-05-13, `publishPost` / `createDraft`

- / `updatePost` and publication-scoped reads only work if the target publication

- has an active **Hashnode Pro** plan; otherwise the call returns a `FORBIDDEN`

- *"does not have an active Pro plan"* error. That is a billing state on the user's

- blog, not something the skill or a reconnect can fix — surface it and stop.

- - **`publicationId` is mandatory** for publishing/drafting — never guess it, read

- it from the `me` query.

- - **`tags` is required on `publishPost`** — supply at least one `{name, slug}`;

- slug must be lowercase with hyphens (e.g. `machine-learning`).

- - **`errors` on HTTP 200** — GraphQL reports failures in the `errors` array, not

- via status codes; always surface them.

- - **Idempotency** — re-running `publishPost` creates a *new* post each time; to

- change an existing one use `updatePost` with its `id`.

-