| 1 | {"openapi":"3.0.0","info":{"contact":{"name":"Jokes One","url":"https://jokes.one/api/joke/"},"description":" Jokes One API offers a complete feature rich REST API access to its jokes platform. This is the documentation for the world famous [jokes API](https://jokes.one/api/joke/). If you are a subscriber and you are trying this from a console add 'X-JokesOne-Api-Secret' header and add your api key as the header value. You can test and play with the API right here on this web page. For using the private end points and subscribing to the API please visit https://jokes.one/api/joke/.","termsOfService":"https://jokes.one/terms","title":"Jokes One","version":"1.1","x-apisguru-categories":["entertainment"],"x-logo":{"backgroundColor":"#FFFFFF","url":"https://jokes.one/branding/smile_magenta.png"},"x-origin":[{"format":"swagger","url":"https://api.jokes.one/yaml/jokes.one.yaml","version":"2.0"}],"x-providerName":"jokes.one"},"tags":[{"description":"Access joke of the day service. Use this to get the joke of the day in various categories. This is a free API that is available to public. You must credit Jokes One if you are using the free version. ","externalDocs":{"description":"Find out more","url":"https://jokes.one/api#joke-of-the-day"},"name":"jod"},{"description":"Access random joke service. Use this to get random jokes , jokes filtered by authors or tags etc. You need an API key to access this service.","name":"joke"}],"paths":{"/jod":{"get":{"description":"Gets `Joke of the Day`.\nOptional `category` param determines\nthe category of returned joke of the day\n","parameters":[{"description":"JOD Category","in":"query","name":"category","required":false,"schema":{"type":"string","format":"string"}}],"responses":{"200":{"description":"200 response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/JokeOfTheDayResponse"},"examples":{"response":{"value":"{\n \"success\": {\n \"total\": 1\n },\n \"contents\": {\n \"jokes\": [\n {\n \"category\": \"animal\",\n \"title\": \"Animal Joke of the day \",\n \"description\": \"Animal Joke of the day \",\n \"background\": \"\",\n \"joke\": {\n \"title\": \"Elephant with Diarrhea\",\n \"length\": \"67\",\n \"clean\": \"0\",\n \"racial\": \"0\",\n \"date\": \"2018-11-05\",\n \"id\": \"1tO_XKcm3_qYMkk0k19HEgeF\",\n \"text\": \"What do you give an elephant with diarrhea? \\r\\n\\r\\n\\r\\nLots of room.\\r\\n\\r\\n\"\n }\n }\n ],\n \"copyright\": \"2018-20 https://jokes.one\"\n }\n}"}}},"application/xml":{"examples":{"response":{"value":"<?xml version=\"1.0\"?>\n<response>\n <success>\n <total>1</total>\n </success>\n <contents>\n <jokes>\n <category>animal</category>\n <title>Animal Joke of the day </title>\n <description>Animal Joke of the day </description>\n <background/>\n <joke>\n <title>Elephant with Diarrhea</title>\n <length>67</length>\n <clean>0</clean>\n <racial>0</racial>\n <date>2018-11-05</date>\n <id>1tO_XKcm3_qYMkk0k19HEgeF</id>\n <text>What do you give an elephant with diarrhea? 
 
 
 Lots of room.
 
</text>\n </joke>\n </jokes>\n <copyright>2018-20 https://jokes.one</copyright>\n </contents>\n</response>"}}}}}},"security":[{"X-JokesOne-Api-Secret":[]}],"tags":["jod"]}},"/jod/categories":{"get":{"description":"Gets a list of `Joke of the Day` Categories.\n","responses":{"200":{"description":"200 response","content":{"application/json":{"examples":{"response":{"value":"{\n \"success\": {\n \"total\": 3\n },\n \"contents\": {\n \"categories\": {\n \"jod\": {\n \"category\": \"jod\",\n \"title\": \"Joke of the day \",\n \"description\": \"Joke of the day \",\n \"background\": \"\"\n },\n \"animal\": {\n \"category\": \"animal\",\n \"title\": \"Animal Joke of the day \",\n \"description\": \"Animal Joke of the day \",\n \"background\": \"\"\n },\n \"blonde\": {\n \"category\": \"blonde\",\n \"title\": \"Blonde joke of the day!\",\n \"description\": \"Blonde joke of the day!\",\n \"background\": \"\"\n }\n },\n \"copyright\": \"2018-20 https://jokes.one\"\n }\n}"}}}}}},"security":[{"X-JokesOne-Api-Secret":[]}],"tags":["jod"]}},"/joke":{"delete":{"description":"Delete a joke. The user needs to be the owner of the joke to be able to delete it.\n","parameters":[{"description":"Joke ID","in":"query","name":"id","required":true,"schema":{"type":"string","format":"string"}}],"responses":{"200":{"description":"200 response","content":{"application/xml":{"examples":{"response":{"value":"{}"}}}}},"401":{"description":"401 response","content":{"application/json":{"examples":{"response":{"value":"{\n \"error\": {\n \"code\": 401,\n \"message\": \"Unauthorized\"\n }\n}"}}}}},"404":{"description":"404 response","content":{"application/json":{"examples":{"response":{"value":"{\n \"error\": {\n \"code\": 404,\n \"message\": \"Not Found: Joke not found\"\n }\n} "}}}}}},"security":[{"X-JokesOne-Api-Secret":[]}],"tags":["joke"]},"get":{"description":"Gets a `Joke` with a given `id`.","parameters":[{"description":"Joke ID","in":"query","name":"id","required":false,"schema":{"type":"string","format":"string"}}],"responses":{"200":{"description":"200 response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/JokeResponse"},"examples":{"response":{"value":"{\n \"success\": {\n \"total\": 1\n },\n \"contents\": {\n \"jokes\": [\n {\n \"title\": \"Anti aircraft weapon\",\n \"length\": \"212\",\n \"clean\": null,\n \"racial\": null,\n \"id\": \"pZdOqARLsLVZ84EkBcWptAeF\",\n \"text\": \"\\nThe USA blamed the Russian companies that they were supplying Bagdad with the elastic band for pants. Iraq engineers made the catapults of them and now Iraq soldiers are striking a blow to American air forces.\\n\\n\"\n }\n ],\n \"copyright\": \"2018-20 https://jokes.one\"\n }\n}"}}},"application/xml":{"schema":{"$ref":"#/components/schemas/JokeResponse"},"examples":{"response":{"value":"<?xml version=\"1.0\"?>\n<response>\n <success>\n <total>1</total>\n </success>\n <contents>\n <jokes>\n <title>Anti aircraft weapon</title>\n <length>212</length>\n <clean/>\n <racial/>\n <id>pZdOqARLsLVZ84EkBcWptAeF</id>\n <text>\nThe USA blamed the Russian companies that they were supplying Bagdad with the elastic band for pants. Iraq engineers made the catapults of them and now Iraq soldiers are striking a blow to American air forces.\n\n</text>\n </jokes>\n <copyright>2018-20 https://jokes.one</copyright>\n </contents>\n</response>"}}}}},"401":{"description":"401 response","content":{"application/json":{"examples":{"response":{"value":"{\n \"error\": {\n \"code\": 401,\n \"message\": \"Unauthorized\"\n }\n}"}}}}}},"security":[{"X-JokesOne-Api-Secret":[]}],"tags":["joke"]},"patch":{"description":"Update a joke","parameters":[{"description":"Joke ID","in":"query","name":"id","required":true,"schema":{"type":"string","format":"string"}},{"description":"title","in":"query","name":"title","required":false,"schema":{"type":"string","format":"string"}},{"description":"text","in":"query","name":"text","required":false,"schema":{"type":"string","format":"string"}},{"description":"Joke Author","in":"query","name":"author","required":false,"schema":{"type":"string","format":"string"}},{"description":"Comma Separated tags","in":"query","name":"tags","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"200 response","content":{"application/json":{"examples":{"response":{"value":"{\n \"success\": {\n \"total\": 1\n },\n \"content\": {\n \"joke\": {\n \"id\": \"0tztT1wYHRzdTf7jIccAzweF\"\n }\n }\n}"}}}}},"401":{"description":"401 response","content":{"application/json":{"examples":{"response":{"value":"{\n \"error\": {\n \"code\": 401,\n \"message\": \"Unauthorized\"\n }\n} "}}}}}},"tags":["joke"]},"put":{"description":"Add a new joke to your private collection.","parameters":[{"description":"Joke Title","in":"query","name":"title","required":true,"schema":{"type":"string","format":"string"}},{"description":"Joke Text","in":"query","name":"text","required":true,"schema":{"type":"string","format":"string"}},{"description":"Joke Author","in":"query","name":"author","required":false,"schema":{"type":"string","format":"string"}},{"description":"Comma Separated tags","in":"query","name":"tags","required":false,"schema":{"type":"string","format":"string"}}],"responses":{"200":{"description":"200 response","content":{"application/json":{"examples":{"response":{"value":"{\n \"success\": {\n \"total\": 1\n },\n \"content\": {\n \"joke\": {\n \"id\": \"0tztT1wYHRzdTf7jIccAzweF\"\n }\n }\n}"}}}}},"401":{"description":"401 response","content":{"application/json":{"examples":{"response":{"value":"{\n \"error\": {\n \"code\": 401,\n \"message\": \"Unauthorized\"\n }\n} "}}}}}},"tags":["joke"]}},"/joke/categories":{"get":{"description":"Gets a list of `Joke` Categories.\n","parameters":[{"description":"Response is paged. This parameter controls where response starts the listing at","in":"query","name":"start","required":false,"schema":{"type":"integer","format":"int32","default":0}}],"responses":{"200":{"description":"200 response","content":{"application/json":{"examples":{"response":{"value":"{\n \"success\": {\n \"total\": 8\n },\n \"contents\": {\n \"categories\": {\n \"jod\": \"Joke of the day\",\n \"work\": \"Work Related Joke of the day\",\n \"kids\": \"Joke of the day for kids\"\n },\n \"copyright\": \"2018-20 https://jokes.one\"\n }\n} "}}}}}},"security":[{"X-JokesOne-Api-Secret":[]}],"tags":["joke"]}},"/joke/list":{"get":{"description":"Get the list of jokes in your private collection.","parameters":[{"description":"Response is paged. This parameter controls where response starts the listing at","in":"query","name":"start","required":false,"schema":{"type":"integer","format":"int32","default":0}}],"responses":{"200":{"description":"200 response","content":{"application/json":{"examples":{"response":{"value":"{\n \"success\": {\n \"total\": \"263\",\n \"range\": {\n \"start\": 0,\n \"end\": 5\n }\n },\n \"contents\": {\n \"jokes\": [\n {\n \"joke\": \"I think you should defend to the death their right to march, and then go down and meet them with baseball bats.\",\n \"length\": \"111\",\n \"author\": \"Woody Allen\",\n \"tags\": [],\n \"id\": \"GkeLUydBfiAH0Tcs2w_gwAeF\"\n },\n {\n \"joke\": \"We have come to dedicate a portion of that field, as a final resting place for those who here gave their lives that that nation might live. It is altogether fitting and proper that we should do this. ... The world will little note nor long remember what we say here, but it can never forget what they did here.\",\n \"length\": \"310\",\n \"author\": \"Abraham Lincoln\",\n \"tags\": [],\n \"id\": \"u6fD9eRFA2NFMHuEoeujaAeF\"\n },\n {\n \"joke\": \"Eighty percent of success is showing up.\",\n \"length\": \"40\",\n \"author\": \"Woody Allen\",\n \"tags\": [\n \"success\",\n \"tso-top-100\"\n ],\n \"id\": \"nLvp0vLfofW06PILxmERHgeF\"\n },\n {\n \"joke\": \"Great ambition is the passion of a great character. Those endowed with it may perform very good or very bad acts. All depends on the principals which direct them.\",\n \"length\": \"164\",\n \"author\": \"Napoleon Bonaparte\",\n \"tags\": [\n \"ambition\",\n \"inspire\",\n \"passion\"\n ],\n \"id\": \"X8juAoTtvxSEdgA0sGbYeQeF\"\n },\n {\n \"joke\": \"I have had dreams, and I have had nightmares. I overcame the nightmares because of my dreams.\",\n \"length\": \"93\",\n \"author\": \"Dr. Jonas Salk\",\n \"tags\": [\n \"dream\",\n \"nightmare\"\n ],\n \"id\": \"m_6Fj8QcXlVsQiiW7SAMLAeF\"\n }\n ]\n }\n}"}}}}},"401":{"description":"401 response","content":{"application/json":{"examples":{"response":{"value":"{\n \"error\": {\n \"code\": 401,\n \"message\": \"Unauthorized\"\n }\n} "}}}}}},"tags":["joke"]}},"/joke/random":{"get":{"description":"Gets a `Random Joke`. When you are in a hurry this is what you call to get a random famous joke.","responses":{"200":{"description":"200 response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/JokeResponse"},"examples":{"response":{"value":"{\n \"success\": {\n \"total\": 1\n },\n \"contents\": {\n \"jokes\": [\n {\n \"title\": \"Blonde tap dancer\",\n \"length\": \"86\",\n \"clean\": \"0\",\n \"racial\": \"0\",\n \"id\": \"SVEPCMsk3SbyeWZbERGzKQeF\",\n \"text\": \"What happened to the blonde tap dancer? \\r\\nShe slipped off and fell down the drain.\\r\\n\\r\\n\"\n }\n ],\n \"copyright\": \"2018-20 https://jokes.one\"\n }\n}"}}},"application/xml":{"schema":{"$ref":"#/components/schemas/JokeResponse"},"examples":{"response":{"value":"<?xml version=\"1.0\"?>\n<response>\n <success>\n <total>1</total>\n </success>\n <contents>\n <jokes>\n <title>Blonde tap dancer</title>\n <length>86</length>\n <clean>0</clean>\n <racial>0</racial>\n <id>SVEPCMsk3SbyeWZbERGzKQeF</id>\n <text>What happened to the blonde tap dancer? 
\nShe slipped off and fell down the drain.
\n
\n</text>\n </jokes>\n <copyright>2018-20 https://jokes.one</copyright>\n </contents>\n</response>"}}},"application/js":{"schema":{"$ref":"#/components/schemas/JokeResponse"}}}},"401":{"description":"401 response","content":{"application/json":{"examples":{"response":{"value":"{\n \"error\": {\n \"code\": 401,\n \"message\": \"Unauthorized\"\n }\n}"}}}}}},"tags":["joke"]}},"/joke/search":{"get":{"description":"Search for a `Joke` in Jokes One platform. Optional `category` , `author`, `minlength`, `maxlength` params determines the filters applied while searching for the joke. ","parameters":[{"description":"Joke Category","in":"query","name":"category","required":false,"schema":{"type":"string","format":"string"}},{"description":"keyword to search for in the joke","in":"query","name":"query","required":false,"schema":{"type":"string","format":"string"}},{"description":"Joke minimum Length","in":"query","name":"minlength","required":false,"schema":{"type":"integer","format":"int32","default":100}},{"description":"Joke maximum Length","in":"query","name":"maxlength","required":false,"schema":{"type":"integer","format":"int32","default":300}},{"description":"Joke Author","in":"query","name":"author","required":false,"schema":{"type":"string","format":"string"}},{"description":"Should search private collection? Default searches public collection.","in":"query","name":"private","required":false,"schema":{"type":"boolean","format":"boolean","default":false}}],"responses":{"200":{"description":"200 response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/JokeResponse"},"examples":{"response":{"value":"{\n \"success\": {\n \"total\": 1\n },\n \"contents\": {\n \"jokes\": [\n {\n \"title\": \"Blonde tap dancer\",\n \"length\": \"86\",\n \"clean\": \"0\",\n \"racial\": \"0\",\n \"id\": \"SVEPCMsk3SbyeWZbERGzKQeF\",\n \"text\": \"What happened to the blonde tap dancer? \\r\\nShe slipped off and fell down the drain.\\r\\n\\r\\n\"\n }\n ],\n \"copyright\": \"2018-20 https://jokes.one\"\n }\n}"}}},"application/xml":{"schema":{"$ref":"#/components/schemas/JokeResponse"},"examples":{"response":{"value":"<?xml version=\"1.0\"?>\n<response>\n <success>\n <total>1</total>\n </success>\n <contents>\n <jokes>\n <title>Blonde tap dancer</title>\n <length>86</length>\n <clean>0</clean>\n <racial>0</racial>\n <id>SVEPCMsk3SbyeWZbERGzKQeF</id>\n <text>What happened to the blonde tap dancer? 
\nShe slipped off and fell down the drain.
\n
\n</text>\n </jokes>\n <copyright>2018-20 https://jokes.one</copyright>\n </contents>\n</response> "}}}}},"401":{"description":"401 response","content":{"application/json":{"examples":{"response":{"value":"{\n \"error\": {\n \"code\": 401,\n \"message\": \"Unauthorized\"\n }\n}"}}}}}},"security":[{"X-JokesOne-Api-Secret":[]}],"tags":["joke"]}},"/joke/tags/add":{"post":{"description":"Add a tag to a given Joke.","parameters":[{"description":"Joke ID","in":"query","name":"id","required":true,"schema":{"type":"string","format":"string"}},{"description":"Comma Separated tags","in":"query","name":"tags","required":true,"schema":{"type":"string","format":"string"}}],"responses":{"200":{"description":"200 response","content":{"application/json":{"examples":{"response":{"value":"{\n}"}}}}},"401":{"description":"401 response","content":{"application/json":{"examples":{"response":{"value":"{\n \"error\": {\n \"code\": 401,\n \"message\": \"Unauthorized\"\n }\n}"}}}}},"404":{"description":"404 response","content":{"application/json":{"examples":{"response":{"value":"{\n \"error\": {\n \"code\": 404,\n \"message\": \"Not Found: Joke not found\"\n }\n} "}}}}}},"tags":["joke"]}},"/joke/tags/remove":{"post":{"description":"Remove a tag from a given joke.","parameters":[{"description":"Joke ID","in":"query","name":"id","required":true,"schema":{"type":"string","format":"string"}},{"description":"Comma Separated tags","in":"query","name":"tags","required":true,"schema":{"type":"string","format":"string"}}],"responses":{"200":{"description":"200 response","content":{"application/json":{"examples":{"response":{"value":"{\n}"}}}}},"401":{"description":"401 response","content":{"application/json":{"examples":{"response":{"value":"{\n \"error\": {\n \"code\": 401,\n \"message\": \"Unauthorized\"\n }\n}"}}}}},"404":{"description":"404 response","content":{"application/json":{"examples":{"response":{"value":"{\n \"error\": {\n \"code\": 404,\n \"message\": \"Not Found: Joke not found\"\n }\n} "}}}}}},"tags":["joke"]}}},"servers":[{"url":"https://api.jokes.one"},{"url":"http://api.jokes.one"}],"components":{"securitySchemes":{"X-JokesOne-Api-Secret":{"in":"header","name":"X-JokesOne-Api-Secret","type":"apiKey"}},"schemas":{"Joke":{"allOf":[{"$ref":"#/components/schemas/NewJoke"},{"properties":{"id":{"description":"Unique identifier representing a specific joke in jokes.one.","type":"string"},"image":{"description":"Image URL that can be used for background to display this joke.","type":"string"},"length":{"description":"Length of the joke string.","format":"int32","type":"integer"}},"type":"object"}]},"JokeOfTheDay":{"allOf":[{"$ref":"#/components/schemas/Joke"},{"properties":{"date":{"description":"Date this joke of the day belongs to","type":"string"}},"required":["date"]}]},"JokeOfTheDayResponse":{"properties":{"contents":{"properties":{"jokes":{"description":"List of jokes","items":{"$ref":"#/components/schemas/JokeOfTheDay"},"type":"array"}}},"success":{"description":"Metadata about this successful call","type":"string"}}},"JokeResponse":{"properties":{"contents":{"properties":{"jokes":{"description":"List of jokes","items":{"$ref":"#/components/schemas/Joke"},"type":"array"}}},"success":{"description":"Metadata about this successful call","type":"string"}}},"NewJoke":{"properties":{"author":{"description":"Author name of joke.","type":"string"},"joke":{"description":"The Joke.","type":"string"},"tags":{"description":"Array of tags/categories.","items":{"type":"string"},"type":"array"},"title":{"description":"Title of the Joke.","type":"string"}},"required":["joke","title"]}}}} |