API guide

The Hashnode API in 2026.Every request now needs Pro.

To publish to Hashnode from code, send a publishPost mutation to https://gql-beta.hashnode.com/ with a Personal Access Token from hashnode.com/settings/developer. Since May 13, 2026, every request that reads or writes a blog needs Hashnode Pro on that blog, $5 a month per seat. The old gql.hashnode.com address now redirects to Hashnode's announcement.

Checked October 8, 2026. Breakreach is our product.

# 1. Upload the cover: get an upload URL, PUT the file, confirm itcurl https://gql-beta.hashnode.com/ \  -H "Authorization: Bearer $HASHNODE_PAT" \  -H "Content-Type: application/json" \  -d '{"query": "mutation ($i: CreateImageUploadInput!) { createImageUploadURL(input: $i) { presignedPut { url key cdnUrl } } }",    "variables": {"i": {"contentType": "image/jpeg"}}}'curl -X PUT "$UPLOAD_URL" -H "Content-Type: image/jpeg" --data-binary @roastery.jpg# then confirmImageUpload(input: { key }) answers ok and the cdnUrl # 2. Publish the post (the blog needs Hashnode Pro)curl https://gql-beta.hashnode.com/ \  -H "Authorization: Bearer $HASHNODE_PAT" \  -H "Content-Type: application/json" \  -d '{"query": "mutation ($i: PublishPostInput!) { publishPost(input: $i) { post { id url } } }",    "variables": {"i": {      "publicationId": "6702a8c1e4b0d2a9f3c41b7e",      "title": "How we roast Morning Light",      "contentMarkdown": "Eleven minutes from green bean to bag…",      "coverImage": "https://cdn.hashnode.com/res/hashnode/image/upload/…/roastery.jpeg",      "tags": [{"slug": "coffee"}, {"slug": "roasting"}],      "originalArticleURL": "https://northbeam.coffee/blog/morning-light"    }}}'

1/4 POST / createImageUploadURLSending

Published · now

How we roast Morning Light

Northbeam Coffee·Oct 8·1 min read

Eleven minutes from green bean to bag. We start low to dry the beans, push through first crack, then stop early to keep the honey and orange notes.

That early stop is why it tastes lighter than our other coffees, and why it works as well in a latte as in a pour-over.

coffeeroasting

The Hashnode API at a glanceWhat it takes before the first post.

Price: Comes with Hashnode Pro on the blog: $5 a month per seat, or $50 a year. Billed per blog
Endpoint: One GraphQL endpoint, https://gql-beta.hashnode.com/. gql.hashnode.com now answers with a redirect
Auth: A Personal Access Token from Settings → Developer, sent as Authorization: Bearer. It reaches every blog its owner has
Without Pro: FORBIDDEN: "Publication does not have an active Pro plan". Public queries like tag, user and feed still answer
Posting: publishPost with publicationId, title and contentMarkdown; coverImage, tags and originalArticleURL are optional
Images: createImageUploadURL, a PUT of the file, then confirmImageUpload. 8 MB, any image type but SVG
Rate limit: Targets of 20,000 queries and 500 mutations a minute, not enforced today. Request bodies stop at 100 KB
Scheduling: Not in the API: it's a Pro feature of the dashboard. publishedAt only backdates a post

Checked on October 8, 2026, from Hashnode's developer documentation and terms.

Our recommendation

To post to Hashnode from your product, use Breakreach's API.We built it, so here's the case.

See the request

The article on Hashnode and its LinkedIn and X posts in one request, scheduled for the same morning
Scheduling the API doesn't have: Breakreach holds the post and publishes it at the time from its servers
Your users paste their token on a hosted page and tick the Pro blogs Breakreach should post to

When to use Hashnode's API directly. Breakreach can't get around the paywall: it only connects blogs on Hashnode Pro, and only the ones the token's owner owns. It publishes posts without series, subtitles, SEO fields or co-authors, and can't edit them afterwards. For more than publishing, call the GraphQL API directly, or use Hashnode's own CLI or MCP server.

How to get access to the Hashnode APIFrom a developer account to your first real post.

1Put the blog on ProIn the blog's dashboard, open Billing and click Upgrade to Pro. Hashnode allow-lists the blog as soon as checkout goes through: no app to register and no review.
2Generate a tokenOn hashnode.com/settings/developer, generate a Personal Access Token. Send it in the Authorization header; the Bearer prefix is optional. Treat it like a password: it can publish, edit and delete.
3Find the blog's idme { publications(first: 50) } lists the blogs the token's owner owns, with id, title and url. Team blogs where they're only a member aren't in it: look those up with publication(host: …).
4Check for Pro firstNo field says whether a blog has Pro. Query publication(id) { id }: a FORBIDDEN answer that mentions the Pro plan means it doesn't, and retrying won't change that.

Hashnode documents Personal Access Tokens as the way to authenticate to the GraphQL API. Its CLI signs people in through the browser, and its MCP server runs its own OAuth, but both still need Pro to write.

How to post with the Hashnode APIThe requests in the demo above, one by one.

1Upload the imagescreateImageUploadURL with the contentType, a PUT of the raw bytes to presignedPut.url, then confirmImageUpload with the key. The confirm step enforces the 8 MB cap and returns the cdnUrl. presignedPost was deprecated on September 1, 2026.
2Publish the postpublishPost with publicationId, title and contentMarkdown, plus coverImage, tags as { slug, name } (unknown tags are created), originalArticleURL, subtitle, slug or seriesId. It returns the post's id and url, custom domain included.
3Or start with a draftcreateDraft still takes the older nested shape, coverImageOptions.coverImageURL for the cover, then publishDraft with its id. Contributors on a team blog can only draft and call submitDraftForReview.

PublishPostInput is flat now: the old coverImageOptions, settings and metaTags fields fail with 400 BAD_USER_INPUT. Resolver errors such as FORBIDDEN come back as HTTP 200 with errors[], so read the body whatever the status.

Common Hashnode API errorsWhat they mean and how to fix them.

Error	What it means	Fix
`UNAUTHENTICATED You must be logged in`	No token, or one that was deleted.	Generate a new token in Settings → Developer.
`FORBIDDEN Publication does not have an active Pro plan`	The blog isn't on Hashnode Pro.	Upgrade it in the blog's dashboard, under Billing. Retrying won't help.
`FORBIDDEN, without the Pro message`	Your role can't do it: a Contributor publishing, for instance.	createDraft, then submitDraftForReview.
`400 BAD_USER_INPUT Field "coverImageOptions" is not defined`	Code written for the old, nested PublishPostInput.	Pass coverImage directly.
`301 from gql.hashnode.com`	The retired endpoint, which redirects to Hashnode's announcement.	POST to https://gql-beta.hashnode.com/.
`400 BAD_REQUEST`	The body wasn't sent as JSON, which Hashnode's CSRF guard refuses.	Send Content-Type: application/json.

Hashnode API limitsRate limits, text and media.

Pro on the blogEvery request about a blog needs Pro on that blog, reads included. The check is per blog: one Pro blog doesn't open the API for the others on the same account.
Request sizeRequest bodies stop at 100 KB, so a long post with images inlined as base64 fails. Upload the images and link them instead.
Images and tagsImages up to 8 MB, image/* only and no SVG. Up to 15 tags per post, sent as slugs; tags that don't exist yet are created.
Rate limits and cachingHashnode publishes targets of 20,000 queries and 500 mutations a minute, and says the server doesn't enforce them today. Query answers may be cached for up to about 25 seconds, so a read right after a write can be stale.

Is the Hashnode API free?

Not anymore. Since May 13, 2026, Hashnode's API needs Hashnode Pro on the blog it reads or writes: $5 a month per seat, or $50 a year. Hashnode says scrapers and spammers were abusing the free API.

Pro is billed per blog and per seat, so a team blog's price follows its members, and Billing shows the total before checkout. The same plan adds custom domains, webhooks, GitHub backup and scheduled publishing in the dashboard.

Through Breakreach, a Hashnode blog counts like any other connected account: $5 a month each up to 20, $3 up to 100, then $2. The blog still needs Hashnode Pro, which you pay to Hashnode.

Ways to post to Hashnode from code

	What you set up	Price	Posts to Hashnode
Breakreach	An API key. Blogs connect with a Hashnode token, or your users connect theirs on a hosted page	$5 a month per account, less from 21	Yes, Blogs on Hashnode Pro
Hashnode's own API	A Personal Access Token, and Hashnode Pro on each blog	$5 a month per seat on each blog, with Hashnode Pro	Yes
Upload-Post	An API key	Free for 2 profiles and 10 uploads a month; Basic $24 a month for 5 profiles	Yes, On paid plans, text only
Zernio	An API key	First 2 accounts free, then $6 per account up to 10, $3 up to 100, $1 after	No
Ayrshare	An API key	From $149 a month for 1 profile, no free plan	No
Outstand	An API key	$19 a month for 3,000 posts, then per post	No

Checked on October 8, 2026, from Hashnode's developer documentation and each company's pricing page. Breakreach is our product.

What the Hashnode API can't do

Schedule a post: there's no scheduling mutation, only the dashboard's
Answer for a blog without Pro, reads included
List team blogs where you're only a member
Tell you whether a blog has Pro: you find out from a FORBIDDEN
Upload a video: the upload mutation takes images only

Post to Hashnode with Breakreach's APIOne request, scheduled, with retries.

POST /v1/posts

curl https://api.breakreach.com/v1/posts \  -H "Authorization: Bearer $BREAKREACH_API_KEY" \  -H "Content-Type: application/json" \  -d '{    "content": "How we roast Morning Light\nEleven minutes from green bean to bag. We start low to dry the beans, push through first crack, then stop early to keep the honey and orange notes.\n\nThat early stop is why it tastes lighter than our other coffees, and why it works as well in a latte as in a pour-over.",    "accountIds": ["6701a2f4c9e84b0012a3b4d6"],    "media": ["https://cdn.northbeam.coffee/roastery.jpg"],    "articleSettings": {"tags": ["coffee", "roasting"], "canonicalUrl": "https://northbeam.coffee/blog/morning-light"},    "scheduledAt": "2026-10-07T09:00:00"  }'

What it posts on Hashnode

ArticlesThe first line is the title. The rest goes to Hashnode as Markdown, so ## headings, lists, links and code blocks come out the way Hashnode renders them.
Cover and photosThe first photo is the cover, and up to 9 more follow the text. Breakreach copies them to Hashnode's CDN first, so the post doesn't depend on Breakreach's storage.
Tags, canonical URL, draftsarticleSettings.tags become Hashnode tags, 15 at most, created if new. canonicalUrl sets the original article's address, and asDraft leaves a draft in the blog's dashboard.
Scheduling and statsscheduledAt, the next free slot, or publishNow, with no dashboard scheduling needed. Views, reactions and comments per post come back, with the blog's followers.

Not yet

Blogs without Hashnode Pro
Team blogs you're only a member of
Series, subtitles, SEO fields and co-authors
Videos, and editing a post once it's published

The full reference, webhooks and the price per connected account are on the developers page, and the OpenAPI spec is at api.breakreach.com/v1/openapi.json.

FAQ

Questions, answered.

Short answers about the Hashnode API.

Not since May 13, 2026. Every request that reads or writes a blog needs Hashnode Pro on that blog, $5 a month per seat or $50 a year. A few public queries, such as tag and user, still answer without it.

https://gql-beta.hashnode.com/, one GraphQL endpoint you POST to. The old gql.hashnode.com answers every request with a 301 redirect to Hashnode's announcement, so code that still calls it stops working.

Generate a Personal Access Token at hashnode.com/settings/developer and send it in the Authorization header, with or without Bearer. It can publish, edit and delete on every blog you own, so keep it out of your code and logs.

Call publishPost with publicationId, title and contentMarkdown, plus coverImage, tags and originalArticleURL if you need them. Get the publicationId from me { publications }, and make sure the blog is on Pro.

No. There's no scheduling mutation: scheduled publishing is a Pro feature of the dashboard, and publishedAt only backdates a post. To schedule from code, hold the post and call publishPost at the time, which is what Breakreach does.

The blog you're reading or writing isn't on Pro. The check is per blog, not per account: upgrade that blog in its dashboard under Billing, and the API works for it as soon as checkout goes through.

$5 a month per connected account up to 20, $3 up to 100, then $2. Each Hashnode blog is one account, and it still needs Hashnode Pro. You pay per connected account, never per post or per request.