A WebMention Endpoint

API Documentation

Fetch mentions

Path: /api/mentions

Returns a JSON-encoded array with all posts whose mentions matches the defined query paramaters

Is CORS-enabled to enable use by web applications.

Example

[ { "author": { "name": "Bob Smith", "photo": null, "url": "http://example.com/about" }, "name": null, "published": 1378650110000, "summary": "Thats such a great post!", "targets": [ "http://example.org/another-post" ], "type": "reply", "interactions": [ "http://example.org/another-post" ], "interactionTarget": true, "url": "http://example.com/post" } ]

Response parameters

Apart from the self explanatory ones, here's a description of the response parameters:

• type – the interaction type. Currently supported are: like, repost, reply and lastly also "mention" which is really a non-interaction. More may be added in the future.
• interactions – all the URL:s interacted with by the post (liked, reposted etc depending on the post type). Interaction URL:s are included even if they don't match the specified query and even if they never were pinged to this WebMention endpoint. Purely mentioned URL:s are never included as mentions are never considered an interaction.
• targets – all the target URL:s that were mentioned in the post and which matches the query of request
• interactionTarget – available for non-mention interactions and set to "true" or "false" dependening on whether a normalized target URL matched a normalized interaction URL or not. This is to tell whether the interaction is an interaction or just a mention from the perspective of the query.
• published – microsecond timestamp – for that special javascript feeling!

Query parameters

• example – when set returns dummy data rather than real data. Useful for testing. Returns a new random set each time, showing a variety of different possible combinations.
• path=http://example.com/foo – multiple allowed – includes all WebMentions that mentions a page on the specified path or below (eg. both WebMentions mentioning http://example.com/foo and http://example.com/foo/bar will be included)
• site=example.com – multiple allowed – includes all WebMentions mentioning a page on the specified site
• url=http://example.com/foo/bar.html – multiple allowed – includes all WebMentions mentioning the specified URL
• interactions=1 – experimental – set to 1 or 0 to either include only like/repost interactions or only non-like/repost posts. When returning only interactions an interaction is only included if the target of the interaction matches the query. Normally interactions are included also if they just mentioned a page matching the query.
• sort=desc – if set to "desc" then the returned mentions will be sorted with the newest one on top
• format=html – if set to "html" a full microformatted HTML-page will be returned rather than a JSON-response

Realtime mentions

Path: /api/mentions/live

An EventSource stream that the browser can subscribe to. The realtime counterpart to the /api/mentions endpoint. Sends mention events with the JSON-encoded mention object for all new mentions that would be included in a request to that endpoint.

Is CORS-enabled to enable use by web applications.

Supports the same query parameters as /api/mentions, except for the "interactions" one.

HTML Embedding

Path: /api/embed

Returns a javascript that, when included in a page, will add an HTML representation of all the matching WebMentions as well as subscribe to new matching mentions in realtime and add them as they come.

Simple example

http://example.com/api/embed?url=http://example.com/foo

Advanced example

http://example.com/api/embed?url=http://example.com/foo/1&url=http://example.com/foo/2&path=http://example.com/bar

Preferred usage

<script id="webmention-hosted"> (function () { var sn = document.createElement("script"), s = document.getElementsByTagName("script")[0], url; url = document.querySelectorAll ? document.querySelectorAll("link[rel~=canonical]") : false; url = url && url[0] ? url[0].href : false; sn.type = "text/javascript"; sn.async = true; sn.src = "//example.com/api/embed?url=" + encodeURIComponent(url || window.location); s.parentNode.insertBefore(sn, s); }()); </script>

Query parameters

Supports all query paramaters of the /api/mentions endpoint (except for the "format" one) as well as the ones below:

• version – the version of the embed script to use

Experimental query parameters

• nofacepile – only in cutting-edge – disables the facepile that's included by default in the cutting-edge version
• nocontext – only in cutting-edge – hides the mentioned URL:s that will otherwise show on embeds that pulls in mentions from multiple URL:s

Currently available versions are

• cutting-edge – an unstable, experimental version where ideas and future features are tested before new versions are released. Do not use in production, but follow updates to the project closely and give feedback! :)
• none – the first initial release had no specified version and is thus the default one if no version is defined. This version is stable and will receive no breaking changes. Incpmatible changes will instead be introduced as new versions.