API guide

The Tumblr API in 2026.Free, with one budget for your whole app.

To post to Tumblr from code, register an app at tumblr.com/oauth/apps, send people through OAuth 2 with the write scope, then call POST /v2/blog/{blog}/posts with the post in NPF, Tumblr's JSON block format. Photos and video go up in the same request, as multipart. It's free, but access tokens last 42 minutes, and every user of your app shares 1,000 calls an hour and 5,000 a day.

Checked October 8, 2026. Breakreach is our product.

# 1. Refresh the token: it lasts 42 minutes, and the refresh token changescurl -X POST https://api.tumblr.com/v2/oauth2/token \  -A "Northbeam/1.0" \  -d grant_type=refresh_token -d refresh_token=$REFRESH_TOKEN \  -d client_id=$CONSUMER_KEY -d client_secret=$SECRET_KEY # 2. Post in NPF: a json part first, then each photo under its identifiercurl -X POST https://api.tumblr.com/v2/blog/northbeam-coffee/posts \  -H "Authorization: Bearer $TOKEN" \  -A "Northbeam/1.0" \  -F 'json={"content": [      {"type": "image", "media": [{"type": "image/jpeg", "identifier": "roastery"}]},      {"type": "image", "media": [{"type": "image/jpeg", "identifier": "pourover"}]},      {"type": "image", "media": [{"type": "image/jpeg", "identifier": "latte"}]},      {"type": "text", "text": "Morning Light is out tomorrow. Honey, orange and cocoa…"}    ], "tags": "coffee,morning light,roastery"};type=application/json' \  -F "roastery=@roastery.jpg;type=image/jpeg" \  -F "pourover=@pourover.jpg;type=image/jpeg" \  -F "latte=@latte.jpg;type=image/jpeg"

1/2 POST /v2/oauth2/tokenSending

Published · now

northbeam-coffee

Morning Light is out tomorrow. Honey, orange and cocoa, our lightest roast yet.

Eleven minutes from green bean to bag, then brewed here as a pour-over and as a latte.

#coffee #morning light #roastery

0 notes

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

Price: No fee. You register an app at tumblr.com/oauth/apps; the docs describe no review
Auth: OAuth 2 with the scopes basic, write and offline_access. OAuth 1.0a still works, and /v2/oauth2/exchange swaps its tokens
Tokens: Access tokens last 42 minutes. Each refresh returns a new refresh token, which lasts 42 days according to Tumblr staff
Posting: POST /v2/blog/{blog}/posts with content as NPF blocks, state and tags; 201 with the post id as a string
Media: Uploaded in the same request as multipart: a json part, then one part per identifier. Up to 30 images and 1 uploaded video per post
Blogs: GET /v2/user/info lists every blog the user can post to: main, side and group blogs, each with a uuid
Rate limit: 1,000 calls an hour and 5,000 a day per app, all users together; 250 posts, 250 images and 20 videos a day per user
Scheduling: state queue with publish_on, a future ISO 8601 time. The post gets a new id when it goes live

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

Our recommendation

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

See the request

No app to register and no OAuth to build: people allow Breakreach on Tumblr, and a login with several blogs gets a picker
The 42-minute tokens are handled: the blogs of one login refresh together, and idle logins are renewed before their 42 days run out
Markdown in, NPF out: headings, lists, bold and links become Tumblr's own blocks, and the same request posts to your other networks

When to use Tumblr's API directly. Breakreach creates original posts only, with no reblogs, polls, asks or audio and no Tumblr queue, and it reads back likes, reblogs and followers, nothing else. For a Tumblr client or a bot that does more, call Tumblr's API directly: it's free, and its docs are on GitHub.

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

1Register an appSigned in to Tumblr, register one at tumblr.com/oauth/apps. You get an OAuth consumer key, which is also your api_key for public calls, and a secret key. Set the app's OAuth2 redirect URL: OAuth 2 stays off until you do.
2Send the person to authorizeGET www.tumblr.com/oauth2/authorize with client_id, response_type=code, scope (basic write offline_access) and state. redirect_uri is required when the app has several. The docs don't mention PKCE, so keep the secret on your server.
3Swap the code for tokensPOST api.tumblr.com/v2/oauth2/token with grant_type=authorization_code, the code, client_id and client_secret. The access token lasts 2,520 seconds, and a refresh token only comes with offline_access.
4Refresh, and keep the new refresh tokengrant_type=refresh_token returns a new access token and a new refresh token. Save both, run one refresh per login at a time, and refresh idle accounts before 42 days.

The docs describe no review: any Tumblr user can authorize a registered app. What holds you back is the app's own budget, and the API agreement gives api@tumblr.com as the contact. Send the same User-Agent on every request: Tumblr can suspend apps whose User-Agent changes.

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

1List the blogsGET /v2/user/info returns the user's blogs with name, url, title, primary, followers and type. Store each blog's uuid (t:…): it survives a rename and works anywhere a blog name does.
2Build the post in NPFcontent is an array of blocks: text (with subtypes such as heading1, heading2, quote and ordered-list-item), image, video, link and audio. Bold, italic and links are formatting ranges, counted in Unicode code points, not UTF-16.
3Send it with the filesPOST /v2/blog/{blog}/posts as multipart/form-data: a json part with the body first, then each file under the identifier its block names. A video block's media is one object, not an array. Tumblr answers 201 with the id.

Tags go as one comma-separated string, without #. Media URLs are only documented for files already on Tumblr, so upload the bytes. A large upload can answer 504 after the post was created: look for the post before you retry.

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

Error	What it means	Fix
`401, code 1013, Unable to authorize`	The access token expired after 42 minutes, or the person removed your app.	Refresh it; if the refresh is refused, send them through OAuth again.
`400 invalid_client (token endpoint)`	The client_id or client_secret is wrong.	Use the app's consumer key and secret key.
`400, code 8001`	The NPF body doesn't validate: a block or a formatting range is malformed.	Check it against the NPF spec; a video's media is one object.
`403, code 8023`	The user's 250 posts for the day are used up.	Wait for Tumblr's next calendar day.
`403, code 8010`	A previous video is still transcoding.	Send one video at a time per user, and retry later.
`429 Limit Exceeded`	Your app's hourly or daily calls, or a per-IP limit.	Back off until the reset in the X-Ratelimit headers, when Tumblr sends them.

Tumblr API limitsRate limits, text and media.

Per app1,000 calls an hour and 5,000 a day per consumer key, every user of your app together. Cache /user/info and read notes sparingly.
Per user, per day250 published posts (reblogs included), 250 images, 20 videos and 60 minutes of video, by calendar day on Tumblr's clock. GET /v2/user/limits shows what's left.
Per post30 image blocks, 10 video blocks of which 1 uploaded, 4,096 code points per text block and 1 MB of JSON. The help center allows 500 MB and 10 minutes per video.
QueueA blog holds 1,000 queued posts and the queue publishes up to 50 a day. A queued, scheduled or draft post gets a new id once it's published.

Is the Tumblr API free?

Yes. There's no paid tier: you register an app and call the API with its consumer key. The docs describe no fee and no review.

What it asks for is restraint. The app shares 1,000 calls an hour across all its users, and the API agreement wants each post to come from an explicit action of the person, who sees where it goes, no floods of near-identical posts, and a line saying the app is built with Tumblr, "Powered by Tumblr" style.

Through Breakreach, each Tumblr blog counts like any other connected account: $5 a month each up to 20, $3 up to 100, then $2.

Ways to post to Tumblr from code

	What you set up	Price	Posts to Tumblr
Breakreach	An API key. Blogs connect through Breakreach's Tumblr app, or your users connect theirs on a hosted page	$5 a month per account, less from 21	Yes, Main, side and group blogs
Tumblr's own API	An app registered at tumblr.com/oauth/apps, OAuth 2 per user, and a token refresh every 42 minutes	Free	Yes
Upload-Post	An API key	Free for 2 profiles and 10 uploads a month; Basic $24 a month for 5 profiles	No
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 Tumblr's developer documentation and each company's pricing page. Breakreach is our product.

What the Tumblr API can't do

Report views or reach: only notes, likes and reblogs
Take a photo or video from your own URL: upload the file
Hold more than one uploaded video in a post
Keep a post's id from the queue to publication
Upload audio for now: it fails with code 8005, an open issue in October 2026

Post to Tumblr 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": "Morning Light is out tomorrow. Honey, orange and cocoa, our lightest roast yet.\n\nEleven minutes from green bean to bag, then brewed here as a pour-over and as a latte.",    "accountIds": ["6701a2f4c9e84b0012a3b4d7"],    "media": ["https://cdn.northbeam.coffee/roastery.jpg", "https://cdn.northbeam.coffee/pourover.jpg", "https://cdn.northbeam.coffee/latte.jpg"],    "articleSettings": {"tags": ["coffee", "morning light", "roastery"]},    "scheduledAt": "2026-10-07T09:00:00"  }'

What it posts on Tumblr

Photos or a videoUp to 30 photos, or one video, uploaded to Tumblr above the text. A post with both gets the video alone.
Formatted text# and ## lines become headings, - and 1. lines lists, > lines quotes, with bold, *italic* and links kept as Tumblr formatting. The first line isn't made a title.
Tags, drafts and schedulingarticleSettings.tags become Tumblr tags and asDraft leaves the post in the blog's drafts. Breakreach publishes at the time itself, so the post's id never changes.
Every blog, and statsMain, side and group blogs, each its own account. Likes and reblogs per post from its notes, and followers per blog.

Not yet

Reblogs, polls and asks
Audio posts and link cards
Tumblr's queue and private posts
Editing or deleting after publishing

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 Tumblr API.

Yes. Register an app at tumblr.com/oauth/apps and you get a consumer key and a secret key, with no fee and no review step in the docs. The limit is your app's budget: 1,000 calls an hour and 5,000 a day, all users together.

With OAuth 2: send the person to www.tumblr.com/oauth2/authorize with the scope basic write offline_access, then POST the code to api.tumblr.com/v2/oauth2/token. The token lasts 42 minutes; refresh it with the refresh token, which changes each time.

POST /v2/blog/{blog}/posts with content as NPF blocks, a text block and image blocks for example, plus state and tags. To upload files, send multipart/form-data: a json part first, then one part per media identifier.

Yes: state queue with publish_on set to a future ISO 8601 time. The post waits in the blog's queue, which holds 1,000 posts, and gets a new id when it's published, so the first id won't find it.

30 image blocks per post, plus one uploaded video. Per user and per day, Tumblr allows 250 image uploads and 20 videos.

Per app: 1,000 calls an hour and 5,000 a day. Per user and per day: 250 posts, 250 images, 20 videos and 60 minutes of video. Per IP: 300 calls a minute. Going over answers 429 Limit Exceeded.

$5 a month per connected account up to 20, $3 up to 100, then $2. Each Tumblr blog is one account. You pay per connected account, never per post or per request.