├── .gitignore ├── LICENSE └── README.md /.gitignore: -------------------------------------------------------------------------------- 1 | README.html -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | CC0 1.0 Universal 2 | 3 | Statement of Purpose 4 | 5 | The laws of most jurisdictions throughout the world automatically confer 6 | exclusive Copyright and Related Rights (defined below) upon the creator and 7 | subsequent owner(s) (each and all, an "owner") of an original work of 8 | authorship and/or a database (each, a "Work"). 9 | 10 | Certain owners wish to permanently relinquish those rights to a Work for the 11 | purpose of contributing to a commons of creative, cultural and scientific 12 | works ("Commons") that the public can reliably and without fear of later 13 | claims of infringement build upon, modify, incorporate in other works, reuse 14 | and redistribute as freely as possible in any form whatsoever and for any 15 | purposes, including without limitation commercial purposes. These owners may 16 | contribute to the Commons to promote the ideal of a free culture and the 17 | further production of creative, cultural and scientific works, or to gain 18 | reputation or greater distribution for their Work in part through the use and 19 | efforts of others. 20 | 21 | For these and/or other purposes and motivations, and without any expectation 22 | of additional consideration or compensation, the person associating CC0 with a 23 | Work (the "Affirmer"), to the extent that he or she is an owner of Copyright 24 | and Related Rights in the Work, voluntarily elects to apply CC0 to the Work 25 | and publicly distribute the Work under its terms, with knowledge of his or her 26 | Copyright and Related Rights in the Work and the meaning and intended legal 27 | effect of CC0 on those rights. 28 | 29 | 1. Copyright and Related Rights. A Work made available under CC0 may be 30 | protected by copyright and related or neighboring rights ("Copyright and 31 | Related Rights"). Copyright and Related Rights include, but are not limited 32 | to, the following: 33 | 34 | i. the right to reproduce, adapt, distribute, perform, display, communicate, 35 | and translate a Work; 36 | 37 | ii. moral rights retained by the original author(s) and/or performer(s); 38 | 39 | iii. publicity and privacy rights pertaining to a person's image or likeness 40 | depicted in a Work; 41 | 42 | iv. rights protecting against unfair competition in regards to a Work, 43 | subject to the limitations in paragraph 4(a), below; 44 | 45 | v. rights protecting the extraction, dissemination, use and reuse of data in 46 | a Work; 47 | 48 | vi. database rights (such as those arising under Directive 96/9/EC of the 49 | European Parliament and of the Council of 11 March 1996 on the legal 50 | protection of databases, and under any national implementation thereof, 51 | including any amended or successor version of such directive); and 52 | 53 | vii. other similar, equivalent or corresponding rights throughout the world 54 | based on applicable law or treaty, and any national implementations thereof. 55 | 56 | 2. Waiver. To the greatest extent permitted by, but not in contravention of, 57 | applicable law, Affirmer hereby overtly, fully, permanently, irrevocably and 58 | unconditionally waives, abandons, and surrenders all of Affirmer's Copyright 59 | and Related Rights and associated claims and causes of action, whether now 60 | known or unknown (including existing as well as future claims and causes of 61 | action), in the Work (i) in all territories worldwide, (ii) for the maximum 62 | duration provided by applicable law or treaty (including future time 63 | extensions), (iii) in any current or future medium and for any number of 64 | copies, and (iv) for any purpose whatsoever, including without limitation 65 | commercial, advertising or promotional purposes (the "Waiver"). Affirmer makes 66 | the Waiver for the benefit of each member of the public at large and to the 67 | detriment of Affirmer's heirs and successors, fully intending that such Waiver 68 | shall not be subject to revocation, rescission, cancellation, termination, or 69 | any other legal or equitable action to disrupt the quiet enjoyment of the Work 70 | by the public as contemplated by Affirmer's express Statement of Purpose. 71 | 72 | 3. Public License Fallback. Should any part of the Waiver for any reason be 73 | judged legally invalid or ineffective under applicable law, then the Waiver 74 | shall be preserved to the maximum extent permitted taking into account 75 | Affirmer's express Statement of Purpose. In addition, to the extent the Waiver 76 | is so judged Affirmer hereby grants to each affected person a royalty-free, 77 | non transferable, non sublicensable, non exclusive, irrevocable and 78 | unconditional license to exercise Affirmer's Copyright and Related Rights in 79 | the Work (i) in all territories worldwide, (ii) for the maximum duration 80 | provided by applicable law or treaty (including future time extensions), (iii) 81 | in any current or future medium and for any number of copies, and (iv) for any 82 | purpose whatsoever, including without limitation commercial, advertising or 83 | promotional purposes (the "License"). The License shall be deemed effective as 84 | of the date CC0 was applied by Affirmer to the Work. Should any part of the 85 | License for any reason be judged legally invalid or ineffective under 86 | applicable law, such partial invalidity or ineffectiveness shall not 87 | invalidate the remainder of the License, and in such case Affirmer hereby 88 | affirms that he or she will not (i) exercise any of his or her remaining 89 | Copyright and Related Rights in the Work or (ii) assert any associated claims 90 | and causes of action with respect to the Work, in either case contrary to 91 | Affirmer's express Statement of Purpose. 92 | 93 | 4. Limitations and Disclaimers. 94 | 95 | a. No trademark or patent rights held by Affirmer are waived, abandoned, 96 | surrendered, licensed or otherwise affected by this document. 97 | 98 | b. Affirmer offers the Work as-is and makes no representations or warranties 99 | of any kind concerning the Work, express, implied, statutory or otherwise, 100 | including without limitation warranties of title, merchantability, fitness 101 | for a particular purpose, non infringement, or the absence of latent or 102 | other defects, accuracy, or the present or absence of errors, whether or not 103 | discoverable, all to the greatest extent permissible under applicable law. 104 | 105 | c. Affirmer disclaims responsibility for clearing rights of other persons 106 | that may apply to the Work or any use thereof, including without limitation 107 | any person's Copyright and Related Rights in the Work. Further, Affirmer 108 | disclaims responsibility for obtaining any necessary consents, permissions 109 | or other rights required for any use of the Work. 110 | 111 | d. Affirmer understands and acknowledges that Creative Commons is not a 112 | party to this document and has no duty or obligation with respect to this 113 | CC0 or use of the Work. 114 | 115 | For more information, please see 116 | 117 | 118 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # Patreon API 2 | Patreon is developing an API of sorts. It's currently not used for a lot of actions on their website, other than for a few cleaned up features. It's also not documented yet. I'm doing some digging and am going to try my best to provide some documentation for it. I am not at all affiliated with Patreon and provide no warranty that this information will work in the future or even now. I'm just publishing it in the hope that it will be useful and will help people extend the Patreon platform in awesome ways. 3 | 4 | ## Notes 5 | 6 | Some important information to look at before diving into this API. 7 | 8 | ### Making requests 9 | 10 | Patreon is making use of the [JSON API spec](http://jsonapi.org) so some implementation details can be found by plumbing that documentation. The root of the API is at api.patreon.com 11 | 12 | ### API keys 13 | 14 | Some requests require that you have an API key when you make them. This is done by appending "?api_key=YOUR API KEY" to the end of the URL. At present, it looks like there's only one API key shared by everyone: 1745177328c8a1d48100a9b14a1d38c1. Methods that require an api key are marked as such. 15 | 16 | 17 | ### Timestamps 18 | 19 | Unless otherwise indicated, assume all timestamps are in this format: 1970-12-31T23:59:59 20 | 21 | 22 | 23 | ## Methods 24 | 25 | 26 | ### /login (POST) 27 | 28 | Method for iniating a user session. Also retrieves a lot of information about the logged in user. 29 | 30 | **Body data** 31 | 32 | * email: user's patreon login email 33 | * password: user's patreon login password 34 | 35 | **Response** 36 | 37 | * data: user object 38 | 39 | In addition to returning a JSON object with information about the user, the server also responds with a Set-Cookie header that sets a cookie named "session_id" to a unique session ID on the domain "patreon.com". This cookie appears to expire a month later by default. 40 | 41 | 42 | ### /user (POST) 43 | 44 | Creates a user, currently used for FB registrations 45 | 46 | **Body data** 47 | 48 | * fb\_access\_token: presumably an access token for Facebook's API? 49 | * email: the email associated with the user's Facebook account? 50 | 51 | **Response** 52 | 53 | * data: user object 54 | 55 | 56 | ### /user/:userid (GET) 57 | 58 | Retrieves data about a given user **[requires api key]** 59 | 60 | **Response** 61 | 62 | * data: user object 63 | 64 | 65 | ### /current_user (GET) 66 | 67 | Retrieves information about the currently logged-in user. Appending "?include=cards" to the URL causes credit card information to be included as well. 68 | 69 | **Response** 70 | 71 | * data: user object 72 | * If "?include=cards", card objects (see below) will be linked. 73 | 74 | 75 | 76 | ### /notifications 77 | 78 | Unfinished endpoint for an unreleased feature 79 | 80 | **Response** 81 | 82 | * data: currently an empty array 83 | 84 | 85 | 86 | ### /campaign (GET) 87 | 88 | Retrieves a list of campaigns. Only seems to work if "?filter=subbable" is appended to the URL 89 | 90 | **Response** 91 | 92 | * data: array of campaign objects 93 | 94 | 95 | 96 | ### /campaign/current_campaign (GET) 97 | 98 | Unfinished endpoint for an unreleased feature **[requires api key]** 99 | 100 | 101 | 102 | ### /campaign/:campaignid (GET) 103 | 104 | Retrieves information about a particular campaign **[requires api key]** 105 | 106 | **Response** 107 | 108 | * data: array of all category objects 109 | * included: array of all reward objects and the user object for the creator of this campaign 110 | 111 | 112 | 113 | ### /campaign/:campaignid/drafts (GET) 114 | 115 | Unfinished endpoint for an unreleased feature **[requires api key]** 116 | 117 | 118 | 119 | ### /categories (GET) 120 | 121 | Gets a list of all the categories on the site (this is part of an unreleased feature) **[requires api key]** 122 | 123 | **Response** 124 | 125 | * data: array of all category objects 126 | 127 | 128 | 129 | ### /reward/:rewardid (GET) 130 | 131 | Retrieves a given reward by its numeric ID **[requires api key]** 132 | 133 | **Response** 134 | 135 | * data: a reward object 136 | * included: the user object of the creator 137 | 138 | 139 | 140 | ### /post (GET) 141 | 142 | Creates a post??? Or maybe creates an ID for a post, which can then be modified with another call??? **[requires api key]** 143 | 144 | 145 | ### /post/:postid (GET) 146 | 147 | Unfinished endpoint for an unreleased feature (but seems to be relatively functional at present). 148 | 149 | Retrieves a given post by its numeric ID **[requires api key]** 150 | 151 | **Response** 152 | 153 | * data: a post object 154 | 155 | 156 | ### /post/:postid (POST) 157 | 158 | Unfinished endpoint for an unreleased feature 159 | 160 | Modifies an existing post **[requires api key]** 161 | 162 | 163 | ### /post/:postid (DELETE) 164 | 165 | Unfinished endpoint for an unreleased feature 166 | 167 | Deletes an existing post **[requires api key]** 168 | 169 | 170 | ### /post/:postid/undelete (GET?) 171 | 172 | Unfinished endpoint for an unreleased feature 173 | 174 | Undeletes a previously-deleted post **[requires api key]** 175 | 176 | 177 | ### /post/:postid/attachments (GET) 178 | 179 | Unfinished endpoint for an unreleased feature 180 | 181 | Retrieves the attachments for a given post **[requires api key]** 182 | 183 | **Response** 184 | 185 | * data: an array, presumably of attachments? 186 | 187 | 188 | ### /post/:postid/attachments (POST) 189 | 190 | Unfinished endpoint for an unreleased feature 191 | 192 | Uploads an attachment **[requires api key]** 193 | 194 | 195 | ### /post/:postid/attachments (DELETE) 196 | 197 | Unfinished endpoint for an unreleased feature 198 | 199 | Deletes an existing attachment **[requires api key]** 200 | 201 | 202 | 203 | 204 | 205 | ## Data types 206 | 207 | These are the types of objects that may be included in requests or responses, either as the main "data" object, or as an object in the "linked" array. 208 | 209 | ### Campaign 210 | 211 | Represents a campaign (i.e. a content creator's patreon page, essentially). Often, the 'included' array will include all the reward objects for this campaign and a user object for the creator of this campaign. 212 | 213 | ``` 214 | { 215 | "about": "", // can contain HTML markup 216 | "created_at": "" 217 | "creation_name": "", 218 | "creator": , // seems to be a Subbable-only thing?? 219 | "creator_name": "", //seems to be a Subbable-only thing?? 220 | "id": , // campaign ID number 221 | "image_small_url": "", 222 | "image_url": "", 223 | "is_monthly": , // does this campaign charge per-month or per-creation? 224 | "is_nsfw": , 225 | "links": { 226 | "rewards": { 227 | "linkage": [ 228 | // array of reward objects 229 | ] 230 | } 231 | } 232 | "main_video_embed": "", // an embed tag for the campaign's main video 233 | "main_video_url": "", // an url to the campaign's main video 234 | "one_liner": "", 235 | "patron_count": , 236 | "pay_per_name": "" // what are supporters being charged for? (e.g. "month", "video", etc.) 237 | "pledge_sum": , // pledged amount in cents 238 | "published_at": "", 239 | "summary": "", 240 | "thanks_embed": "", // embed tag for patron thanks video (null if no video), 241 | "thanks_msg": "", // message shown to thank patrons 242 | "thanks_video_url": "", // url for patron thanks video (null if no video), 243 | "type": "campaign", 244 | "url": "" // generally https://www.patreon.com/ 245 | } 246 | ``` 247 | 248 | ### Card 249 | 250 | Represents a credit card or other payment method (i.e. PayPal) 251 | 252 | ``` 253 | { 254 | "card_type": "", // known possibilities: "PayPal", "Visa" 255 | "expiration_date": "", // will be null for PayPal 256 | "id": "", 257 | "links": { 258 | "user": { 259 | "id": "", 260 | "type": "user" 261 | } 262 | }, 263 | "number": , // will be 0 for PayPal 264 | "type": "card" 265 | } 266 | ``` 267 | 268 | ### Category 269 | 270 | Represents a category of campaign (e.g. Music, Comics, etc) 271 | 272 | ``` 273 | { 274 | "id": , // at time of writing, categories are ids 0-14, except the "All" category, which has id 99 275 | "name": , 276 | "type": "category" 277 | } 278 | ``` 279 | 280 | 281 | ### Comment 282 | 283 | Represents a comment on a post 284 | 285 | ``` 286 | { 287 | "type": "", 288 | "body": "", 289 | "links": { 290 | "parent": { 291 | "linkage": { 292 | "type": "", 293 | "id": "" 294 | } 295 | } 296 | } 297 | } 298 | ``` 299 | 300 | 301 | ### Post 302 | 303 | Represents a post or creation on a campaign 304 | 305 | ``` 306 | { 307 | "campaign_id": "", 308 | "category": , // null if no comment set 309 | "cents_pledged_at_creation": , // what was the total sum of all pledges at the time when this was posted? 310 | "comment_count": , 311 | "content": "", 312 | "created_at": "", // presumably can't be null 313 | "current_user_has_liked": , // has the logged in user liked this post? 314 | "deleted_at": , // null if not deleted 315 | "edited_at": , // null if not edited 316 | "embed": { // stuff for embedding videos. if it's not a video, all sub-fields will be set to null 317 | "description": null, // video description 318 | "domain": null, // web domain of platform where video is uploaded 319 | "html": null, // video embed code 320 | "subject": null, // video title 321 | "url": null // video url (i.e. on youtube or whatever other platform) 322 | }, 323 | "id": "", 324 | "image_height": , // 0 if no image 325 | "image_large_url": "", // null if no image 326 | "image_url": "", // null if no image 327 | "image_width": , // 0 if no image 328 | "is_creation": , // is this a creation or just a post? 329 | "is_paid": , // true if this is an automated post after a month/content is completed, else false 330 | "like_count": , 331 | "min_cents_pledged_to_view": , // minimum individual pledge necessary to view post 332 | "post_type": "", // may be other unknown values 333 | "published_at": "", // null if unpublished 334 | "thumbnail_url": "", // null if no image 335 | "title": "", 336 | "type": "post", 337 | "url": "", 338 | "user_id": "" 339 | } 340 | ``` 341 | 342 | 343 | ### Reward 344 | 345 | Represents a reward tier for a campaign. There are two reward objects, id:-1 "Everyone" and id:0 "Patrons Only", that seem to be global and constant for all campaigns. 346 | 347 | ``` 348 | { 349 | "amount": , // pledge in cents required to access this reward (null if unrestricted) 350 | "created_at": , // null for global rewards 351 | "creator_id": null, // only appears for global rewards 352 | "description": "", // description of what this 353 | "id": "", 354 | "links": { 355 | "creator": { 356 | "linkage": { 357 | "id": "", 358 | "type": "user" 359 | } 360 | } 361 | }, 362 | "requires_shipping": , // does patreon require a shipping address from users who enter at this level? 363 | "type": "reward", 364 | "user_limit": // how many users are allowed to claim this reward? 0 if unlimited, null for global rewards 365 | }, 366 | ``` 367 | 368 | 369 | ### User 370 | 371 | A user object contains information about a Patreon user, usually the currently logged-in user. 372 | 373 | ``` 374 | { 375 | "about": "", // an optional bio, can be null 376 | "created": "", 377 | "email": "", 378 | "first_name": "", 379 | "full_name": "", 380 | "gender": , // 0 if unset, 1 if male, 2 if female 381 | "id": "", // is always numeric afaik, but appears as a string nonetheless 382 | "image_url": "", 383 | "last_name": "", 384 | "status": 1, // not sure what this means, usually it's 1 but I have seen 0 385 | "thumb_url": "", 386 | "type": "user", 387 | "url": "", 388 | "vanity": "" // null if no vanity username set 389 | } 390 | ``` 391 | --------------------------------------------------------------------------------