Pine.blog's API supports token-based and HTTP Basic authentication for users wishing to access their data using the Pine.blog API, or those wishing to take advantage of the higher rate limits that logging in with their account provides.

💡 Important: Authenticated requests return slightly different data than un-authenticated requests. If you're authenticated, feeds, sites, and posts will contain information about your subscriptions and recommendations. These additional endpoints are currently in beta and will be released here when they're ready.

Token Based Authentication

API tokens are useful for scenarios where a user may not want to give the client application access to their account credentials. API tokens are also useful when building automated tooling like scripts, scheduled jobs or when integrating with tools like IFTTT or other automation services.

You can find or generate your API token in your account page and using it to make requests is simple. Just add an Authorization: Token {your token} header to your request.

# Using Token-based Authentication
$ http https://pine.blog/api/sites/search?q=something \
  "Authorization: Token {your token}"

HTTP Basic Authentication

You can also access the Pine.blog API using traditional HTTP Basic Authentication. In this case the API expects an Authorization: Basic {credentials} header where the credentials are the base-64 encoded, colon-separated username and password. This method also accepts the user's email address as their username, just like the web form on the site, but because of legacy concerns, email addresses may not be unique enough to log a user in.

# Using HTTP Basic Authentication
$ http https://pine.blog/api/sites/search?q=something \
  "Authorization: Basic {base64 encoded username:password}"

Pine.blog supports Webhooks as a method that developers can use to get up-to-date information from the Pine.blog API about when a feed changes. Once you've added a Webhook URL in your account settings page Pine.blog will start sending requests to you to let you know that Pine.blog has detected changes in a feed.

Currently Pine.blog only sends you Webhooks for feeds you're subscribed to.

When Pine.blog notifies you of a change to a feed, it will send a POST request to the URL provided in your accounts page. The request will contain an X-Webhook-Token header. Your app should verify the value of this header with the value in your accounts page. Requests that don't match this value are not from Pine.blog.

The body of the request to your server will look something like this:

HTTP/1.1 POST /your/webhook/url
...various headers...
X-Webhook-Token: YOUR_WEBHOOK_SECRET

{
    "token": "YOUR_WEBHOOK_SECRET",
    "event_type": "feed.updated",
    "data": {
        "id": "{feed.id}",
        "url": "https://pine.blog/api/feeds/{feed.id}",
        "updated_at": "2020-02-01T00:00:32Z"
    },
}

The value of the event_type and data.url fields will correspond to the resource that was updated.

Note that the body of the request also contains your Webhook Token. Applications may use either the token in the body or in the headers to validate webhook requests.

Webmentions allow Pine.blog to communicate with, receive content from, and post content to other sites. When a user on Pine.blog links to a site or likes a post, Pine.blog will automatically send Webmentions to the relevant sites (if the user has enabled Webmentions and the target site supports Webmentions).

If you'd like to send Webmentions from your platform or service to Pine.blog, simply discover the Webmention Endpoint (as per the spec) send Webmention requests to it. Pine.blog accepts any of the criteria tested by the Webmention.rocks Test Suite including updating and deleting Webmentions.

Webmention requests to Pine.blog take the following form as per the Webmention Specification →

HTTP/1.1 POST /api/webmentions
Content-Type: application/x-www-form-urlencoded

source=https://my.site/a/post/that/mentions/some/post/on/pine.blog.html
&target=https://pine.blog/u/<username>/archive/<post-id>

Important: Developers of apps using the Pine.blog API do not need to send Webmentions. Pine.blog will handle sending and receiving Webmentions when the user publishes a draft or likes/unlikes a post.

Pine.blog uses h-entry classes when parsing incoming Webmentions and stores that information for display on a user's blog. It is recommended that sites include a top-level h-entry that includes the name and content of the commenting/replying post and information about the author (preferably as an h-cite). This information is what is displayed next to the post's content. You can test your Webmentions against the Webmention.rocks Test Suite. If your icons and usernames appear there, they should work on Pine.blog.

For added assurance, you can test your h-entry metadata with the Microformats Parser library. Pine.blog uses this library to parse all incoming Webmentions.

Pine.blog aims to be as friendly as possible to the open web. If you build tools, features, or apps using the Pine.blog API, that's awesome! Please just mention that you use Pine.blog in your app or service, and if you rely on Pine.blog then please consider signing up for a paid subscription.