├── sections ├── podcasts.md └── episodes.md └── README.md /sections/podcasts.md: -------------------------------------------------------------------------------- 1 | 2 | Podcasts 3 | ======== 4 | 5 | Get podcasts 6 | ------------ 7 | 8 | * `GET /podcasts.json` will return all the episodes for a podcast. 9 | * This should be called without the podcast_id in the URL. The URL should look like `/api/podcasts.json`. 10 | 11 | ```json 12 | [ 13 | { 14 | "id": 10, 15 | "title": "Life Empowerment", 16 | "author": "Motivational Mike", 17 | "description": "Let me tell you how to live your best life today!", 18 | "website_address": null, 19 | "contact_email": "team+mike@buzzsprout.com", 20 | "keywords": null, 21 | "explicit": false, 22 | "main_category": null, 23 | "sub_category": null, 24 | "main_category2": null, 25 | "sub_category2": null, 26 | "main_category3": null, 27 | "sub_category3": null, 28 | "language": "en-us", 29 | "timezone": "Eastern Time (US \u0026 Canada)", 30 | "artwork_url": "http://www.buzzsprout.test/images/artworks_large.jpg", 31 | "background_url": null 32 | }, 33 | { 34 | "id": 20, 35 | "title": "Youth Podcast", 36 | "author": "Pastor Tim Tom", 37 | "description": "Our super cool youth podcast", 38 | "website_address": null, 39 | "contact_email": "team+tim@buzzsprout.com", 40 | "keywords": null, 41 | "explicit": false, 42 | "main_category": null, 43 | "sub_category": null, 44 | "main_category2": null, 45 | "sub_category2": null, 46 | "main_category3": null, 47 | "sub_category3": null, 48 | "language": "en-us", 49 | "timezone": "Eastern Time (US \u0026 Canada)", 50 | "artwork_url": "http://www.buzzsprout.test/images/artworks_large.jpg", 51 | "background_url": null 52 | } 53 | ] 54 | ``` 55 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | Buzzsprout API 2 | ==================== 3 | 4 | This is version one of the Buzzsprout API. This API has been designed around RESTful concepts with JSON for serialization. 5 | 6 | URL 7 | --- 8 | All requests are SSL only and the API URL is `https://www.buzzsprout.com/api/9999` where `9999` is the podcast identifier. If we change the API in backward-incompatible ways, we'll add the version marker and maintain stable support for old URLs. 9 | 10 | 11 | Authentication 12 | -------------- 13 | 14 | Buzzsprout uses a simple token-based HTTP Authentication scheme. For clients to authenticate, the method "Token" and the token key should be included in the Authorization HTTP header. The key should be prefixed by the string literal "token=" with no whitespace. For example: 15 | 16 | ```shell 17 | Authorization: Token token=ApV99yzvwApV99yzvwApV99yzvwApV99yzvw 18 | ``` 19 | 20 | 21 | Additionaly you can pass the api token as a paramater in the URL 22 | ``` 23 | ?api_token=ApV99yzvwApV99yzvwApV99yzvwApV99yzvw 24 | ``` 25 | 26 | To retrieve your token check out the my account section in your Buzzsprout admin at [buzzsprout.com](https://www.buzzsprout.com "www.buzzsprout.com"). 27 | 28 | User Agent 29 | ---------- 30 | Ensure you set the user agent header. Failing to do so may result in a blocked request since many bots and spammers use the default user agent set by the libraries used with making requests. 31 | 32 | Body Format 33 | ---------- 34 | All data is serialized with JSON and UTF-8 encoded. This means that you have to send `Content-Type: application/json; charset=utf-8` when you're POSTing or PUTing data into Buzzsprout. All API URLs end in .json to indicate that they accept and return JSON. 35 | 36 | You'll receive a `415 Unsupported Media Type` response code if you attempt to use a different URL suffix or leave out the `Content-Type` header. 37 | 38 | Sample GET 39 | ------- 40 | To make a request for all the Episodes on your account, you'd append the episodes index path to the base url to form something like https://www.buzzsprout.com/api/9999/episodes.json. In cURL, that looks like: 41 | 42 | ```shell 43 | curl -H "Authorization: Token token=ApV99yzvwApV99yzvwApV99yzvwApV99yzvw" \ 44 | https://www.buzzsprout.com/api/9999/episodes.json 45 | ``` 46 | Sample POST 47 | ------------ 48 | To create something, it's the same deal except you also have to include the `Content-Type` header and the JSON data: 49 | 50 | ```shell 51 | curl -H "Authorization: Token token=ApV99yzvwApV99yzvwApV99yzvwApV99yzvw" \ 52 | -H 'Content-Type: application/json' \ 53 | -d '{ "title": "My new episode!" }' \ 54 | https://www.buzzsprout.com/api/9999/episodes.json 55 | ``` 56 | 57 | Use HTTP caching 58 | ---------------- 59 | 60 | You must make use of the HTTP freshness headers to lessen the load on our servers (and increase the speed of your application!). Most requests we return will include an `ETag` or `Last-Modified` header. When you first request a resource, store this value, and then submit them back to us on subsequent requests as `If-None-Match` and `If-Modified-Since`. If the resource hasn't changed, you'll see a `304 Not Modified` response, which saves you the time and bandwidth of sending something you already have. 61 | 62 | 63 | Handling errors 64 | --------------- 65 | 66 | If Buzzsprout is having trouble, you might see a 5xx error. `500` means that the app is entirely down, but you might also see `502 Bad Gateway`, `503 Service Unavailable`, or `504 Gateway Timeout`. It's your responsibility in all of these cases to retry your request later. 67 | 68 | 69 | Thanks! 70 | ---------------------- 71 | 72 | Thank you for checking out Buzzsprout's API and please don't hesitate to reach out and let us know how you are using the API. Feel free to use GitHub issues to post any issues or feature requests. 73 | 74 | Please tell us how we can make the API better. If you have a specific feature request or if you found a bug, please use GitHub issues. Fork these docs and send a pull request with improvements. 75 | 76 | To talk with us and other developers about the API, [post a question on StackOverflow](http://stackoverflow.com/questions/ask) tagged `Buzzsprout` or [check out our support section](http://www.buzzsprout.com/help). 77 | -------------------------------------------------------------------------------- /sections/episodes.md: -------------------------------------------------------------------------------- 1 | Episodes 2 | ======== 3 | Run the following examples in Postman [![Run in Postman](https://run.pstmn.io/button.svg)](https://app.getpostman.com/run-collection/6eae6ad6bc679e8ad112) 4 | 5 | Get episodes 6 | ------------ 7 | 8 | * `GET /episodes.json` will return all the episodes for a podcast. 9 | 10 | ```json 11 | [ 12 | 13 | { 14 | "id":788881, 15 | "title":"Too small or too big?", 16 | "audio_url":"https://www.buzzsprout.com/140447/788881-filename.mp3", 17 | "artwork_url":"https://storage.buzzsprout.com/variants/NABbMDx7JN5bSLzLPXyj67jA/8d66eb17bb7d02ca4856ab443a78f2148cafbb129f58a3c81282007c6fe24ff2", 18 | "description":"", 19 | "summary":"", 20 | "artist":"Muffin Man", 21 | "tags":"", 22 | "published_at":"2019-09-12T03:00:00.000-04:00", 23 | "duration":12362, 24 | "hq":true, 25 | "magic_mastering":true, 26 | "guid":"Buzzsprout788881", 27 | "inactive_at":null, 28 | "episode_number":5, 29 | "season_number":5, 30 | "explicit":false, 31 | "private":false, 32 | "total_plays":150 33 | }, 34 | { 35 | "id":788880, 36 | "title":"Too fast or too slow?", 37 | "audio_url":"https://www.buzzsprout.com/140447/788880-filename.mp3", 38 | "artwork_url":"https://storage.buzzsprout.com/variants/NABbMDx7JN5bSLzLPXyj67jA/8d66eb17bb7d02ca4856ab443a78f2148cafbb129f58a3c81282007c6fe24ff2", 39 | "description":"", 40 | "summary":"", 41 | "artist":"Muffin Man", 42 | "tags":"", 43 | "published_at":"2019-09-12T03:00:00.000-04:00", 44 | "duration":23462, 45 | "hq":false, 46 | "magic_mastering":false, 47 | "guid":"Buzzsprout788880", 48 | "inactive_at":null, 49 | "episode_number":4, 50 | "season_number":5, 51 | "explicit":true, 52 | "private":false, 53 | "total_plays":150 54 | } 55 | ] 56 | ``` 57 | 58 | Get episode 59 | ------------ 60 | 61 | * `GET /episodes/788881.json` will return the specifed episode. 62 | 63 | ```json 64 | 65 | { 66 | "id":788881, 67 | "title":"Too small or too big?", 68 | "audio_url":"https://www.buzzsprout.com/140447/788881-filename.mp3", 69 | "artwork_url":"https://storage.buzzsprout.com/variants/NABbMDx7JN5bSLzLPXyj67jA/8d66eb17bb7d02ca4856ab443a78f2148cafbb129f58a3c81282007c6fe24ff2", 70 | "description":"", 71 | "summary":"", 72 | "artist":"Muffin Man", 73 | "tags":"", 74 | "published_at":"2019-09-12T03:00:00.000-04:00", 75 | "duration":12362, 76 | "hq":true, 77 | "guid":"Buzzsprout788881", 78 | "inactive_at":null, 79 | "episode_number":5, 80 | "season_number":5, 81 | "explicit":false, 82 | "private":false, 83 | "total_plays":150 84 | } 85 | ``` 86 | 87 | 88 | Create episode 89 | ------------- 90 | * `POST /episodes.json` will create a new episode with the included parameters. 91 | 92 | ```json 93 | { 94 | "title":"Too many or too few?", 95 | "description":"", 96 | "summary":"", 97 | "artist":"Muffin Man", 98 | "tags":"", 99 | "published_at":"2019-09-12T03:00:00.000-04:00", 100 | "duration":23462, 101 | "guid":"Buzzsprout788880", 102 | "inactive_at":null, 103 | "episode_number":4, 104 | "season_number":5, 105 | "explicit":true, 106 | "private":true, 107 | "email_user_after_audio_processed": true, 108 | "audio_url": "https://www.google.com/my_audio_file.mp4", 109 | "artwork_url": "https://www.google.com/my_artwork_file.jpeg" 110 | } 111 | ``` 112 | 113 | This will return `201 Created`, with the current JSON representation of the episode if the creation was a success. 114 | 115 | **To send an audio file or artwork file**: Instead of sending the *audio_url* param you can send the actual file as an attachment with the *audio_file* param. Likewise, instead of sending the *artwork_url* param you can send the actual file as an attachment with the *artwork_file* param 116 | 117 | **Email user after audio processed**: Sends the user an email once your file has finished processing or if an error occurred during processing. It defaults to true and can be set to false to not send any emails. 118 | 119 | 120 | Update episode 121 | ------------- 122 | * `PUT /episodes/1.json` will update an existing episode with the included parameters. 123 | 124 | ```json 125 | { 126 | "title":"The New Republic", 127 | "private":false 128 | } 129 | ``` 130 | 131 | This will return `200 OK` along with the current JSON representation of the updated episode if the creation was a success. 132 | --------------------------------------------------------------------------------