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.
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"
]
}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-Afterheader 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." }
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.
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 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"
}
},
// ...
}
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 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.
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.
$ http https://pine.blog/api/sites/search?q=something \
"Authorization: Token {your token}"
💡 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.
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": {
"updated_at": "",
"url": "https://pine.blog/api/feeds/{feed.id}",
},
}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.
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
List
Fetch a paginated list of collections and a few of the top recommended sites in that category.
This endpoint provides a paginated list of all of the collections available in the Pine.blog API. The featured sites in each collection are curated by the Pine.blog editor and ranked by the number of times a Pine.blog user has recommended the site.
Query Parameters
The following parameters should be included as part of a URL query string.
| Parameter | Description |
|---|---|
page | A page number within the paginated result set. |
Feeds
Read
Fetch information about a given feed.
This endpoint provides information, in depth, about a given feed. Every feed has a URL pointing towards its detail view. The feed contains information about the type of feed it represents as well as any data obtained from that feed, a link to the feed on the host site, when it was last updated, a set of recent posts for the feed, and an approximation as to how often the feed has new content.
Authenticated Users: The feed will also contain information about any subscriptions that the current user has to the feed. Additionally, authenticated users will see more recent posts in a feed than a non-authenticated user.
Path Parameters
The following parameters should be included in the URL path.
| Parameter | Description |
|---|---|
id required |
Query Parameters
The following parameters should be included as part of a URL query string.
| Parameter | Description |
|---|---|
search | A search term. |
Posts
Read
Fetch the details of a given post
This endpoint provides information about a post with the given ID. This includes information about the author, metadata about the post, the parent feed and site, both HTML and plain-text versions of the post's contents (including pre-shortened versions suitable for display in a twitter-like list), and links to any medium-to-large sized images found in the post's HTML.
Authenticated Users: Posts will also contain information about whether the given user has liked the post.
Path Parameters
The following parameters should be included in the URL path.
| Parameter | Description |
|---|---|
id required |
Query Parameters
The following parameters should be included as part of a URL query string.
| Parameter | Description |
|---|---|
search | A search term. |
Sites
Search
Search the Feed Directory for a site
This endpoint requires a search query parameter q
containing a given user's query string (URL encoded of course) and returns a
list of paginated results for sites matching the query. Each site in result
set also includes a detail link (see below) which can be used to retrieve
more detailed information about the site. The API also returns some
additional information and links about both the query statistics.
Advanced Search Syntax
The search API supports Lucene-style advanced search syntax with logical operators and quoted strings. By default all terms in a query are treated with AND operators between them unless otherwise specified.
("current events" or news) and (spain or italy or france or england)Field Filtering
The new search API also supports field filters on any of the site fields: description, link, title, total_recommendations, and type. Terms can be grouped with parentheses.
apple type:microblog or title:(open sesame)Fuzzy Matching
Search also supports fuzzy glob-style matching using wildcard expressions like ? to represent a single character and * to represent any number of characters.
Note that a wildcard starting with ? or * is very slow, and also that these wildcards only match individual terms.
te?t test* *b?g*Read
Fetch the details of a single site.
This API also returns information about
the site's feeds including the default_feed and some recent posts in that feed.
Authenticated Users: This endpoint will also return information about an recommendations that the user has made for this site.
Path Parameters
The following parameters should be included in the URL path.
| Parameter | Description |
|---|---|
id required |
Query Parameters
The following parameters should be included as part of a URL query string.
| Parameter | Description |
|---|---|
search | A search term. |
Tags
List
Fetch a paginated list of tags and a few of the top recommended sites in that category.
This endpoint provides a paginated list of all of the tags available in the Pine.blog API. The featured sites in each tag are curated by the Pine.blog editor and ranked by the number of times a Pine.blog user has recommended the site.
Query Parameters
The following parameters should be included as part of a URL query string.
| Parameter | Description |
|---|---|
page | A page number within the paginated result set. |
Read
Fetch a single tag and any top recommended sites in that category.
This endpoint provides the same interface as the list endpoint, just only for a single tag.
The list of sites featured in a tag are also paginated. Links to further pages of sites for a tag are given in the API if any.
Path Parameters
The following parameters should be included in the URL path.
| Parameter | Description |
|---|---|
slug required | A unique value identifying this tag. |