API Endpoints Reference

Pine supports many different public API endpoints and the complete list is found here. These endpoints cover anything from searching for sites, getting detailed information about a site and it's feeds, and authenticating with premium account credentials to remove the default throttling limits.

API Root

/api/

This is the root endpoint url. This endpoint contains a series of links to other public parts of the API.

$ http /api/

{
    "sites": "https://pine.blog/api/sites",
    "tags": "https://pine.blog/api/tags"
}

Site Search New!

/api/sites/search?q=some+query

Like the old search API, this endpoint requires a search query parameter 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 now also returns some additional information and links about both the query statistics and some options to filter their query using related_searches.

This new search API is dramatically faster at searching and indexing compared to the previous API and provides much more in the ways of filtering and sorting results.

  • Advanced Search Syntax

    The new 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: Note that a wildcard starting with ? or * is very slow, and also that these wildcards only match individual terms.

    te?t test* *b?g*
$ http /api/sites/search?q=wiki

{
    "count": 2,
    "next": null,
    "previous": null,
    "related_searches": {
        "all": "http://pine.blog/api/sites/search?q=test",
        "blogs_only": "http://pine.blog/api/sites/search?q=test+type%3Ablog",
        "microblogs_only": "http://pine.blog/api/sites/search?q=test+type%3Amicroblog",
        "photoblogs_only": "http://pine.blog/api/sites/search?q=test+type%3Aphotoblog"
    },
    "results": [
        {
            "description": "the official blog of test double",
            "link": "http://blog.testdouble.com",
            "title": "Test Double | Our Thinking",
            "total_recommendations": 0,
            "type": "blog",
            "url": "http://pine.blog/api/sites/12a7ed81-9ae3-4ad6-9ef2-b90149518a39"
        },
        {
            "description": "my thoughts (in no particular order)",
            "link": "http://www.outofmygord.com/",
            "title": "Comments on: Test home page",
            "total_recommendations": 0,
            "type": "blog",
            "url": "http://pine.blog/api/sites/bc2b49d9-626b-42f6-b90c-b67cab65abe1"
        }
    ],
    "statistics": {
        "query_runtime": 0.0013144859985914081
    }
}

Site Search Deprecated!

/api/sites?search=some+query

This API is still functional but will be unreliable after 01/01/2018. It was replaced by the new search API.

This endpoint requires a search query parameter 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 the site's information directly.

$ http /api/sites?search=wiki

{
    "count": 4,
    "next": null,
    "previous": null,
    "results": [
        {
            "description": "The Main web of Vanderbilt Biostatistics Wiki. Welcome to Vanderbilt Biostatistics Wiki ... meet people on this site ",
            "feeds": [
                {
                    "feed_url": "http://biostat.mc.vanderbilt.edu/wiki/bin/view/Main/WebRss",
                    "last_updated": "2017-09-13T21:39:25.531654Z",
                    "type": "rss"
                }
            ],
            "image": null,
            "link": "http://biostat.mc.vanderbilt.edu/wiki/bin/view/Main",
            "tags": [],
            "title": "Vanderbilt Biostatistics Wiki's Main web",
            "total_recommendations": 0,
            "type": "blog",
            "url": "http://pine.blog/api/sites/148675a5-864d-4c0d-b70e-ae20cd71bcb2"
        },
        {
            "description": "Extract tables from PDFs and scrape the web",
            "feeds": [
                {
                    "feed_url": "https://blog.scraperwiki.com/feed/",
                    "last_updated": "2017-09-13T21:50:24.096952Z",
                    "type": "rss"
                }
            ],
            "image": null,
            "link": "https://blog.scraperwiki.com",
            "tags": [],
            "title": "ScraperWiki",
            "total_recommendations": 0,
            "type": "blog",
            "url": "http://pine.blog/api/sites/32b99263-5afb-4a6a-bea1-fe6dc3d97104"
        }
    ]
}

Site Page

/api/sites/{id}

This endpoint returns the details for the site indicated by the {id} in the URL and contains all of the information about a site including when Pine last checked the site's feeds.

$ http /api/sites/d063a62f-ee3a-4cbd-96c9-0bde321ee7b7

{
    "description": null,
    "feeds": [
        {
            "feed_url": "http://www.museofadventure.com/journal?format=RSS",
            "last_updated": "2017-09-13T21:50:28.912817Z",
            "type": "rss"
        }
    ],
    "image": null,
    "link": "http://www.museofadventure.com",
    "tags": [
        {
            "name": "Personal Blogs",
            "url": "http://pine.blog/api/tags/personal"
        },
        {
            "name": "Arts and Culture",
            "url": "http://pine.blog/api/tags/art"
        }
    ],
    "title": "MuseofAdventure",
    "total_recommendations": 0,
    "type": "photoblog",
    "url": "http://pine.blog/api/sites/ef0e7403-ca84-4282-b362-e9c330683e03"
}

Tags List

/api/tags

This endpoint provides links to all of the different tags and their associated Top Charts of Sites.

$ http /api/tags/art

{
    "count": 1,
    "next": null,
    "previous": null,
    "results": [
        {
            "name": "Technology",
            "sites": [
                {
                    "description": "",
                    "feeds": [
                        {
                            "feed_url": "http://www.manton.org/feed",
                            "last_updated": "2017-09-13T22:48:58.568975Z",
                            "type": "rss"
                        },
                        {
                            "feed_url": "http://www.manton.org/comments/feed",
                            "last_updated": "2017-09-13T22:48:59.121717Z",
                            "type": "rss"
                        },
                        {
                            "feed_url": "http://www.manton.org/feed/json",
                            "last_updated": "2017-09-13T22:48:59.725164Z",
                            "type": "jsonfeed"
                        }
                    ],
                    "image": null,
                    "link": "http://www.manton.org",
                    "tags": [],
                    "title": "Manton Reece",
                    "total_recommendations": 0,
                    "type": "blog",
                    "url": "http://pine.blog/api/sites/7c781861-749e-45ff-aefb-76a3e3cdfc0f"
                }
            ],
            "url": "https://pine.blog/api/tags/tech"
        }
    ]
}

Tag Page

/api/tags/{slug}

A given tag and it's Top Charts list and further details will be under this endpoint. Here you'll find a list of feeds sorted by number of recommendations that are classified under the given tag as well as some additional information about the tag itself.

$ http /api/tags/tech

{
    "name": "Technology",
    "sites": [
        {
            "description": "",
            "feeds": [
                {
                    "feed_url": "http://www.manton.org/feed",
                    "last_updated": "2017-09-13T22:48:58.568975Z",
                    "type": "rss"
                },
                {
                    "feed_url": "http://www.manton.org/comments/feed",
                    "last_updated": "2017-09-13T22:48:59.121717Z",
                    "type": "rss"
                },
                {
                    "feed_url": "http://www.manton.org/feed/json",
                    "last_updated": "2017-09-13T22:48:59.725164Z",
                    "type": "jsonfeed"
                }
            ],
            "image": null,
            "link": "http://www.manton.org",
            "tags": [],
            "title": "Manton Reece",
            "total_recommendations": 0,
            "type": "blog",
            "url": "http://pine.blog/api/sites/7c781861-749e-45ff-aefb-76a3e3cdfc0f"
        }
    ],
    "url": "https://pine.blog/api/tags/tech"
}

Premium User API Authentication

If you're a premium user, you can use the account credentials, found on your profile page, to bypass the normal request throttling.

Pine uses OAuth2's client_credentials flow to authenticate and authorize clients. This means that authenticated clients do not have access to any user's specific data. Requests are instead tied to the developer's own account. This also means that the authentication flow is fairly simple and doesn't require users to authorize an application to use Pine.

Important: There is still a throttle on Premium account requests of 1000/minute, but it mainly exists to prevent spam. If you run into a problem with this limitation please contact us.

Authenticating with the API

Before making authenticated requests, every client needs to request an access token to make requests with. To get an access token, make a POST request to /api/o/token/ using HTTP basic authentication with your client_id as the username and client_secret as the password. The request must also have a grant_type request parameter with the value set to client_credentials.

$ curl -X POST http://pine.blog/api/o/token/ \
    -u "<client_id>:<client_secret>" \
    -d "grant_type=client_credentials"

{
    "access_token": "my_sample_token",
    "expires_in": 36000,
    "scope": "read",
    "token_type": "Bearer"
}

Important: Requests to the OAuth API must be form encoded. JSON encoding, though supported for the rest of the API is not supported for OAuth token endpoints.

Important: The above flow does not provide a refresh token. If your token becomes expired you must request a new one.

Making Authenticated Requests

Once you've authenticated and gotten an access token, simply add an Authorization: Bearer <access_token> header to your requests. That's it, you're done!

$ curl -H "Authorization: Bearer <access_token>" \
    https://pine.blog/api/sites?search=siracusa

Revoking a Token

You can revoke an access token by making a POST request to /api/o/revoke_token with the token, client id, and client secret as form parameters.

$ curl --data "token=<access_token>&client_id=<client_id>&client_secret=<client_secret>" \
    https://pine.blog/api/o/revoke_token/