Micropub

3.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 necessary, it SHOULD be returned as a [JSON] encoded object.

3.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.

Note: The server MUST NOT store the access_token property in the post.

3.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. If no type is specified, the default type [h-entry] SHOULD be used. Clients and servers MUST support creating posts using the x-www-form-urlencoded encoding, and MAY also support creating posts using the JSON syntax.

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=53d9cee2030456a81931fb708ece92c

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

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

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

... (binary data) ...
--53d9cee2030456a81931fb708ece92c--

h=entry&content=hello+world&photo=https://photos.example.com/592829482876343254.jpg

{
  "type": ["h-entry"],
  "properties": {
    "content": ["hello world"],
    "category": ["foo","bar"],
    "photo": ["https://photos.example.com/592829482876343254.jpg"]
  }
}

h=entry
&summary=Weighed+155.73+pounds
&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": {
    "summary": [
      "Weight 155.73 pounds"
    ],
    "weight": [
      {
        "type": ["h-measure"],
        "properties": {
          "num": ["155.73"],
          "unit": ["lb"]
        }
      }
    ],
    "bodyfat": [
      {
        "type": ["h-measure"],
        "properties": {
          "num": ["19.83"],
          "unit": ["%"]
        }
      }
    ]
  }
}

Link: <http:

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

3.4 Update

Micropub servers SHOULD support updating posts, including adding and removing individual properties as described in this section.

Updating entries is done with a JSON post describing the changes to make.

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.

The values of each property inside the replace, add or delete keys MUST be an array, even if there is only a single value.

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

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

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

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

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

3.5 Delete

Micropub servers SHOULD support deleting posts, and MAY support undeleting posts.

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"
}

To undelete a post, use "undelete" as the action.

mp-action=undelete
&url=http:

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

3.7 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=config
Authorization: Bearer xxxxxxxxx

{
  "media-endpoint": "https://media.example.com/micropub",
  "syndicate-to": [
    {
      "uid": "https://myfavoritesocialnetwork.example/aaronpk",
      "name": "aaronpk on myfavoritesocialnetwork"
      "service": {
        "name": "My Favorite Social Network",
        "url": "https://myfavoritesocialnetwork.example/",
        "photo": "https://myfavoritesocialnetwork.example/img/icon.png"
      },
      "user": {
        "name": "aaronpk",
        "url": "https://myfavoritesocialnetwork.example/aaronpk",
        "photo": "https://myfavoritesocialnetwork.example/aaronpk/photo.jpg"
      }
    }
  ]
}

GET /micropub?q=source&properties[]=published&properties[]=category&url=http://aaronpk.example/post/1000
Authorization: Bearer xxxxxxxxx

{
  "properties": {
    "published": ["2016-02-21T12:50:53-08:00"],
    "category": [
      "foo", 
      "bar"
    ]
  }
}

GET /micropub?q=source&url=http://aaronpk.example/post/1000
Authorization: Bearer xxxxxxxxx

{
  "type": "h-entry",
  "properties": {
    "published": ["2016-02-21T12:50:53-08:00"],
    "content": ["Hello World"],
    "category": [
      "foo", 
      "bar"
    ]
  }
}

GET /micropub?q=source&properties=content&url=http://aaronpk.example/post/1000
Authorization: Bearer xxxxxxxxx

{
  "properties": {
    "content": [
      {
        "html": "<b>Hello</b> <i>World</i>"
      }
    ]
  }
}

GET /micropub?q=syndicate-to

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

HTTP/1.1 200 OK
Content-type: application/json

{
  "syndicate-to": [
    {
      "uid": "https://archive.org/",
      "name": "archive.org"
    },
    {
      "uid": "https://wikimedia.org/",
      "name": "WikiMedia"
    },
    {
      "uid": "https://myfavoritesocialnetwork.example/aaronpk",
      "name": "aaronpk on myfavoritesocialnetwork"
      "service": {
        "name": "My Favorite Social Network",
        "url": "https://myfavoritesocialnetwork.example/",
        "photo": "https://myfavoritesocialnetwork.example/img/icon.png"
      },
      "user": {
        "name": "aaronpk",
        "url": "https://myfavoritesocialnetwork.example/aaronpk",
        "photo": "https://myfavoritesocialnetwork.example/aaronpk/photo.jpg"
      }
    }
  ]
}

At a minimum, a syndication destination MUST have uid and name properties. The uid property is opaque to the client, and is the value the client sends in the Micropub request to indicate the targets to syndicate to. The name property is the value the client can display to the user. The name should be unambiguously descriptive of the destination, so that if for example there are two destinations on the same service, the name can disambiguate them.

The Micropub server MAY also include additional information about the destination service and user account. This is accomplished with the additional properties service and user, both of which can have three properties, name (a human-readable name), url and photo (both URLs).

The client may use the service and user properties to enhance the display of the syndication options, for example by including the user or service photos on the syndication buttons.

3.8 Error Response

If there was an error with the request, the endpoint MUST return an appropriate HTTP status code, typically 400, 401, or 403, and MAY include a description of the error. If an error body is returned, the response body MUST be encoded as a [JSON] object and include at least a single property named error with the value set to one of the below:

• HTTP 403: forbidden - The authenticated user does not have permission to perform this request
• HTTP 401: insufficient_scope - The scope of this token does not meet the requirements for this request. The client may wish to re-authorize the user to obtain the necessary scope. The response MAY include the "scope" attribute with the scope necessary to successfully perform this request.
• HTTP 400: invalid_request - The request is missing a required parameter, or there was a problem with a value of one of the parameters
• HTTP 400: not_found - The post with the requested URL was not found

The response body MAY also contain an error_description property with a human-readable description of the error message, used to assist the client developer in understanding the error. This is not meant to be shown to the end user.

See the OAuth 2 Bearer Token [RFC6750] spec for more details on the how to return error responses.

GET /micropub?q=source&url=http://aaronpk.example/post/404
Authorization: Bearer xxxxxxxx

HTTP/1.1 400 Bad Request
Content-type: application/json

{
  "error": "not_found",
  "error_description": "The post with the requested URL was not found"
}

5.1 Authentication

Micropub requests MUST be 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] Micropub servers MUST accept the token using both methods.

Authorization: Bearer XXXXXXXXX

Form-Encoded Body Parameter

access_token=XXXXXXXXX

5.2 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 from a URL. See Obtaining an Access Token for more details.

5.3 Endpoint Discovery

Micropub defines a link relation value of micropub to link to a website's Micropub endpoint from the profile page identifying the user.

A Micropub client SHOULD be able to be configured by authenticating with a domain name using [IndieAuth]. During this authentication (and authorization), the client discovers the Micropub endpoint which will be used to create posts, as well as obtains an access token it will use in the Micropub requests.

The client looks for a <link rel="micropub"> tag in the HTML head of the URL used to authenticate, or sends an HTTP Link header with a rel value of micropub.

Link: <https:

HTML Link Tag

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

5.4 Scope

The Micropub server MUST require the bearer token to include at least one scope value, in order to ensure posts cannot be created by arbitrary tokens.

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.

Most Micropub servers require clients to obtain the "create" scope in order to create posts. However, some servers MAY require more granular scope, such as "delete", "update", or "create:video", in order to limit the abilities of various clients. See Scope for more details and a list of all currently used values for scope.