API Docs | podcastsocial.org

The podcastsocial.org API

Overview

The API for podcastsocial.org is meant to follow the quirks and conventions of the PodcastIndex.org API, to be familiar to developers already using that API, and since the goal is to eventually get these two calls added to the PodcastIndex.org API itself.

Authentication Details

Use the same authentication style you use to authenticate to PodcastIndex.org, but use your podcastsocial.org API Key + Secret instead.

Email xxxx%podcastsocial.org to receive a API Key + Secret for all https://api.podcastsocial.org calls.

GET /socialinteracts/byepisodeid

Finds all known social interaction items for a given podcast episode.

Returns any <podcast:socialInteract> tag information from the feed item itself ("source": "feed") as well as any previously created volunteer root post items ("source": "volunteer").

If there are no existing items, you may still be able to create one if you need one available to serve as a target of your app's reply comment.

Example:

https://api.podcastsocial.org/api/1.0/socialinteracts/byepisodeid?id=16795090&pretty

Request

Query-string Parameters

id

number(required) The PodcastIndex episode ID

pretty

boolean If present, indent the output to help with debugging.

Response

Schema Example 1 Example 2 Example 3

{
status: enum: true | false
items: [{: List of social interact items matching request
episodeId: number: The PodcastIndex episode ID
sourceType: enum: feed | volunteer
source: URL: (sourceType: feed) Feed URL | (sourceType: volunteer) URL of volunteer index service
platform: string: The platform id, as defined in the SocialInteract tag
protocol: string: The protocol, as defined in the SocialInteract tag
accountId: string: The accountId, as defined in the SocialInteract tag
pubDate: string: The pubDate, as defined in the SocialInteract tag
priority: string: The priority, as defined in the SocialInteract tag
content: string: The URL to the episode's root comment, as defined in the SocialInteract tag
}]
count: integer: Number of items returned in the request
query: string: Query used in the request
description: string: Description of the response
}

{
  "status": "true",
  "items": [
    {
      "episodeId": 16795090,
      "sourceType": "volunteer",
      "source": "https://podcastsocial.org",
      "platform": "mastodon",
      "protocol": "activitypub",
      "accountId": "@podcastsocial@comments.podcastsocial.org",
      "pubDate": "2022-02-15T17:06:39.896Z",
      "content": "https://comments.podcastsocial.org/users/podcastsocial/statuses/107803102400740135"
    }
  ],
  "count": 1,
  "query": "episodeId=16795090",
  "description": "Found matching episode."
}

{
  "status": "true",
  "items": [
    {
      "episodeId": 6681036776,
      "sourceType": "feed",
      "source": "http://mp3s.nashownotes.com/pc20rss.xml",
      "platform": "activitypub",
      "content": "https://podcastindex.social/web/@dave/107780731968782368"
    }
  ],
  "count": 1,
  "query": "episodeId=6681036776",
  "description": "Found matching episode."
}

{
  "status": "true",
  "items": [
    {
      "episodeId": 6663293893,
      "sourceType": "feed",
      "source": "https://engineered.network/causality/feed/index.xml",
      "platform": "mastodon",
      "protocol": "activitypub",
      "accountId": "@chidgey@engineered.space",
      "pubDate": "2021-11-09T20:31:10Z",
      "priority": "1",
      "content": "https://engineered.space/notice/ADEfVgscQ7oXygKqA4"
    },
    {
      "episodeId": 6663293893,
      "sourceType": "feed",
      "source": "https://engineered.network/causality/feed/index.xml",
      "platform": "twitter",
      "protocol": "twitter",
      "accountId": "@Engineered_Net",
      "pubDate": "2021-11-09T20:31:10Z",
      "priority": "2",
      "content": "https://twitter.com/Engineered_Net/status/1458171040715051010"
    },
    {
      "episodeId": 6663293893,
      "sourceType": "feed",
      "source": "https://engineered.network/causality/feed/index.xml",
      "platform": "facebook",
      "protocol": "facebook",
      "accountId": "EngineeredNetwork",
      "pubDate": "2021-11-09T20:31:10Z",
      "priority": "3",
      "content": "https://www.facebook.com/engineerednetwork/posts/752153156186128"
    }
  ],
  "count": 3,
  "query": "episodeId=6663293893",
  "description": "Found matching episode."
}

GET | POST /socialinteracts/add/byepisodeid

Creates a new social interaction item for a given podcast episode by posting a new root comment to a volunteer ActivityPub server.

Returns the social interact information of the newly-created volunteer root post item, or the existing social interact information if it already exists.

Please only call this if you have a reply to post afterward, there is no value in creating a root post that will have no replies.

This call will fail if the episode specified no longer exists in the current feed.

If there are existing social interact items (either in the feed, or existing volunteer items) for the episode, they will be returned - no new volunteer item will be created.