Documentation for the and Feed Directory APIs.'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 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 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.


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": [
    "parses": [
Response Codes

Most response codes used by's API reflect standard behaviour defined in the HTTP specification. Below is an overview of any special HTTP codes returned by the 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
    HTTP/1.0 429 Too Many Requests
    // ...
    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 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 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

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

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

Authentication's API supports token-based and HTTP Basic authentication for users wishing to access their data using the 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 \
  "Authorization: Token {your token}"

HTTP Basic Authentication

You can also access the 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 \
  "Authorization: Basic {base64 encoded username:password}"

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

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

When 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

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

HTTP/1.1 POST /your/webhook/url
...various headers...

    "token": "YOUR_WEBHOOK_SECRET",
    "event_type": "feed.updated",
    "data": {
        "id": "{}",
        "url": "{}",
        "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 to communicate with, receive content from, and post content to other sites. When a user on links to a site or likes a post, 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, simply discover the Webmention Endpoint (as per the spec) send Webmention requests to it. accepts any of the criteria tested by the Test Suite including updating and deleting Webmentions.

Webmention requests to take the following form as per the Webmention Specification →

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


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

H-Entry and Webmentions 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 Test Suite. If your icons and usernames appear there, they should work on

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

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

API Methods

Below are the various endpoints that are available in the 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, you may see additional endpoints listed below.