Pine.blog API
Documentation for the Pine.blog and Feed Directory APIs.

Pine.blog's API provides a simple and easy way to query The Feed Directory's index of blogs, microblogs, and photoblogs as well as access your own personal Pine.blog data for personal use. The API is modern, free, and follows a JSON-REST style (no more XML-RPC 🎉). Access to the API does not require a login token or OAuth key, however requests are throttled and some fields are omitted based on the authentication level.

Request Methods

The Pine.blog API is a JSON-REST API and abides by most of the typical REST paradigms. The API uses response codes and HTTP request methods to determine intent. This is enforced as much as possible so while it may not be strictly the case for all endpoints, the vast majority of endpoints use the standard conventions.

Options

Most endpoints support the HTTP Options request method. Responses to OPTIONS requests will describe the format, parameters, and acceptable content types that are relevant to the endpoint. Below is a sample of what an OPTIONS response will look like.

OPTIONS /api/sites/search

{
    "name": "Search",
    "description": "...",
    "renders": [
        "application/json",
        "text/html"
    ],
    "parses": [
        "application/json",
        "application/x-www-form-urlencoded",
        "multipart/form-data"
    ]
}
Response Codes

Most response codes used by Pine.blog's API reflect standard behaviour defined in the HTTP specification. Below is an overview of any special HTTP codes returned by the Pine.blog API.

  • 429 Too Many Requests

    If you've exceeded your request count, then subsequent requests will receive responses with error code 429 with both a response containing a human-readable message and a Retry-After header field with the seconds until requests will again be accepted.

    $ http https://pine.blog/api/too_frequent_request
    
    HTTP/1.0 429 Too Many Requests
    Allow: GET, HEAD, OPTIONS
    // ...
    Retry-After: 34
    
    {
        "detail": "Request was throttled. Expected available in 34 seconds."
    }
    
Throttling Limits

Requests to the API are rate limited to prevent spam. Normally this won't be an issue for users or for those looking to write simple scripts against the API. However if you need more frequent access to the API you can upgrade to a Premium Account to up the limit. Premium accounts are useful for anyone wanting to build production software against the Pine.blog API.

Authentication Method Rate Limit
No Authentication 60/minute
Authenticated w/ Free Account 100/minute
Authenticated w/ Premium Account 1000/minute

Note: If you require that the limit be removed, please email support@skyrocket.software and we can talk about your needs.

Meta Entries

API responses may, at any time, include a _meta entry at the top level. This entry will contain at least one important piece of information about the current query or endpoint. These can be deprecation notices, beta API notices, and more. These notices are intended to be read by a developer and provide helpful information about the requested API endpoint.

Deprecation Notices

Deprecation notices will often, but not always include an effective_date and replaced_by entry if one exists. In all cases the deprecation notice will have a plain-text message explaining the deprecation.

As an example, if an API was deprecated, then the developer requesting the deprecated API would see something like the following:

$ http http://pine.blog/api/some_deprecated_api

{
    "_meta": {
        "deprecation_notice": {
            "effective_date": "2018-01-01",
            "message": "Warning, this API has been deprecated and will be no longer be reliable after the specified date.",
            "replaced_by": "/api/some_new_api"
        }
    },
    // ...
}
Beta Notices

Endpoints are sometimes released while still in beta for developers to try out and give feedback. These APIs will not only be marked as beta in the documentation, but will also have a beta_notice in the meta section of all API responses.

Beta notices will often, but not always include an link entry which points to a section of the documentation explaining the new endpoint. In all cases the beta notice will have a plain-text message explaining that is is subject to change.

$ http http://pine.blog/api/some_beta_api

{
    "_meta": {
        "beta_notice": {
            "link": "https://pine.blog/api/documentation#some_beta_api",
            "message": "Warning, this endpoint is currently in beta and is subject to change. Please see our documentation for more information."
        }
    },
    // ...
}

Authentication

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

Webhooks

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

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.

H-Entry and Webmentions

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.

Attribution

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.


API Methods

Below are the various endpoints that are available in the Pine.blog API. Because Anonymous, Authenticated, and Premium Users have different access levels, the available endpoints below are shown based on your current authenticated status. That is, if you are logged into Pine.blog, you may see additional endpoints listed below.

Collections

Feeds

Posts

Sites

Tags