FeedDirectory
FAQ  -  Apps  -  API Docs  -  Blog  -  Support  -  Contact

Connecting voices across open platforms

Publish, Subscribe, Follow

Connecting content producers with consumers, and enabling consumers to discover new content from their favourite producers and their friends.

We provide developers of all applications (web, mobile, desktop), simple APIs to build great products on top of open data. Users enjoy data portability between all applications that use the service.

People are free to use whatever platform they wish for their content. From a large silicon-valley services, to self-hosted systems. Anything that provides an RSS feed is supported by the directory.

Users control what data is public, private, or just for their select audience. Users control how they can be discovered - by using either an email address or a unique name.

Privacy is built-in. We DO NOT track you, we DO NOT want to know who you are, we DO NOT even want your real name or email address (but you may want to give a valid email address to enable account recovery if things go wrong - but we never store email addresses). If you only want to read the directory then you don't even need an account.

We firmly believe in freedom of speech and freedom of expression. We do not host any of your content, you choose where that is, and it is not our intention to de-platform anybody for what they have to say, no matter if we agree with it or not. It is the content producer's responsibility to ensure they are operating with the law where they reside and where their content resides. It is the responsibility of the content consumer to only consume content that is legal where they live. That said, be nice to each other.

Calling all developers

If you develop a podcast player, an RSS reader, or a content production platform, we'd love for you to integrate with feeddirectory.org. You don't need to ask for an API key or secret password, all of our API docs are available online. If you can think of a feature you'd like to see adding, please let us know. Our aim is to provide you with backend services that will do subscription management and provide "follow this user" functionality so you don't have to.

Calling all content producers

Ask your content platform provider to support the feeddirectory.org service. Most content platforms already provide RSS feeds can be simply added to the directory. See our apps section to see if your platform is already supported.

COMING SOON: If your platform is not yet fully integrated, you can register for a feeddirectory.org account, and add your RSS feeds yourself using FollowMyWords.com - our free to use front-end to the directory. The directory gives you one place where you can make all of your content available, and you can take your audience with you if you decide to move platforms, or if that decision is made for you by others.

Calling all consumers of content

Ask the developers of your favourite Podcast and RSS reader applications to support the feeddirectory.org service. There is no cost, and it will allow you control and portability of your data.

COMING SOON: If your player/reader is not yet integrated, you can register for a feeddirectory.org account, and add your favoutite RSS feeds yourself using FollowMyWords.com - our free to use front-end to the directory.


FAQ

What is this? What can I use it for?

Put simply, it is a place where you can store links to things that you publish (blog posts, podcasts, anything RSS), and things that you like to read or listen to. Your lists of things are associated with your username. You can then share your username and people can see what you publish, and also what you like to consume. Everything in one place.

Once you have an account, you can "follow" other accounts that you are interested in.

There is also the ability to be discovered by email address. If somebody doesn't know what your username is on the directory, but does know your email address, they can look up your account by using that.

For app developers, this gives you a pre-built backend service for managing subscriptions to RSS feeds. By integrating with this it allows your new users to bring their subscriptions with them to your app.

For content producers, this gives you a place to let your readers/listeners know of new content that you're releasing. Your audience follow your account and will see new blogs and podcasts when you launch them.

For readers and listeners, this gives you a single place to store links to the content that you like to consume. It also allows you to move between all apps that support the directory without having to rebuild your subscription lists - you get the same subscriptions on your laptop, tablet, and phone. There is also the ability synchronise the position within an episode / article. This enables the ability to, for example, pause a podcast on one device, and then pick up at the same place on another.

We're working on implementing various privacy levels so you can share links with everybody, just with your followers, or keep your lists private, just for you.

What logging do you perform?

Very little.

We keep API access logs (the normal logs that nginx uses) for a couple of days so we can troubleshoot any issues that may occur. These logs will contain the URL of the API that has been accessed, the time of day, and the IP address of the client. If you're not happy about this, use a VPN or TOR to hide your real IP address - we don't mind.

We do record how many times each account has been accessed, but DO NOT record details of each access - we just keep a counter and a last-used time to see which accounts are most active and which are dormant.

We keep a counter of successful and unsuccessful API requests from each IP address that makes a request to the system. These counters are NOT associated with accounts. They are intended to be used to spot attempts to abuse the system.

The only time we associate an IP address with an account is if a request is made to re-activate/recover an account. The IP address where the request was made from is included in an email sent to the account holder. After a short period of time we purge these requests from the database.

How do you send emails if you do not store an email address?

When you create an account you're asked to supply an email address to associate with the account. We store a hash of this email address. If in the future you try to recover the account (because you've lost your ID or secret), you're asked for your email address again. This is hashed and compared to the stored hash value, and if they match the email address you have entered is used to send an account recovery email. If they do not match no email is sent.

What hashing algorithm do you use?

We use SHA-256. Email addresses are stored using a straight hash. Account secrets are stored using salted-hashes.

Are you building an index of content?

No, that's not what we're building. We want to be the place where people list the content that they produce, and store their subscriptions to content that they consume. We then provide a way to discover the content that people wish to share.

Can I integrate feeddirectory.org into an app that I'm building?

Excellent! Yes, go for it. Read our API Docs and let us know how you get on so we can list your awesomeness on here.

What happens if I am banned / suspeded / kicked / de-platformed from a service that I'm publishing to?

For people that follow you through feeddirectory.org, your move to a new platform should be pretty easy. You should remove the published URL of the old platform, and then add the URL of your new home. Depending on which application your followers are using to consume your content, they may automatically get subscribed, get an alert, or simply be able to see that you have a new home. A core concept of feeddirectory.org is that people follow your account here and not on the various content platforms, so you as a content producer are free to host your content wherever you like and switch when you choose to do so.

Will you de-platform me if I say something you don't like?

No. We will only remove a URL or account from the directory if we are required to do so by law. We currently host the service in the UK, and operate under the laws of England and Wales. As we do not host any content ourselves, and just store your links to your content, we believe that such instances should be very rare. It is your responsbility to ensure you are obeying the relevant laws where you live.

Do you use AWS, Azure, Google or any other public cloud vendors for your hosting?

No. We do not make use of any public cloud hosting. We do use a Google hosted font on this webpage, but that's about the end of our involvement with them. We are currently hosted by a boutique ISP in the UK called Watchfront. They are lovely people and we urge you to buy stuff from them.

Are there any limits to the amount of times I can use the service?

Not at the moment. If we see people abusing it (e.g. thousands of feeds being added to single accounts) then we may implement some countermeasures, but at the moment there are no limits. We do limit some APIs on the amount of data that they return at any one time - the details are in the API docs where this takes place. We also perform rate-limiting of API calls - which should not impact normal users of the service.

How do I permanently remove my account?

We permanently purge deactivated accounts from our database 90 days after they are deactivated. After this time there is no way to recover an account.

I've forgotten the email address that I used to create the account, can you recover it for me?

No, sorry, by design we choose not to hold email addresses (only non-reversable hashes of them) so do not know which account is yours unless you can provide the same email address again. Also, we will not change email addresses on any account manually. You can change your own email address but this does require you to have access credentials for the account.

Apps

Content viewers / players

Integrated

Application Platforms
FollowMyWords.com Web COMING SOON: ... a simple but functional proof-of-concept from the people behind feeddirectory.org

Content platforms

Itegrated

Coming soon...

RSS Feeds

Lots of platforms provide RSS feeds of your content. Here are a few we know about. Please let us know what we're missing.
Blogger The RSS feed for Blogger hosted sites can be found by appending /rss.xmlto the end of the blog URL. For example, our Blog at https://feeddirectorydev.blogspot.com has an RSS feed at https://feeddirectorydev.blogspot.com/rss.xml
LiveJournal LiveJournal offers a few options for RSS feeds. This normally involves adding /data/atom or /data/rss to the end of your LJ URL. More information: https://www.livejournal.com/support/faq/149.html
Tumblr The RSS feed for Tumblr hosted blogs can be found by appending /rssto the end of the blog URL. For example, if your Tumblr blog address is https://myblog.tumblr.com then your RSS feed will be https://myblog.tumblr.com/rss
Reddit Reddit provides many RSS feed options. In most cases, you can create an RSS feed by adding .rss to the end of an existing reddit URL. A comprehensive list is available: https://www.reddit.com/wiki/rss
Pinterest Pinterest provides a few RSS feed options. The URL for the RSS feed of all your items is https://pinterest.com/YOUR-USERNAME/feed.rss, and for a specific board it will be https://pinterest.com/YOUR-USERNAME/BOARDNAME.rss
Wordpress The RSS feed for Wordpress content is normally found by adding /feed to the end of the site URL. For example, the RSS feed for wordpress.org can be found at wordpress.org/feed.

Similarly, the RSS for a Wordpress site hosted on mylovelywordpresssite.com would be at mylovelywordpresssite.com/feed.
Medium The RSS feed for Medium content can be found by adding /feed/ before your account name in the URL. For example, if your site is on https://medium.com/my-medium-site your RSS feed will be https://medium.com/feed/my-medium-site
Twitter Twitter does not provide an RSS feed directly, but there are a number of third-party services that claim to:

https://feeder.co/knowledge-base/rss-feed-creation/twitter-rss-feeds/

https://zapier.com/blog/twitter-rss-feed/

https://rss.app/blog/how-to-create-twitter-rss-feeds

Facebook Facebook does not provide an RSS feed directly, but there are a number of third-party services that claim to:

https://zapier.com/blog/facebook-rss-feed/

https://rss.com/blog/facebook-rss-feed/

Instagram Instagram does not provide an RSS feed directly, but there are a number of third-party services that claim to:

https://rss.app/blog/how-to-create-instagram-rss-feeds


API

All APIs are hosted at https://feeddirectory.org/api/1.0/ and support parameters in the URL or as fields from a form POST. Most of the APIs require the credentials for an account to be provided. This can either be done by supplying the parameters account-uuid and account-secret along with the other parameters, or by setting the X-FeedDirectory-Auth header.

All APIs will return a status code of 200 for a successful operation, or another code to signify an error. In the case of an error, a short explanation of the problem will be returned.

Some of the APIs where authentication is optional may return different data if authentication is not performed. Privacy settings apply to publish, subscribe and follow data.

If you're building an application that will use the API, please also include a "User-Agent" header with your requests to enable the diagnosis of any problems that may occur.

Create Account

Creates an account

/api/1.0/Account/Create
email Required The email address of the account holder. This address is used to recover the account if the system assigned credentials are lost.

Example Requests

GET /api/1.0/Account/Create?email=myname@example.com

curl 'https://feeddirectory.org/api/1.0/Account/Create?email=MY_EMAIL_ADDRESS'

Example Responses

200
{
  "account-uuid" : 
    "MY_ACCOUNT_UUID",
  "account-secret" : 
    "MY_ACCOUNT_SECRET",
  "public-short-code" : 
    "MY_SHORT_CODE"
}
The account-uuid and account-secret should be retained for subsequent API calls. This is the only time these will be issued. The public-short-code is a unique reference for the account which is public. This code is system generated on account creation, but can be changed to another value.
409
Account already exists
400
Invalid email address

Account Info

Gets some basic metrics for an account.

/api/1.0/Account/Info
Authentication Required

Example Requests

GET /api/1.0/Account/Info?account-uuid=MY_ACCOUNT_UUID &account-secret=MY_ACCOUNT_SECRET

curl -H 'X-FeedDirectory-Auth: MY_ACCOUNT_UUID:MY_ACCOUNT_SECRET' 'https://feeddirectory.org/api/1.0/Account/Info'

Example Responses

200
{
  "published-feeds" : 1,
  "subscribed-feeds" : 33,
  "following" : 4,
  "followers" : 13,
  "public-short-code" : 
    "MY_SHORT_CODE"
}
403
Unable to authenticate

Change Short Code

Change the public short code for an account. The short code uniquely identifies the account to others.

/api/1.0/Account/ShortCode/Change
Authentication Required
public-short-code Required The new short code for the account.

Example Requests

GET /api/1.0/Account/ShortCode/Change?account-uuid=MY_ACCOUNT_UUID &account-secret=MY_ACCOUNT_SECRET &public-short-code=MY_NEW_SHORT_CODE

curl -H 'X-FeedDirectory-Auth: MY_ACCOUNT_UUID:MY_ACCOUNT_SECRET' 'https://feeddirectory.org/api/1.0/Account/ShortCode/Change?public-short-code=MY_NEW_SHORT_CODE'

Example Responses

200
{
  "account-uuid" : 
    MY_ACCOUNT_UUID,
  "public-short-code" : 
    "MY_SHORT_CODE"
}
403
Unable to authenticate
409
Short code already in use

Reset Secret

Resets the secret for an account.

/api/1.0/Account/Secret/Reset
Authentication Required
email Required The email address that was supplied when the account was created

Example Requests

GET /api/1.0/Account/Secret/Reset?account-uuid=MY_ACCOUNT_UUID &account-secret=MY_ACCOUNT_SECRET &email=MY_EMAIL_ADDRESS

curl -H 'X-FeedDirectory-Auth: MY_ACCOUNT_UUID:MY_ACCOUNT_SECRET' 'https://feeddirectory.org/api/1.0/Account/Secret/Reset?email=MY_EMAIL_ADDRESS'

Example Responses

200
{
  "account-uuid" : 
    "MY_ACCOUNT_UUID",
  "account-secret" : 
    "MY_ACCOUNT_SECRET",
  "public-short-code" : 
    "MY_SHORT_CODE"
}
The new account-secret should be retained for subsequent API calls. This is the only time these will be issued.
403
Unable to authenticate
403
Email does not match this account

Activate Account

Request the activation of an account that's previously been deactivated. This can also be used to retrieve the authentication credentials for an account. New credentials are emailed to the account holder.

/api/1.0/Account/Activate
email Required The email address that was supplied when the account was created

Example Requests

GET /api/1.0/Account/Activate?email=MY_EMAIL_ADDRESS

curl 'https://feeddirectory.org/api/1.0/Account/Activate?email=MY_EMAIL_ADDRESS'

Example Responses

200
{
  "activate-email-uuid" : 
    "UNIQUE_EMAIL_REFERENCE",
}
A unique reference to an email that has been sent to the account holder with a new set of credentials. Useful for debugging problems.
404
Account not found

Deactivate Account

Deactivate an account, making it inaccessisble.

/api/1.0/Account/Deactivate
Authentication Required
email Required The email address that was supplied when the account was created

Example Requests

GET /api/1.0/Account/Deactivate?account-uuid=MY_ACCOUNT_UUID &account-secret=MY_ACCOUNT_SECRET &email=MY_EMAIL_ADDRESS

curl -H 'X-FeedDirectory-Auth: MY_ACCOUNT_UUID:MY_ACCOUNT_SECRET' 'https://feeddirectory.org/api/1.0/Account/Deactivate?email=MY_EMAIL_ADDRESS'

Example Responses

200
{
  "goodbye" : true
}
403
Unable to authenticate
403
Email does not match this account

Change Email

Change the email address that's associated with an account.

/api/1.0/Account/Email/Change
Authentication Required
email Required The email address that was supplied when the account was created
new-email Required The new email address that should be associated with the account

Example Requests

GET /api/1.0/Account/Email/Change?account-uuid=MY_ACCOUNT_UUID &account-secret=MY_ACCOUNT_SECRET &email=MY_EMAIL_ADDRESS &new-email=MY_NEW_EMAIL_ADDRESS

curl -H 'X-FeedDirectory-Auth: MY_ACCOUNT_UUID:MY_ACCOUNT_SECRET' 'https://feeddirectory.org/api/1.0/Account/Email/Change?email=MY_EMAIL_ADDRESS &new-email=MY_NEW_EMAIL_ADDRESS'

Example Responses

200
{
  "account-uuid" : 
    "MY_ACCOUNT_UUID"
}
403
Unable to authenticate
403
Email does not match this account
409
Email address already in use
400
Not a valid email address

Publish

Publish a new RSS feed for an account

/api/1.0/Publish
Authentication Required
url Required The URL of an RSS feed that the account is publishing

Example Requests

GET /api/1.0/Publish?account-uuid=MY_ACCOUNT_UUID &account-secret=MY_ACCOUNT_SECRET &url=MY_RSS_FEED

curl -H 'X-FeedDirectory-Auth: MY_ACCOUNT_UUID:MY_ACCOUNT_SECRET' 'https://feeddirectory.org/api/1.0/Publish?url=MY_RSS_FEED'

Example Responses

200
{
  "published-uuid" : 
    "a unique reference to the published item"
}
Useful for debugging problems.
403
Unable to authenticate
400
The URL doesn't seem to be valid

Unpublish

Unpublish an RSS feed from an account

/api/1.0/Unpublish
Authentication Required
url Required The URL of an RSS feed that the account want to remove from the published list

Example Requests

GET /api/1.0/Unpublish?account-uuid=MY_ACCOUNT_UUID &account-secret=MY_ACCOUNT_SECRET &url=MY_RSS_FEED

curl -H 'X-FeedDirectory-Auth: MY_ACCOUNT_UUID:MY_ACCOUNT_SECRET' 'https://feeddirectory.org/api/1.0/Unpublish?url=MY_RSS_FEED'

Example Responses

200
{  }
403
Unable to authenticate
404
The URL is not being published

Subscribe

Subscribe a new RSS feed for an account

/api/1.0/Subscribe
Authentication Required
url Required The URL of an RSS feed that the account is subscribing to

Example Requests

GET /api/1.0/Subscribe?account-uuid=MY_ACCOUNT_UUID &account-secret=MY_ACCOUNT_SECRET &url=ANY_RSS_FEED

curl -H 'X-FeedDirectory-Auth: MY_ACCOUNT_UUID:MY_ACCOUNT_SECRET' 'https://feeddirectory.org/api/1.0/Subscribe?url=ANY_RSS_FEED'

Example Responses

200
{
  "subscribed-uuid" : 
    "a unique reference to the subscribed item"
}
Useful for debugging problems.
403
Unable to authenticate
400
The URL doesn't seem to be valid

Unsubscribe

Unsubscribe an RSS feed from an account

/api/1.0/Unsubscribe
Authentication Required
url Required The URL of an RSS feed that the account want to remove from the subscribed list

Example Requests

GET /api/1.0/Unsubscribe?account-uuid=MY_ACCOUNT_UUID &account-secret=MY_ACCOUNT_SECRET &url=ANY_RSS_FEED

curl -H 'X-FeedDirectory-Auth: MY_ACCOUNT_UUID:MY_ACCOUNT_SECRET' 'https://feeddirectory.org/api/1.0/Unsubscribe?url=ANY_RSS_FEED'

Example Responses

200
{  }
403
Unable to authenticate
404
The URL is not being published

Set Episode Position

Store position information relating to an episode or entry of an RSS feed

/api/1.0/Episode/Position/Set
Authentication Required
url Required The url of an existing subscription
episode Required A unique reference to the episode or item. This could be the GUID item from the RSS feed. Can be up to 1024 characters.
position Required An integer number that represents a position in the episode. For audio this could be a number of seconds, or for text it could be a paragraph number.
completed Optional True or false (yes or no) to mark that this episide has been completed.
hidden Optional True or false (yes or no) to mark that this episide should be hidden.

Example Requests

GET /api/1.0/Episode/Position/Set?account-uuid=MY_ACCOUNT_UUID &account-secret=MY_ACCOUNT_SECRET &url=SUBSCRIBED_RSS_FEED &episode=UNIQUE_EPISODE_REF &position=420&completed=false&hidden=false

curl -H 'X-FeedDirectory-Auth: MY_ACCOUNT_UUID:MY_ACCOUNT_SECRET' 'https://feeddirectory.org/api/1.0/Episode/Position/Set?url=SUBSCRIBED_RSS_FEED &episode=UNIQUE_EPISODE_REF &position=420&completed=false&hidden=false'

Example Responses

200
{
  "episode" :
    "UNIQUE_EPISODE_REF",
  "position" : 420,
  "subscription-uuid" :
    "a unique reference to the subscribed item"
}
      
403
Unable to authenticate
404
No subscription to URL
400
Invalid episode identifier
400
Invalid position value

Get Episode Position

Retrieve position information relating to an episode or entry of an RSS feed

/api/1.0/Episode/Position/Get
Authentication Required
url Required The url of an existing subscription
episode Required A unique reference to the episode or item. This could be the GUID item from the RSS feed. Can be up to 1024 characters.

Example Requests

GET /api/1.0/Episode/Position/Get?account-uuid=MY_ACCOUNT_UUID&account-secret=MY_ACCOUNT_SECRET &url=SUBSCRIBED_RSS_FEED &episode=UNIQUE_EPISODE_REF

curl -H 'X-FeedDirectory-Auth: MY_ACCOUNT_UUID:MY_ACCOUNT_SECRET' 'https://feeddirectory.org/api/1.0/Episode/Position/Get?url=SUBSCRIBED_RSS_FEED &episode=UNIQUE_EPISODE_REF'

Example Responses

200
{
  "episode" : 
    "UNIQUE_EPISODE_REF",
  "position" : 420,
  "completed" : false,
  "hidden" : false,
  "subscription-uuid" : 
    "a unique reference to the subscribed item",
  "last-updated" :
  {
    "epoch-millis" : 1612205256462,
    "timestamp" : "2021-02-01T18:47:36.462+00:00"
  }
}
      
403
Unable to authenticate
404
No subscription to URL
400
Invalid episode identifier

Get All Episode Positions

Retrieve position information for all episodes that have had a position recorded.

/api/1.0/Episode/Position/All
Authentication Required
lookback-seconds Optional The number of seconds from the current time to look back for episode markers that have been updated
max-episodes Optional The amount of episodes to return for the API call. By default up to 10000 episode records will be returned in reverse-chronological order based upon the last time the episode position was updated.

Example Requests

GET /api/1.0/Episode/Position/All?account-uuid=MY_ACCOUNT_UUID&account-secret=MY_ACCOUNT_SECRET &lookback=86400

curl -H 'X-FeedDirectory-Auth: MY_ACCOUNT_UUID:MY_ACCOUNT_SECRET' 'https://feeddirectory.org/api/1.0/Episode/Position/All?max-episodes=1000'

Example Responses

200
{
  "episodes" : [
    {
      "url" : 
        "URL_OF_SUBSCRIBED_RSS_FEED_1"
      "episode" : 
        "UNIQUE_EPISODE_REF1",
      "position" : 8873,
      "completed" : true,
      "hidden" : false,
      "last-updated" :
        {
          "epoch-millis" : 1613839485915,
          "timestamp" : "2021-02-20T16:44:45.915421+00:00"
        }
    },
    {
      "url" : 
        "URL_OF_SUBSCRIBED_RSS_FEED_2"      
      "episode" : 
        "UNIQUE_EPISODE_REF2",
      "position" : 420,
      "completed" : false,
      "hidden" : false,
      "last-updated" :
        {
          "epoch-millis" : 1612205256462,
          "timestamp" : "2021-02-01T18:47:36.462+00:00"
        }
    }
  ]
}

      
403
Unable to authenticate

Follow

Follow another account

/api/1.0/Follow
Authentication Required
public-short-code Required The short code of the account that is to be followed

Example Requests

GET /api/1.0/Follow?account-uuid=MY_ACCOUNT_UUID &account-secret=MY_ACCOUNT_SECRET &public-short-code=SOMEBODYS_SHORT_CODE

curl -H 'X-FeedDirectory-Auth: MY_ACCOUNT_UUID:MY_ACCOUNT_SECRET' 'https://feeddirectory.org/api/1.0/Follow?url=public-short-code=SOMEBODYS_SHORT_CODE'

Example Responses

200
{
  "follow-uuid" : 
    "a unique reference to the follow"
        }
Useful for debugging problems.
403
Unable to authenticate
404
The short code doesn't is not valid

Unfollow

Unfollow another account

/api/1.0/Unfollow
Authentication Required
public-short-code Required The short code of the account that is to be unfollowed

Example Requests

GET /api/1.0/Unfollow?account-uuid=MY_ACCOUNT_UUID &account-secret=MY_ACCOUNT_SECRET &public-short-code=SOMEBODYS_SHORT_CODE

curl -H 'X-FeedDirectory-Auth: MY_ACCOUNT_UUID:MY_ACCOUNT_SECRET' 'https://feeddirectory.org/api/1.0/Unfollow?url=public-short-code=SOMEBODYS_SHORT_CODE'

Example Responses

200
{  }
403
Unable to authenticate
404
The account is not following this short code

Feed

Get the RSS feeds for an account.

/api/1.0/Feed
Authentication Optional
public-short-code Optional
email Optional

Example Requests

GET /api/1.0/Feed?account-uuid=MY_ACCOUNT_UUID &account-secret=MY_ACCOUNT_SECRET

GET /api/1.0/Feed?public-short-code=SOMEBODYS_SHORT_CODE

GET /api/1.0/Feed?email=SOMEBODYS_EMAIL_ADDRESS

curl -H 'X-FeedDirectory-Auth: MY_ACCOUNT_UUID:MY_ACCOUNT_SECRET' 'https://feeddirectory.org/api/1.0/Feed'

curl 'https://feeddirectory.org/api/1.0/Feed?public-short-code=SOMEBODYS_SHORT_CODE'

curl 'https://feeddirectory.org/api/1.0/Feed?email=SOMEBODYS_EMAIL_ADDRESS'

Example Responses

200
{
  "public-short-code" : 
    SHORT_CODE_FOR_ACCOUNT,
  "published" : [
    {
      "url" : 
        "URL_OF_PUBLISHED_RSS_FEED_1"
    },
    {
      "url" : 
        "URL_OF_PUBLISHED_RSS_FEED_2"
    }
  ],
  "subscribed" : [
    {
      "url" : 
        "URL_OF_SUBSCRIBED_RSS_FEED_1"
    },
    {
      "url" : 
        "URL_OF_SUBSCRIBED_RSS_FEED_2"
    },
    {
      "url" : 
        "URL_OF_SUBSCRIBED_RSS_FEED_3"
    }
  ]
}
        
404
Cannot locate the account

Who

Get a list of accounts that publish or subscribe a specific URL.

/api/1.0/Who
Authentication Required
url Required The url that should be searched for

Example Requests

GET /api/1.0/Who?account-uuid=MY_ACCOUNT_UUID &account-secret=MY_ACCOUNT_SECRET &url=ANY_RSS_FEED

curl -H 'X-FeedDirectory-Auth: MY_ACCOUNT_UUID:MY_ACCOUNT_SECRET' 'https://feeddirectory.org/api/1.0/Who?url=ANY_RSS_FEED'

Example Responses

200
{
  "publisher-short-codes" : [
    "ACCOUNT_SHORT_CODE_1",
    "ACCOUNT_SHORT_CODE_2"
  ],
  "subscriber-short-codes" : [
    "ACCOUNT_SHORT_CODE_3",
    "ACCOUNT_SHORT_CODE_4",
    "ACCOUNT_SHORT_CODE_5"
  ]
}
      
403
Unable to authenticate

Following

Get a list of other accounts that are followed.

/api/1.0/Following
Authentication Optional
public-short-code Optional
email Optional

Example Requests

GET /api/1.0/Following?account-uuid=MY_ACCOUNT_UUID &account-secret=MY_ACCOUNT_SECRET

GET /api/1.0/Following?public-short-code=SOMEBODYS_SHORT_CODE

GET /api/1.0/Following?email=SOMEBODYS_EMAIL_ADDRESS

curl -H 'X-FeedDirectory-Auth: MY_ACCOUNT_UUID:MY_ACCOUNT_SECRET' 'https://feeddirectory.org/api/1.0/Following'

curl 'https://feeddirectory.org/api/1.0/Following?public-short-code=SOMEBODYS_SHORT_CODE'

curl 'https://feeddirectory.org/api/1.0/Following?email=SOMEBODYS_EMAIL_ADDRESS'

Example Responses

200
{
  "following" : [
    {
      "public-short-code" : 
        "ACCOUNT_SHORT_CODE_1"
    },
    {
      "public-short-code" : 
        "ACCOUNT_SHORT_CODE_2"
    }
  ]
}
        
403
Unable to authenticate

Set an account permission switch

Set a permission switch against an account.

/api/1.0/Permission/Account/Set
Authentication Required
switch Required Valid values are: is-discoverable, followers-require-authorisation
value Required true or false

Example Requests

GET /api/1.0/Permission/Account/Set?account-uuid=MY_ACCOUNT_UUID &account-secret=MY_ACCOUNT_SECRET &switch=is-discoverable &value=false

curl -H 'X-FeedDirectory-Auth: MY_ACCOUNT_UUID:MY_ACCOUNT_SECRET' 'https://feeddirectory.org/api/1.0/Permission/Account/Set?switch=is-discoverable &value=false'

Example Responses

200
{
  "permission" : 
    {
      "is-discoverable" : true
    }
}
        
403
Unable to authenticate
400
Invalid switch name
400
Invalid switch value

Get an account permission switch

Get a permission switch against an account.

/api/1.0/Permission/Account/Get
Authentication Required
switch Required Valid values are: is-discoverable, followers-require-authorisation

Example Requests

GET /api/1.0/Permission/Account/Get?account-uuid=MY_ACCOUNT_UUID &account-secret=MY_ACCOUNT_SECRET &switch=is-discoverable

curl -H 'X-FeedDirectory-Auth: MY_ACCOUNT_UUID:MY_ACCOUNT_SECRET' 'https://feeddirectory.org/api/1.0/Permission/Account/Get?switch=is-discoverable'

Example Responses

200
{
  "permission" : 
    {
      "is-discoverable" : true
    }
}
        
403
Unable to authenticate
400
Invalid switch name

Set a subscription permission switch

Set a permission switch against a subscription.

/api/1.0/Permission/Subscription/Set
Authentication Required
url Required The URL of a subscribed item
switch Required Valid values are: private, follower-only
value Required true or false

Example Requests

GET /api/1.0/Permission/Subscription/Set?account-uuid=MY_ACCOUNT_UUID &account-secret=MY_ACCOUNT_SECRET &switch=private &value=false &url=URL_OF_SUBSCRIBED_RSS_FEED_1

curl -H 'X-FeedDirectory-Auth: MY_ACCOUNT_UUID:MY_ACCOUNT_SECRET' 'https://feeddirectory.org/api/1.0/Permission/Subscription/Set?switch=private &value=false &url=URL_OF_SUBSCRIBED_RSS_FEED_1'

Example Responses

200
{
  "permission" : 
    {
      "private" : true
    }
}
        
403
Unable to authenticate
404
Not a valid subscription
400
Invalid switch name
400
Invalid switch value

Get a subscription permission switch

Get a permission switch against a subscription.

/api/1.0/Permission/Subscription/Get
Authentication Required
url Required The URL of a subscribed item
switch Required Valid values are: private, follower-only

Example Requests

GET /api/1.0/Permission/Subscription/Get?account-uuid=MY_ACCOUNT_UUID &account-secret=MY_ACCOUNT_SECRET &switch=private &url=URL_OF_SUBSCRIBED_RSS_FEED_1

curl -H 'X-FeedDirectory-Auth: MY_ACCOUNT_UUID:MY_ACCOUNT_SECRET' 'https://feeddirectory.org/api/1.0/Permission/Subscription/Get?switch=private &url=URL_OF_SUBSCRIBED_RSS_FEED_1'

Example Responses

200
{
  "permission" : 
    {
      "is-discoverable" : true
    }
}
        
403
Unable to authenticate
404
Not a valid subscription
400
Invalid switch name

Set a published item permission switch

Set a permission switch against a published item.

/api/1.0/Permission/Published/Set
Authentication Required
url Required The URL of a published item
switch Required Valid values are: private, follower-only
value Required true or false

Example Requests

GET /api/1.0/Permission/Published/Set?account-uuid=MY_ACCOUNT_UUID &account-secret=MY_ACCOUNT_SECRET &switch=private &value=false &url=URL_OF_PUBLISHED_RSS_FEED_1

curl -H 'X-FeedDirectory-Auth: MY_ACCOUNT_UUID:MY_ACCOUNT_SECRET' 'https://feeddirectory.org/api/1.0/Permission/Published/Set?switch=private &value=false &url=URL_OF_PUBLISHED_RSS_FEED_1'

Example Responses

200
{
  "permission" : 
    {
      "private" : true
    }
}
        
403
Unable to authenticate
404
Not a valid published item
400
Invalid switch name
400
Invalid switch value

Get a published item permission switch

Get a permission switch against a published item.

/api/1.0/Permission/Published/Get
Authentication Required
url Required The URL of a published item
switch Required Valid values are: private, follower-only

Example Requests

GET /api/1.0/Permission/Published/Get?account-uuid=MY_ACCOUNT_UUID &account-secret=MY_ACCOUNT_SECRET &switch=private &url=URL_OF_PUBLISHED_RSS_FEED_1

curl -H 'X-FeedDirectory-Auth: MY_ACCOUNT_UUID:MY_ACCOUNT_SECRET' 'https://feeddirectory.org/api/1.0/Permission/Published/Get?switch=private &url=URL_OF_PUBLISHED_RSS_FEED_1'

Example Responses

200
{
  "permission" : 
    {
      "is-discoverable" : true
    }
}
        
403
Unable to authenticate
404
Not a valid published item
400
Invalid switch name

Set a follow item permission switch

Set a permission switch against a followed account.

/api/1.0/Permission/Follow/Set
Authentication Required
public-short-code Required The short code of the followed account
switch Required Valid values are: private, follower-only
value Required true or false

Example Requests

GET /api/1.0/Permission/Follow/Set?account-uuid=MY_ACCOUNT_UUID &account-secret=MY_ACCOUNT_SECRET &switch=private &value=false &public-short-code=SOMEBODYS_SHORT_CODE

curl -H 'X-FeedDirectory-Auth: MY_ACCOUNT_UUID:MY_ACCOUNT_SECRET' 'https://feeddirectory.org/api/1.0/Permission/Follow/Set?switch=private &value=false &public-short-code=SOMEBODYS_SHORT_CODE'

Example Responses

200
{
  "permission" : 
    {
      "private" : true
    }
}
        
403
Unable to authenticate
404
Not a valid follow
400
Invalid switch name
400
Invalid switch value

Get a follow item permission switch

Get a permission switch against a followed account.

/api/1.0/Permission/Follow/Get
Authentication Required
public-short-code Required The short code of the followed account
switch Required Valid values are: private, follower-only

Example Requests

GET /api/1.0/Permission/Follow/Get?account-uuid=MY_ACCOUNT_UUID &account-secret=MY_ACCOUNT_SECRET &switch=private &public-short-code=SOMEBODYS_SHORT_CODE

curl -H 'X-FeedDirectory-Auth: MY_ACCOUNT_UUID:MY_ACCOUNT_SECRET' 'https://feeddirectory.org/api/1.0/Permission/Follow/Get?switch=private &public-short-code=SOMEBODYS_SHORT_CODE'

Example Responses

200
{
  "permission" : 
    {
      "private" : true
    }
}
        
403
Unable to authenticate
404
Not a valid follow
400
Invalid switch name

Get unauthorised follows

Get a list of follow requests (for this account) that are not authorised.

/api/1.0/Permission/Follow/Unauthorised
Authentication Required

Example Requests

GET /api/1.0/Permission/Follow/Unauthorised?account-uuid=MY_ACCOUNT_UUID &account-secret=MY_ACCOUNT_SECRET

curl -H 'X-FeedDirectory-Auth: MY_ACCOUNT_UUID:MY_ACCOUNT_SECRET' 'https://feeddirectory.org/api/1.0/Permission/Follow/Unauthorised'

Example Responses

200
{
  "unauthorised" : [
    {
      "public-short-code" : "SOMEBODYS_SHORT_CODE",
      "last-updated" :
        {
          "epoch-millis" : 1613928386084,
          "timestamp" : "2021-02-21T17:26:26.084814+00"
        }
    },
    {
      "public-short-code" : "ANOTHER_SHORT_CODE",
      "last-updated" :
        {
          "epoch-millis" : 1613928456031,
          "timestamp" : "2021-02-21T17:27:36.031654+00"
        }
    }    
  ]
}
        
403
Unable to authenticate

Authorise a follow request

Authorise a request to follow an account

/api/1.0/Permission/Follow/Authorise
Authentication Required
public-short-code Required The short code of the followed account

Example Requests

GET /api/1.0/Permission/Follow/Authorise?account-uuid=MY_ACCOUNT_UUID &account-secret=MY_ACCOUNT_SECRET &public-short-code=SOMEBODYS_SHORT_CODE

curl -H 'X-FeedDirectory-Auth: MY_ACCOUNT_UUID:MY_ACCOUNT_SECRET' 'https://feeddirectory.org/api/1.0/Permission/Follow/Authorise?public-short-code=SOMEBODYS_SHORT_CODE'

Example Responses

200
{
  "authorised" : true
}
        
403
Unable to authenticate
404
Not a valid follow

Deauthorise a follow request

Deauthorise a request to follow an account

/api/1.0/Permission/Follow/Deauthorise
Authentication Required
public-short-code Required The short code of the followed account

Example Requests

GET /api/1.0/Permission/Follow/Deauthorise?account-uuid=MY_ACCOUNT_UUID &account-secret=MY_ACCOUNT_SECRET &public-short-code=SOMEBODYS_SHORT_CODE

curl -H 'X-FeedDirectory-Auth: MY_ACCOUNT_UUID:MY_ACCOUNT_SECRET' 'https://feeddirectory.org/api/1.0/Permission/Follow/Deauthorise?public-short-code=SOMEBODYS_SHORT_CODE'

Example Responses

200
{
  "authorised" : false
}
        
403
Unable to authenticate
404
Not a valid follow

Create a comment

Create a comment against an episode at a specified position. The account MUST be subscribed to the URL in order to comment against an episode.

/api/1.0/Comment/Create
Authentication Required
url Required The url of an existing subscription
episode Required A unique reference to the episode or item. This could be the GUID item from the RSS feed. Can be up to 1024 characters.
position Required An integer number that represents a position in the episode that the comment is related to. For audio this could be a number of seconds, or for text it could be a paragraph number.
comment Required The text of the comment that will be created. This should be less than 1024 bytes in size.
metadata Optional A small bit of metadata that will be associated with the comment. This should be in JSON format and less than 1024 bytes in size.

Example Requests

GET /api/1.0/Comment/Create?account-uuid=MY_ACCOUNT_UUID &account-secret=MY_ACCOUNT_SECRET &url= &episode= &position= &comment=

curl -H 'X-FeedDirectory-Auth: MY_ACCOUNT_UUID:MY_ACCOUNT_SECRET' '/api/1.0/Comment/Create?&url= &episode= &position= &comment='

Example Responses

200
{
  "comment" : {
      "comment-uuid" : "UNIQUE_COMMENT_ID",
      "url" : 
      "episode" :
      "position" :
      "text" :
      "public-short-code" : "YOUR_SHORT_CODE",
      "metadata" : null,
      "created" :
        {
          "epoch-millis" : 1613928386084,
          "timestamp" : "2021-02-21T17:26:26.084814+00"
        }
  }
}
        
403
Unable to authenticate
404
Subscription not found
400
Invalid data

Read comments

Read all of the comments against an episode

/api/1.0/Comment/Read
Authentication Required
url Required The url of an existing subscription
episode Required A unique reference to the episode or item. This could be the GUID item from the RSS feed. Can be up to 1024 characters.
lookback-seconds Optional The number of seconds from the current time to look back for comments that have been created or a vote was counted for it.
max-comments Optional The amount of comments to return for the API call. By default up to 10000 comments will be returned in reverse-chronological order based upon the time the comment was created or a vote was counted for it.

Example Requests

GET /api/1.0/Comment/Read?account-uuid=MY_ACCOUNT_UUID &account-secret=MY_ACCOUNT_SECRET &url= &episode=

curl -H 'X-FeedDirectory-Auth: MY_ACCOUNT_UUID:MY_ACCOUNT_SECRET' '/api/1.0/Comment/Read?&url= &episode= '

Example Responses

200
{
  "comments" : [
    {
      "comment-uuid" : "UNIQUE_COMMENT_ID",
      "position" : 420,
      "text" : "a very nice comment"
      "public-short-code" : "A_PUBLIC_SHORT_CODE",
      "created" :
        {
          "epoch-millis" : 1613928386084,
          "timestamp" : "2021-02-21T17:26:26.084814+00"
        },
      "last-updated" :
        {
          "epoch-millis" : 1613928386084,
          "timestamp" : "2021-02-21T17:26:26.084814+00"
        },
      "metadata" : null,
      "votes" : {
        "score" : 104,
        "abuse" : -10,
        "spam" : -20
      }
    },
    {
      "comment-uuid" : "UNIQUE_COMMENT_ID",
      "position" : 1337,
      "text" : "a really abusing and slightly spammy comment"
      "public-short-code" : "A_PUBLIC_SHORT_CODE",
      "created" :
        {
          "epoch-millis" : 1613928386084,
          "timestamp" : "2021-02-21T17:26:26.084814+00"
        },
      "last-updated" :
        {
          "epoch-millis" : 1613928386084,
          "timestamp" : "2021-02-21T17:26:26.084814+00"
        },
      "metadata" : { "foo" : "bar" },
      "votes" : {
        "score" : -9,
        "abuse" : 5,
        "spam" : 1
      }
    }
  ]
}
        
403
Unable to authenticate

Read my comments

Read all of the comments submitted from the account

/api/1.0/Comment/My
Authentication Required
lookback-seconds Optional The number of seconds from the current time to look back for comments that have been created or a vote was counted for it.
max-comments Optional The amount of comments to return for the API call. By default up to 10000 comments will be returned in reverse-chronological order based upon the time the comment was created or a vote was counted for it.

Example Requests

GET /api/1.0/Comment/My?account-uuid=MY_ACCOUNT_UUID &account-secret=MY_ACCOUNT_SECRET

curl -H 'X-FeedDirectory-Auth: MY_ACCOUNT_UUID:MY_ACCOUNT_SECRET' '/api/1.0/Comment/My'

Example Responses

200
{
  "comments" : [
    {
      "url" : "FEED_URL",
      "episode" : "EPISODE_REFERENCE",
      "comment-uuid" : "UNIQUE_COMMENT_ID",
      "position" : 420,
      "text" : "a very nice comment"
      "public-short-code" : "A_PUBLIC_SHORT_CODE",
      "created" :
        {
          "epoch-millis" : 1613928386084,
          "timestamp" : "2021-02-21T17:26:26.084814+00"
        }
      "metadata" : null,
      "votes" : {
        "score" : 104,
        "abuse" : 0,
        "spam" : 0
      }
    },
    {
      "url" : "FEED_URL",
      "episode" : "EPISODE_REFERENCE",
      "comment-uuid" : "UNIQUE_COMMENT_ID",
      "position" : 1337,
      "text" : "a really abusing and slightly spammy comment"
      "public-short-code" : "A_PUBLIC_SHORT_CODE",
      "created" :
        {
          "epoch-millis" : 1613928386084,
          "timestamp" : "2021-02-21T17:26:26.084814+00"
        }
      "metadata" : { "foo" : "bar" },
      "votes" : {
        "score" : -9,
        "abuse" : 5,
        "spam" : 1
      }
    }
  ]
}
        
403
Unable to authenticate

Vote on a comment

Vote on a comment or mark it as abusive or spam

/api/1.0/Comment/Vote
Authentication Required
comment-uuid Required The uuid of the comment
vote Optional Either +1 or -1 to either vote up or down, or 0 to be neutral.
abuse Optional Either +1 to mark the comment as abusive or -1 mark it as not abusive, or 0 to be neutral.
spam Optional Either +1 to mark the comment as spam or -1 mark it as not spam, or 0 to be neutral.

Example Requests

GET /api/1.0/Comment/Vote?account-uuid=MY_ACCOUNT_UUID &account-secret=MY_ACCOUNT_SECRET &comment-uuid= &vote=1

curl -H 'X-FeedDirectory-Auth: MY_ACCOUNT_UUID:MY_ACCOUNT_SECRET' '/api/1.0/Comment/Vote?&comment-uuid= &vote=-1 '

Example Responses

200
{
  "vote" : {
      "comment-uuid" : "UNIQUE_COMMENT_ID",
      "vote-uuid" : "UNIQUE_VOTE_ID",
      "vote" : 1,
      "abuse" : 0,
      "spam" : 0,
      "created" :
        {
          "epoch-millis" : 1613928386084,
          "timestamp" : "2021-02-21T17:26:26.084814+00"
        },
      "last-updated" :
        {
          "epoch-millis" : 1613928386084,
          "timestamp" : "2021-02-21T17:26:26.084814+00"
        }
    }
}
        
403
Unable to authenticate
404
Comment not found

Support

It is our intention to always keep this service free of charge for application developers and end users. We're designed to run lean here so do not have many overheads, but if you are able to give a little value back if you get value from the service, it would really be appreciated.
Just the price of a cup of coffee each month would make a huge difference to us. We drink a lot of coffee! ;-)

Contact

Our founder and lead developer can be found at podcastindex.social, contact us through the Development Blog, or send us an email info@feeddirectory.org



feeddirectory.org hosting provided by

Watchfront

Buy stuff from them, they're nice people.

Copyright ©2021 feeddirectory.org