Libsyn API Reference

Post

Handles Libsyn posts (episodes).

  • Search Posts - Returns a list of episodes (posts) by specified search parameters.
  • Retrieve Post - Returns an individual Libsyn episode (post) by filters.
  • Create Post - Create a new Libsyn post (episode).
  • Update Post - Update a Libsyn post (episode).
  • Delete Post - Permanently delete a individual Libsyn episode (post).

Fields

Field Type Description
id integer Represents an individual post (also known as episodes).
item_title string An individual post title.
show_id string Represents an individual show. Must be unique show identifier (numerical) or slug (text).
primary_content object Represents the media file attached to the episode. See the Primary Content section for further explanation of primary content properties and methods of uploading to episodes.
item_slug string Unique text identifier for post.
item_subtitle string Post subtitle.
is_draft boolean Represents if the post is currently not published. {"true", "false"}
qc_state string Quality Control Management: {"none", "awaiting", "approved", "declined", null}
itunes_explicit string Represents iTunes explicit content {"no", "yes", "clean", null}
itunes_episode_number integer iTunes Episode Number
itunes_season_number integer iTunes Season Number
itunes_episode_type string Represents iTunes episode Type {"full", "trailer", "bonus", null}
itunes_episode_summary string iTunes Episode Summary (simliar to Description)
itunes_episode_title string iTunes Episode Title (similar to Title)
itunes_episode_author string iTunes Episode Author
tv_rating string Represents TV Rating {"TV-14", "TV-G", "TV-PG", "TV-Y7", "TV-Y", "TV-MA", null}
tv_subrating string Represents TV Sub Rating {"L", "D", "V", "LS", "S", "VL", "VLD", "LSD", "VLS", "LD", "SD", "VS", "VLSD", "VD", null}
category string Post category.
item_keywords array Keywords associated with the episode.
permalink_type string Post permalink type.
custom_permalink_url string Post custom permalink url.
guid string Post content custom identifier.
allow_advertising string Allow advertising on post.
display_comments string Allow displaying of comments on post.
creation_date string Post creation date.
last_updated string Post last updated date.
premium_state string Post premium state (only applies if premium-enabled in account).
body string Post episode body or description.
requested_body string Post requested body.
extra_rss_tags mixed Extra post rss tags.
release_date string Post release date for all destinations. You may set destination release dates individually by using releases instead. This field must be in "YYYY-mm-dd HH:mm:ss" format. Optional: you may set release_date to "now" which will use the current date/time.
releases array An array of release objects, each one is structured as follows: release_id: (int), item_id: (int), destination_id: (int), release_date: (string), expiration_date: (string), release_state: (string), creation_date: (string), destination_name: (string), destination_type_slug: (string), external_release: (boolean)
expiration_date string Post expiration date (if applicable)
additional_content array Post additional content by the content_ids. Must be structured as example: Array( contentid1, contentid2, contentid3 ) (extra_content will take priority if extra_content_ids and/or extra_content_urls are also set.)
thumbnail file File to upload as thumbnail.
thumbnail_id integer Asset ID of thumbnail to use. (Note: This field will be ignored if "thumbnail" or "thumbnail_url" is present.)
thumbnail_url string URL for thumbnail to import. (Note: This field will be ignored if "thumbnail" is present.)
blog_image file File to upload as blog image.
blog_image_id integer Asset ID of blog to use. (Note: This field will be ignored if "blog_image" or "blog_image_url" is present.)
blog_image_url string URL for blog image to import. (Note: This field will be ignored if "blog_image" is present.)
background_image file File to upload as background image.
background_image_id integer Asset ID of background to use. (Note: This field will be ignored if "background_image" or "background_image_url" is present.)
background_image_url string URL for background image to import. (Note: This field will be ignored if "background_image" is present.)
page_count integer Total number of pages returned in the search request. (Present in the Search Posts endpoint.)
page_size integer Total number of items per page. (Present in the Search Posts endpoint.)
total_items integer Total number of items returned in the search request. (Present in the Search Posts and Retrieve Post endpoints.)

Primary Content

Primary content refers to the media file that is attached to the post. If there is no primary content associated with the post, it is assumed that the episode is text-only.

via GET

Primary content will contain information about the primary content file that is currently set.

via POST

Primary content represents a file and is used to add or replace the primary content of a post.

Fields

Field Type Description
content_id integer Represents an individual media file.
url string URL address of the media file.
secure_url string Secure URL address of the media file.
filename string File name of the media file.
duration integer Length of the media file in seconds.
mime_type string Mime type of the media file.
audio_codec string Audio codec of the media file.
video_codec string Video codec of the media file.

Attaching Primary Content

There are multiple methods available to you for attaching primary content to a post. In each case, there will be a specific field key to use.

  1. primary_content: Use this key to attach a file to be uploaded.
  2. primary_content_id: Use this key to reference the content_id of a media file that you have already uploaded to your Libsyn account. This content must not be already attached to another post. You can reference the Media section of our API documentation for more information on how to retrieve the content_id of a media file.
  3. primary_content_url: Use this key to reference the URL address of where the media file is located. Libsyn will import the media at this address to your Libsyn account and attach it to your post. Be advised this method can only be used for media files outside of Libsyn.

Request
Headers
Header Value
Accept application/json
Specific Search Parameters
Parameters Description
sort In addition to the post results being able to be sorted via their creation_date, they can also be sorted via their item_id.
is_draft Returns results based upon the is_draft status specified in the search request.
premium_state Returns results based upon the premium_state status specified in the search request.

Search Posts

Returns a list of episodes (posts) by specified search parameters.

Request

Send a GET request to the /post endpoint, the show_id search parameter is required:

$ curl https://api.libsyn.com/post?show_id=[:show_id]

-X GET \

-H 'Authorization:Bearer (Your Access Token)'

-H 'Accept: application/json'


Response

On success, your app will receive the following response:


{
 "_links": {
   "self": {
	   "href": "https://api.libsyn.com/post"
   },
   "first": {
	   "href": "https://api.libsyn.com/post?page={page}"
   },
	 "last": {
		"href": "https://api.libsyn.com/post?page={page}"
	 },
   "next": {
	   "href": "https://api.libsyn.com/post?page={page}"
   }
 },
 "_embedded": {
   "item": [
	   {
		  "id": "(int)		- Represents a individual post (also known as episodes).",
		  "item_title": "(string)		- A individual post title.",
		  "show_id": "(string)		- Represents a individual show.  Must be unique show identifier (numerical) or slug (text).",
		  "primary_content": "(object)	- Post primary content_id, url, secure_url, filename, duration, mime_type, audio_codec, video_codec",
		  "item_slug": "(string)	- Post item slug",
		  "item_subtitle": "(string)		- Post subtitle.",
		  "is_draft": "(bool)		- Represents if the post is currently not published. {"true", "false"}",
		  "qc_state": "(string)		- Quality Control Management: {"none", "awaiting", "approved", "declined", null}",
		  "itunes_explicit": "(string)		- Represents iTunes explicit content {"no", "yes", "clean", null}",
		  "itunes_episode_number": "(int)	- iTunes Episode Number",
		  "itunes_season_number": "(int)	- iTunes Season Number",
		  "itunes_episode_type": "(string)	- Represents iTunes episode Type {"full", "trailer", "bonus", null}",
		  "itunes_episode_summary": "(string)	- iTunes Episode Summary (simliar to Description)",
		  "itunes_episode_title": "(string)	- iTunes Episode Title (similar to Title)",
		  "itunes_episode_author": "(string)	- iTunes Episode Author",
		  "tv_rating": "(string)		- Represents TV Rating {null, "TV-14", "TV-G", "TV-PG", "TV-Y7", "TV-Y", "TV-MA", null}",
		  "tv_subrating": "(string)		- Represents TV Sub Rating {null, "L", "D", "V", "LS", "S", "VL", "VLD", "LSD", "VLS", "LD", "SD", "VS", "VLSD", "VD", null}",
		  "category": "(string)		- Post category.",
		  "permalink_type": "(string)		- Post permalink type.",
		  "custom_permalink_url": "(string)		- Post custom permalink url.",
		  "guid": "(string)		- Post content custom identifier.",
		  "allow_advertising": "(string)		- Allow advertising on post.",
		  "display_comments": "(string)		- Allow displaying of comments on post.",
		  "creation_date": "(string)		- Post creation date.",
		  "last_updated": "(string)		- Post last updated date.",
		  "premium_state": "(string)		- Post premium state (only applies if premium-enalbed in account).",
		  "body": "(string)		- Post episode body or description.",
		  "extra_rss_tags": "(mixed)		- Extra post rss tags.",
		  "release_date": "(string)		- Post release date for all destinations.  You may set destination release dates individually by using releases instead.  This field must be in "YYYY-mm-dd HH:mm:ss" format. Optional: you may set release_date to "now" which will use the current date/time."
		  "releases": "(array)		- An array of release objects, each one is structured as follows: release_id: (int), item_id: (int), destination_id: (int), release_date: (string), expiration_date: (string), release_state: (string), creation_date: (string), destination_name: (string), destination_type_slug: (string), external_release: (boolean)",
		  "expiration_date": "(string)		- Post expiration date (if applicable)",
		  "additional_content":"(array)		- Post additional content by the content_ids. Must be structured as example:  Array( contentid1, contentid2, contentid3 ). (extra_content will take priority if extra_content_ids and/or extra_content_urls are also set.)",
		  "thumbnail": "(array)		- Post thumbnail information.",
		  "blog_image": "(array)	- Post blog image information.",
		  "background_image": "(array)	- Post background image information.",
		  "_links": {
			"self": {
 			  "href": "https://api.libsyn.com/post/[:item_id]"
 		    }
	      }
	   }
   ]
 },
 "page_count": "(int)	- Total number of pages returned in the search request.",
 "page_size": "(int)	- Total number of items per page.",
 "total_items": "(int)	- Total number of items returned in the search request."
}
													
Retrieve Post

Returns an individual Libsyn episode (post) by filters.

Request

Send a GET request to the /post/[:item_id] endpoint:

$ curl https://api.libsyn.com/post/[:item_id]

-X GET \

-H 'Authorization:Bearer (Your Access Token)'

-H 'Accept: application/json'


Response

On success, your app will receive the following response:


{
 "_links": {
   "self": {
	   "href": "/post/[:item_id]"
   }
 },
 "_embedded": {
	"post": {
		 "id": "(int)		- Represents a individual post (also known as episodes).",
		 "item_title": "(string)		- A individual post title.",
		 "show_id": "(string)		- Represents a individual show.  Must be unique show identifier (numerical) or slug (text).",
		 "primary_content": "(array)	- Post primary content_id, url, secure_url, filename, duration, mime_type, audio_codec, video_codec",
		 "item_slug": "(string)	- Post item slug",
		 "item_subtitle": "(string)		- Post subtitle.",
		 "is_draft": "(bool)		- Represents if the post is currently not published. {"true", "false"}",
		 "qc_state": "(string)		- Quality Control Management: {"none", "awaiting", "approved", "declined", null}",
		 "itunes_explicit": "(string)		- Represents iTunes explicit content {"no", "yes", "clean", null}",
		 "itunes_episode_number": "(int)	- iTunes Episode Number",
		 "itunes_season_number": "(int)	- iTunes Season Number",
		 "itunes_episode_type": "(string)	- Represents iTunes episode Type {"full", "trailer", "bonus", null}",
		 "itunes_episode_summary": "(string)	- iTunes Episode Summary (simliar to Description)",
		 "itunes_episode_title": "(string)	- iTunes Episode Title (similar to Title)",
		 "itunes_episode_author": "(string)	- iTunes Episode Author",
		 "tv_rating": "(string)		- Represents TV Rating {null, "TV-14", "TV-G", "TV-PG", "TV-Y7", "TV-Y", "TV-MA", null}",
		 "tv_subrating": "(string)		- Represents TV Sub Rating {null, "L", "D", "V", "LS", "S", "VL", "VLD", "LSD", "VLS", "LD", "SD", "VS", "VLSD", "VD", null}",
		 "category": "(string)		- Post category.",
		 "item_keywords": "(array)		- Keywords that are associated with the Post.",
		 "permalink_type": "(string)		- Post permalink type.",
		 "custom_permalink_url": "(string)		- Post custom permalink url.",
		 "guid": "(string)		- Post content custom identifier.",
		 "allow_advertising": "(string)		- Allow advertising on post.",
		 "display_comments": "(string)		- Allow displaying of comments on post.",
		 "creation_date": "(string)		- Post creation date.",
		 "last_updated": "(string)		- Post last updated date.",
		 "premium_state": "(string)		- Post premium state (only applies if premium-enalbed in account).",
		 "body": "(string)		- Post episode body or description.",
		 "requested_body": "(string)		- Post requested body.",
		 "extra_rss_tags": "(mixed)		- Extra post rss tags.",
		 "release_date": "(string)		- Post release date for all destinations.  You may set destination release dates individually by using releases instead.  This field must be in "YYYY-mm-dd HH:mm:ss" format. Optional: you may set release_date to "now" which will use the current date/time.",
		 "releases": "(array)		- An array of release objects, each one is structured as follows: release_id: (int), item_id: (int), destination_id: (int), release_date: (string), expiration_date: (string), release_state: (string), creation_date: (string), destination_name: (string), destination_type_slug: (string), external_release: (boolean)"
		 "expiration_date": "(string)		- Post expiration date (if applicable)",
		 "additional_content":"(array)		- Post additional content by the content_ids. Must be structured as example:  Array( contentid1, contentid2, contentid3 ). (extra_content will take priority if extra_content_ids and/or extra_content_urls are also set.)",
		 "thumbnail": "(array)		- Post thumbnail information.",
		 "blog_image": "(array)	- Post blog image information.",
		 "background_image": "(array)	- Post background image information.",
		 "player_use_thumbnail": (boolean)    - Post player embed code setting to include thumbnail or not (Default to true)",
	}
},
"total_items": "(int)	- The total number of items returned in the search request."
													
Create Post

Create a new Libsyn post (episode).

Request

It is required that the following fields be included in the form data of the body in order to successfully create a new episode:

  • show_id
  • item_title
  • item_slug
  • is_draft
  • release_date

Send a POST request to the /post endpoint:

$ curl https://api.libsyn.com/post

-X POST \

-H 'Authorization:Bearer (Your Access Token)'

-H 'Accept: application/json'


-F 'show_id=[:show_id]'

-F 'item_title=[:item_title]'

-F 'item_slug=[:item_slug]'

-F 'is_draft=[:is_draft]'

-F 'release_date=[:release_date]'


Response

On success, your app will receive the following response:


{
	"status": "(string)		- Represents the status of the post you are attempting to upload.",
	"post": {
		"item_title": "(string)		- A individual post title.",
		"show_id": "(string)		- Represents a individual show.  Must be unique show identifier (numerical) or slug (text).",
		"primary_content": "(array)	- Post primary content_id, url, secure_url, filename, duration, mime_type, audio_codec, video_codec",
		"item_slug": "(string)	- Post item slug",
		"item_subtitle": "(string)		- Post subtitle.",
		"is_draft": "(bool)		- Represents if the post is currently not published. {"true", "false"}",
		"qc_state": "(string)		- Quality Control Management: {"none", "awaiting", "approved", "declined", null}",
		"premium_state": "(string)	- Premium State (Premium Shows only): {"premium", "pay", "free", "auto", null}",
		"itunes_explicit": "(string)		- Represents iTunes explicit content {"no", "yes", "clean", null}",
		"itunes_episode_number": "(int)	- iTunes Episode Number",
		"itunes_season_number": "(int)	- iTunes Season Number",
		"itunes_season_number": "(int)	- iTunes Season Number",
		"itunes_episode_type": "(string)	- Represents iTunes episode Type {"full", "trailer", "bonus", null}",
		"itunes_episode_summary": "(string)	- iTunes Episode Summary (simliar to Description)",
		"itunes_episode_title": "(string)	- iTunes Episode Title (similar to Title)",
		"itunes_episode_author": "(string)	- iTunes Episode Author",
		"update_id3": "(bool)	- Update Primary Content id3 tags with post data (mp3 files only)",
		"tv_rating": "(string)		- Represents TV Rating {null, "TV-14", "TV-G", "TV-PG", "TV-Y7", "TV-Y", "TV-MA", null}",
		"tv_subrating": "(string)		- Represents TV Sub Rating {null, "L", "D", "V", "LS", "S", "VL", "VLD", "LSD", "VLS", "LD", "SD", "VS", "VLSD", "VD", null}",
		"category": "(string)		- Post category.",
		"permalink_type": "(string)		- Post permalink type.",
		"custom_permalink_url": "(string)		- Post custom permalink url.",
		"guid": "(string)		- Post content custom identifier.",
		"allow_advertising": "(string)		- Allow advertising on post.",
		"display_comments": "(string)		- Allow displaying of comments on post.",
		"creation_date": "(string)		- Post creation date.",
		"last_updated": "(string)		- Post last updated date.",
		"premium_state": "(string)		- Post premium state (only applies if premium-enalbed in account).",
		"body": "(string)		- Post episode body or description.",
		"extra_rss_tags": "(mixed)		- Extra post rss tags.",
		"release_date": "(string)		- Post release date for all destinations.  You may set destination release dates individually by using releases instead.  This field must be in "YYYY-mm-dd HH:mm:ss" format. Optional: you may set release_date to "now" which will use the current date/time."
		"releases": "(array)		- An array of release objects, each one is structured as follows: release_id: (int), item_id: (int), destination_id: (int), release_date: (string), expiration_date: (string), release_state: (string), creation_date: (string), destination_name: (string), destination_type_slug: (string), external_release: (boolean)"
	}
}
														
Update Post

Update a Libsyn post (episode).

Request

It is required that the following fields be included in the form data of the body in order to successfully update an existing episode:

  • show_id
  • item_title
  • is_draft
  • release_date

Send a POST request to the /post[/:item_id] endpoint:

$ curl https://api.libsyn.com/post[/:item_id]

-X POST \

-H 'Authorization:Bearer (Your Access Token)'

-H 'Accept: application/json'


-F 'show_id=[:show_id]'

-F 'item_title=[:item_title]'

-F 'is_draft=[:is_draft]'

-F 'release_date=[:release_date]'


Response

On success, your app will receive the following response:


{
"status": "(string)		- Represents the status of the post you are attempting to upload.",
"post": {
	"item_title": "(string)		- A individual post title.",
	"show_id": "(string)		- Represents a individual show.  Must be unique show identifier (numerical) or slug (text).",
	"primary_content": "(array)	- Post primary content_id, url, secure_url, filename, duration, mime_type, audio_codec, video_codec",
	"item_slug": "(string)	- Post item slug",
	"item_subtitle": "(string)		- Post subtitle.",
	"is_draft": "(bool)		- Represents if the post is currently not published. {"true", "false"}",
	"qc_state": "(string)		- Quality Control Management: {"none", "awaiting", "approved", "declined", null}",
	"premium_state": "(string)	- Premium State (Premium Shows only): {"premium", "pay", "free", "auto", null}",
	"itunes_explicit": "(string)		- Represents iTunes explicit content {"no", "yes", "clean", null}",
	"itunes_episode_number": "(int)	- iTunes Episode Number",
	"itunes_season_number": "(int)	- iTunes Season Number",
	"itunes_season_number": "(int)	- iTunes Season Number",
	"itunes_episode_type": "(string)	- Represents iTunes episode Type {"full", "trailer", "bonus", null}",
	"itunes_episode_summary": "(string)	- iTunes Episode Summary (simliar to Description)",
	"itunes_episode_title": "(string)	- iTunes Episode Title (similar to Title)",
	"itunes_episode_author": "(string)	- iTunes Episode Author",
	"update_id3": "(bool)	- Update Primary Content id3 tags with post data (mp3 files only)",
	"tv_rating": "(string)		- Represents TV Rating {null, "TV-14", "TV-G", "TV-PG", "TV-Y7", "TV-Y", "TV-MA", null}",
	"tv_subrating": "(string)		- Represents TV Sub Rating {null, "L", "D", "V", "LS", "S", "VL", "VLD", "LSD", "VLS", "LD", "SD", "VS", "VLSD", "VD", null}",
	"category": "(string)		- Post category.",
	"permalink_type": "(string)		- Post permalink type.",
	"custom_permalink_url": "(string)		- Post custom permalink url.",
	"guid": "(string)		- Post content custom identifier.",
	"allow_advertising": "(string)		- Allow advertising on post.",
	"display_comments": "(string)		- Allow displaying of comments on post.",
	"creation_date": "(string)		- Post creation date.",
	"last_updated": "(string)		- Post last updated date.",
	"premium_state": "(string)		- Post premium state (only applies if premium-enalbed in account).",
	"body": "(string)		- Post episode body or description.",
	"extra_rss_tags": "(mixed)		- Extra post rss tags.",
	"release_date": "(string)		- Post release date for all destinations.  You may set destination release dates individually by using releases instead.  This field must be in "YYYY-mm-dd HH:mm:ss" format. Optional: you may set release_date to "now" which will use the current date/time."
	"releases": "(array)		- An array of release objects, each one is structured as follows: release_id: (int), item_id: (int), destination_id: (int), release_date: (string), expiration_date: (string), release_state: (string), creation_date: (string), destination_name: (string), destination_type_slug: (string), external_release: (boolean)"
	}
}
							
Delete Post

Permanently delete a individual Libsyn episode (post).

Field Type Description
status string The status of the item you are attempting to delete.
post object Post item_id.
Request

Send a DELETE request to the /post[/:item_id] endpoint:

$ curl https://api.libsyn.com/post[/:item_id]

-X DELETE \

-H 'Authorization:Bearer (Your Access Token)'

-H 'Accept: application/json'


Response

On success, your app will receive the following response:


{
   "status": "(string)		- The status of the item you are attempting to delete.",
	"post": {
		 "id": "(int)		- Represents an individual post (also known as episodes).",
	}
}