2.1 Overview

All Micropub requests to create posts are sent as x-www-form-urlencoded, multipart form-data [HTML5], 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 [RFC7231] header.

2.2 Reserved Properties

A few POST body property names are reserved when requests are sent as x-www-form-urlencoded or multipart form data.

• access_token - the OAuth Bearer token authenticating the request (the access token may be sent in an HTTP Authorization header or this form parameter)
• h - used to specify the object type being created
• q - used to query a Micropub endpoint
• url - indicates the URL of the object being changed
• mp-action - indicates whether this is an update, delete, or undelete
• replace - for updates, the top-level property containing properties to replace
• add - for updates, the top-level property containing properties to add
• delete - for updates, the top-level property containing properties to remove
• mp-* - reserved for future use

When creating posts, all other properties in the request are considered properties of the object being created.

2.3 Create

To create a post, send an HTTP POST request to the Micropub endpoint indicating the type of post you are creating, as well as specifying the properties of the post.

h={microformats object type}

e.g. h=entry

All parameters not beginning with "mp-" are properties of the object being created.

e.g. content=hello+world

To specify multiple values for a property, such as multiple categories of an h-entry, use array bracket notation for the property name.

e.g. category[]=foo&category[]=bar

Properties that accept multiple values MUST also accept a single value as a string. A complete example of a form-encoded request follows.

h=entry&content=hello+world&category[]=foo&category[]=bar

multipart/form-data; boundary=553d9cee2030456a81931fb708ece92c

--553d9cee2030456a81931fb708ece92c
Content-Disposition: form-data; name="h"

entry
--553d9cee2030456a81931fb708ece92c
Content-Disposition: form-data; name="content"

Hello World!
--553d9cee2030456a81931fb708ece92c
Content-Disposition: form-data; name="photo"; filename="aaronpk.png"
Content-Type: image/png
Content-Transfer-Encoding: binary

... (binary data) ...
--553d9cee2030456a81931fb708ece92c--

{
  "type": ["h-entry"],
  "properties": {
    "content": ["hello world"],
    "category": ["foo","bar"]
  }
}

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]=%

{
  "type": ["h-entry"],
  "properties": {
    "weight": [
      {
        "type": "h-measure",
        "properties": {
          "num": ["155.73"],
          "unit": ["lb"]
        }
      }
    ],
    "bodyfat": [
      {
        "type": "h-measure",
        "properties": {
          "num": ["19.83"],
          "unit": ["%"]
        }
      }
    ]
  }
}

Link: <http://aaron.pk/xxxxx>; rel="shortlink"

Link: <https://https://myfavoritesocialnetwork.example/aaronpk/xxxxxx>; rel="syndication"

2.4 Update

Updating entries can be done with either a JSON post or form-encoded post. The syntax of the update request is the same in both cases, using the array bracket notation when encoding in form-encoded format.

To update an entry, send mp-action=update and specify the URL of the entry that is being updated using the "url" property. The request MUST also include either a replace, add or delete property containing the updates to make.

mp-action=update
&url=http://example.com/post/1
&replace[properties][content]=hello+moon

{
  "mp-action": "update",
  "url": "http://example.com/post/1",
  "replace": {
    "properties": {
      "content": ["hello moon"]
    }
  }
}

mp-action=update
&url=http://aaronpk.example/notes/2014/06/01/2/indieweb
&add[properties][syndication][]=https://archive.org/example

{
  "mp-action": "update",
  "url": "http://aaronparecki.com/notes/2014/06/01/2/indieweb",
  "add": {
    "properties": {
      "syndication": ["https://archive.org/"]
    }
  }
}

mp-action=update
&url=http://aaronpk.example/notes/2014/06/01/2/indieweb
&add[properties][category][]=webmention
&add[properties][category][]=indieweb

{
  "mp-action": "update",
  "url": "http://aaronpk.example/notes/2014/06/01/2/indieweb",
  "add": {
    "properties": {
      "category": ["webmention","indieweb"]
    }
  }
}

mp-action=update
&url=http://example.com/post/1
&delete[properties]=category

{
  "mp-action": "update",
  "url": "http://example.com/post/1",
  "delete": {
    "properties": ["category"]
  }
}

mp-action=update
&url=http://example.com/post/1
&delete[properties][category]=indieweb

{
  "mp-action": "update",
  "url": "http://example.com/post/1",
  "delete": {
    "properties": {
      "category": ["indieweb"]
    }
  }
}

2.5 Delete

To delete an entire entry at a URL, send a POST request containing mp-action=delete and the URL of the item in the url property.

mp-action=delete
&url=http://example.com/post/1

{
  "mp-action": "delete",
  "url": "http://example.com/post/1"
}

Some Micropub endpoints may support undeleting posts. To undelete a post, use "undelete" as the action.

mp-action=undelete
&url=http://example.com/post/1

{
  "mp-action": "undelete",
  "url": "http://example.com/post/1"
}

2.6 Querying

Micropub clients may need to query the Micropub endpoint to discover its capabilities, such as finding a list of syndication targets that it displays to the user, or retrieving the source of a post to display in the updating interface.

To query, make a GET request to the micropub endpoint and use the q parameter to specify what you are querying.

Note: The Micropub endpoint may include a query string such as ?micropub=endpoint, so in this case, Micropub clients MUST append the q parameter instead of replacing the query string.

GET /micropub?q=syndicate-to

GET /micropub?q=syndicate-to
Authorization: Bearer xxxxxxxxx

syndicate-to[]=https://archive.org/
&syndicate-to[]=https://wikimedia.org/
&syndicate-to[]=https://myfavoritesocialnetwork.example/aaronpk

GET /micropub?q=syndicate-to
Authorization: Bearer xxxxxxxxx
Accept: application/json

{
  "syndicate-to": [
    "https://archive.org/",
    "https://wikimedia.org/",
    "https://myfavoritesocialnetwork.example/aaronpk"
  ]
}

3.1 Endpoint Discovery

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.

HTTP Link Header

Link: <https://example.com/micropub>; rel="micropub"

HTML Link Tag

<link rel="micropub" href="https://example.com/micropub">

3.2 Authentication and Authorization

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 SHOULD be handled via the OAuth 2.0 [RFC6749] protocol, including the [IndieAuth] extension which supports endpoint discovery. See Obtaining an Access Token for more details.

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. [RFC6750]

HTTP Header

Authorization: Bearer XXXXXXXXX

Form-Encoded Body Parameter

access_token=XXXXXXXXX

3.3 Scope

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. [RFC6749]

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.