Micropub is an open API standard that is used to create posts on one's own domain using third-party clients. Web apps and native apps (e.g. iPhone, Android) can use Micropub to post short notes, photos, events or other posts to your own site.
The Micropub vocabulary is derived directly from the Microformats vocabulary. Micropub is meant to be a serialization of Microformats that can be submitted as an HTTP POST. The method for developing new Micropub vocabularies is to look at the Microformats representation and work backwards.
Similar to how microformats has a relatively small ruleset for parsing HTML documents into a data structure, Micropub defines a small set of rules to interpret HTTP POST and GET requests as Micropub commands. Where Microformats does not require changing the parsing rules to introduce new properties of an object such as an h-entry, Micropub similarly does not require changing parsing rules to interpret requests that may correspond to different post types, such as posting videos vs "likes".
The Micropub syntax describes how to interpret HTTP POST and GET requests into a useful action the server can take.
The full specification can be read at http://micropub.net/draft/
All Micropub requests to create posts are sent as form-encoded, multipart form-data , or JSON encoded HTTP requests. Responses typically do not include a response body, indicating the needed information (such as the URL of the created post) in HTTP headers. When a response body is required, it is returned as either form-encoded or JSON, depending on the HTTP Accept header.
How to implement
How to implement the Micropub API, both in a client that can discover an endpoint and publish to it, and on a server to support an endpoint to create/update/delete posts in response.
It should be possible to configure an API client by authenticating as your domain name using IndieAuth. After signing in, your domain needs a way to specify the API endpoint the client will use to create new posts.
Add a <link> tag in the HTML head of your home page, or send an HTTP Link header.
Link: <https://example.com/micropub>; rel="micropub"
<link rel="micropub" href="https://example.com/micropub">
Micropub requests are authenticated by including a Bearer Token in either the HTTP header or a form-encoded body parameter as described in the OAuth Bearer Token RFC.
Authorization should be handled via the IndieAuth protocol, built on top of OAuth 2.0. See obtaining-an-access-token for more details. An app that wants to post to a user's Micropub endpoint will need to obtain authorization from the user in order to get an access token.
Authorization: Bearer XXXXXXXX
Form-Encoded Body Parameter
The client may request one or more scopes during the authorization request. It does this according to standard OAuth 2.0 techniques, by passing a space-separated list of scope names in the authorization request.
The authorization server must indicate to the user any scopes that are part of the request, whether or not the authorization server recognizes the scopes. The authorization server may also allow the user to add or remove scopes that the client requests.
For example, most Micropub servers require clients to obtain the "post" scope in order to create posts. However, some servers may require more granular scope requests, such as "delete" or "post:video". See scope for more details and a list of all currently used values for scope.
(This section is a stub)
When a Micropub client obtains an access token, it may need to be able to verify the access token is valid and retrieve the URL of the user it belongs to. Micropub endpoints must implement a method that returns basic information about the access token.
Access tokens can be verified by making an empty GET request to the Micropub endpoint with the access token in the header. If the access token is valid, the Micropub endpoint must reply with at least the "me" parameter, and may also return scope, client_id, and expiration date.
Note: This may not be appropriate for the micropub endpoint and may be better handled by the token endpoint.
Form-encoded Microformats Representation
For the simplicity of writing clients and servers, all Micropub endpoints must handle the standard form-encoded format. At a most basic level, you should be able to write an HTML form and set the form action to your own endpoint and use it to post to your site.
Examples of Creating Objects
Indicating the object being created
To indicate the object being created, use a property called "h", (which would never be the name of a property of a microformats object), followed by the name of the microformats object. Examples:
The following properties may be included in a request to create a new h-entry:
- category = tag1, tag2, tag3 (sent as array syntax:
- as a Geo URI, for example
- as a URL that contains an h-card
- My micropub client currently has a map to mark the specific location in LatLng values, and a text input for an actual place name. So my client is sending a request of the form "&location=1.23,%40-4.56:An%40Address" Jonnybarnes.net 07:57, 10 June 2014 (PDT)
- as a Geo URI, for example
- Pass one or more URLs pointing to places where this entry already exists. Can be used for PESOS implementations.
- mp-syndicate-to = https://myfavoritesocialnetwork.example/aaronpk, https://archive.org/, etc.
- This property is slightly different from the others since it is giving a command to the server rather than describing an object, which is why it is prefixed with "mp-".
Posting a new note with tags, syndicating to myfavoritesocialnetwork:
- published (optional, defaults to "now" if not present. Useful for writing offline and syncing later)
POST /micropub HTTP/1.1 Host: aaronparecki.com Content-type: application/x-www-form-urlencoded h=entry &content=The+%40Jawbone+UP%2C+my+favorite+of+the+%23quantifiedself+trackers%2C+finally+released+their+official+API%21+http%3A%2F%2Fjawbone.com%2Fup%2Fdeveloper%2F &category=jawbone&category=quantifiedself&category=api &mp-syndicate-to=https://myfavoritesocialnetwork.example/aaronpk
POST /micropub HTTP/1.1 Host: example.com Content-type: application/x-www-form-urlencoded Authorization: Bearer XXXXXXX h=entry &content=Hello+World
curl https://example.com/micropub -d h=entry -d "content=Hello World" -H "Authorization: Bearer XXXXXXX"
Posting a new reply, syndicating to myfavoritesocialnetwork
POST /post/new HTTP/1.1 Host: aaronparecki.com Content-type: application/x-www-form-urlencoded h=entry &content=%40BarnabyWalters+My+favorite+for+that+use+case+is+Redis.+It%27s+easy+to+set+up+and+use%2C+I+often+use+it+to+move+data+between+apps+written+in+different+languages+too. &in-reply-to=http://waterpigs.co.uk/notes/4S0LMw/ &mp-syndicate-to=https://myfavoritesocialnetwork.example/aaronpk
Posting a new repost, and adding additional tags.
POST /micropub HTTP/1.1 Host: aaronparecki.com Content-type: application/x-www-form-urlencoded h=entry &repost-of=http://waterpigs.co.uk/notes/4S0LMw/ &category=realtime
Posting a new article
Posting a new bookmark with name, quote, and tags.
POST /micropub HTTP/1.1 Host: aaronparecki.com Content-type: application/x-www-form-urlencoded h=entry &bookmark-of=https%3A%2F%2Fplus.google.com%2F%2BKartikPrabhu%2Fposts%2FUzKErSbfmHq &name=To+everyone+who+is+complaining+about+Popular+Science+shutting+down+comments... &content=%22Why+is+there+this+expectation+that+every+website+should+be+a+forum%3F+No+website+has+any+obligation+to+provide+a+space+for+your+rants.+Use+your+own+space+on+the+web+to+do+that.%22 &category=indieweb&category=comments
When a Micropub request includes a file, the entire request is sent in the
multipart/form-data encoding, and the file is named by content type, either "audio", "video" or "photo". A request may include one or more of these files.
When OwnYourGram makes a Micropub request to post a video, it also sends a photo which is a thumbnail preview of the video.
In PHP, these files are accessible using the
$_FILES['video'] $_FILES['photo'] $_FILES['audio']
Note that there is no practical way to upload a file when the request body is JSON encoded.
The following properties may be included in a request to create a new h-event:
Posting a new event
POST /micropub HTTP/1.1 Host: aaronparecki.com Content-type: application/x-www-form-urlencoded h=event &name=IndieWeb Dinner at 21st Amendment &description=In SF Monday evening? Join @caseorganic and I for an #indieweb dinner at 6pm! (Sorry for the short notice!) &start=2013-09-30T18:00:00-07:00 &category=indieweb &location=http://21st-amendment.com/
The following properties may be included in a request to create a new h-cite:
(The following list is from microformats.org/wiki/h-cite)
- published - date of publication of the work (not the date the h-cite was created)
- author - URL of an h-card
- url - a URL to access the cited work
- content - the content or partial content of the work itself, such as when including a blockquote snippet of a work
Nested Microformat Objects
Whenever possible, nested Microformats objects should be avoided. A better alternative is to reference objects by their URLs. The most common example is including an h-card for a venue, such as checking in to a location or tagging a photo with a person or location. In these cases, it is better to reference the object by URL, creating it first if necessary.
For simple values such as an h-geo property with latitude and longitude, just use a Geo URI such as
This technique has the advantage of ensuring that each object that is created has its own URL (each piece of data has its own link). This also gives the server an opportunity to handle each entity separately. E.g., rather than creating a duplicate of an existing venue, it may give back a link to one that was already created, possibly even merging in newly received data first.
For more complicated objects, it is better to first create an object on the target site so that it has its own URL, then reference that object's URL in the main request.
For example, creating a checkin post would involve two POST requests:
First create the venue by posting an h-card:
POST /micropub h=card &name=Ford+Food+and+Drink &url=http://www.fordfoodanddrink.com/ &street-address=2505 SE 11th Ave &locality=Portland ®ion=OR &postal-code=97214 &geo=geo:45.5048473,-122.6549551 &tel=(503) 236-3023
HTTP/1.1 201 Created Location: http://example.com/venue/10
Then create the checkin post:
POST /micropub h=entry &location=http://example.com/venue/10 &name=Working on Micropub &category=indieweb
HTTP/1.1 201 Created Location: http://example.com/entry/1001
- This technique has the advantage of ensuring that each object that is created has its own URL (each piece of data has its own link)
- Also gives the server an opportunity to handle each entity separately. E.g., rather than creating a duplicate of an existing venue, it may give back a link to one that was already created, possibly even merging in newly received data first.
In some cases, it does not make sense for the nested object to have a URL. For example, when posting an h-measure value, there is no reason for the h-measure itself to have a URL, so this is an acceptable case to use the nested microformats object syntax.
For example, creating a new "weight" measurement post as an h-entry with h-measure objects:
h=entry &weight[type]=h-measure &weight[properties][num]=155.73 &weight[properties][unit]=lb &bodyfat[type]=h-measure &bodyfat[properties][num]=19.83 &bodyfat[properties][unit]=%
Examples of IndieWeb sites that support the micropub API (in order of deployment).
Aaron Parecki supports publishing various post types on aaronparecki.com using micropub since 2013-12-25.
- 2013-12-25 note micropub publishing support added
- 2013-12-28 pushup micropub publishing support added
- 2014-02-24 photo micropub publishing support added
- 2014-09-17 bookmark micropub publishing support added
- 2014-11-07 repost micropub publishing support added
- 2014-12-22 like micropub publishing support added
Ben Roberts posts to his Postly site via micropub. Photos are posted using OwnYourGram and Notes, Replies, and Articles are posted using his own Postly Client. Deleting entries via micropub added 2014-09-28.
bear supports micropub since 2015-01-01.
- Supports any post types by passing all metadata in the 'content' param as and inferring post types from it (so all a client needs is a content field).
- Supports edit over POST via resending content (+ metadata) and the slug of the post to be edited.
Jeena Paradies supports micropub for notes (with syndication and reply-to) only since 2015-07-12. Posting photos works too since 2015-07-24. And now even person tagging for notes and photos since 2015-07-30.
- Supports any post types by and inferring post types.
Micropub has been added to the following CMS software and blog publishing tools for additional server support.
Ben has written a Known plugin that logs in via IndieAuth and publishes content via micropub. It's designed to work so that all indieweb post types - notes etc - are passed to the content plugin registered to handle them. 
Shane has written a Craft plugin for Micropub. It currently only works with notes and requires some configuration to setup. It has also only been tested with Quill so far, as of 2015-07-11. https://github.com/ShaneHudson/Micropub_Craft
Pelle Wessman has written a self-hosteable service that exposes a Micropub endpoint and then performs the instructions sent to that endpoint by committing Jekyll formatted data to a GitHub repository for the Jekyll site. Modular built and would be possible to extend to support other systems like Jekyll as well. https://github.com/voxpelli/webpage-micropub-to-github
Ryan Barrett's ownyourresponses is PESOS as a service for Twitter favorites, retweets, and replies and Instagram likes. It polls your accounts periodically for new activity via the APIs and creates corresponding like, repost, and reply posts on your site via Micropub.
The original motivation is described in PESOS for Bridgy Publish.
Sites and client applications that publish via micropub. Alphabetically sorted.
The iOS text editor Editorial can publish its documents to Micropub through a couple of third party Workflows created by Pelle Wessman. Two for authorizing and deauthorizing with an IndieAuth endpoint and one for the Micropub publishing. Shown in action in this video.
Micropublish is Barry Frost's simple Micropub client. Supports Note, Article, Bookmark, Reply, Repost and Like post types. Barry uses this to post all content on his site. Ruby source code is available on GitHub.
In September 2015, Kyle Mahan created micropub-xmpp-bot, an experimental XMPP chat bot for posting notes, replies, likes, and reposts via micropub. Notably, it uses an out-of-band redirect_uri handler that prompts the user to copy/paste their auth code. Give it a shot by XMPP chatting with email@example.com. (If it's offline, ping "kylewm" on IRC).
open source: https://github.com/kylewm/micropub-xmpp-bot/
- The signup process contains lots of useful documentation and debugging information to help get new micropub implementations working.
Ben Roberts' Postly creates notes and articles via micropub and can add syndication links after posting. synditate-to links are passed as a php readable array field not a comma separated list. Postly can also edit posts when passing mp-action=edit Publicly Available UI
- The signup process walks you through configuring your website to accept Micropub requests from apps like this.
Barnaby's Taproot publishes notes via micropub. The post UI is publicly accessible, and you can use it to make posts on your own website. As of 2014-06-12 it’s also marked up with h-product and h-x-app markup so that authorization UIs can provide a better experience whilst authorizing, without having to pre-register apps and upload logos
Teacup is a Micropub client for posting various types of food posts.
Woodwind has optional support for posting replies and likes via Micropub. Includes toggles for syndicate-to endpoints as of 2015-02-10.
Open source libraries & implementations used to support micropub on the client app side and on the API endpoint side on the server:
- p3k-micropub PHP library used in p3k
- taproot/authentication PHP library used in Taproot, implements both client app and resource provider authentication
- wordpress-micropub: WordPress plugin for server endpoint
- flask-micropub: Flask (Python) plugin that makes it easy to add IndieAuth authentication and Micropub authorization to a client application.
- micropub-express Node.js library created and used by Pelle Wessman for voxpelli.com's micropub endpoint
Please use the Github repo for issues and discussion related to the spec.
For issues that have been discussed and are ready to consider for inclusion in the spec, use the Micropub-brainstorming page to collect examples and iterate on the ideas.