swagger: '2.0'
schemes:
- https
- http
host: api.jokes.one
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 API
version: '1.1'
x-apisguru-categories:
- entertainment
x-issues:
- https://github.com/APIs-guru/openapi-directory/issues/743
x-logo:
backgroundColor: '#FFFFFF'
url: >-
https://api.apis.guru/v2/cache/logo/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
x-tags:
- helpWanted
consumes:
- application/json
produces:
- application/json
- application/xml
- application/js
securityDefinitions:
X-JokesOne-API-Secret:
in: header
name: X-JokesOne-API-Secret
type: apiKey
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`.
Optional `category` param determines
the category of returned joke of the day
parameters:
- description: JOD Category
format: string
in: query
name: category
required: false
type: string
produces:
- application/json
responses:
'200':
description: 200 response
examples:
application/json: |-
{
"success": {
"total": 1
},
"contents": {
"jokes": [
{
"category": "animal",
"title": "Animal Joke of the day ",
"description": "Animal Joke of the day ",
"background": "",
"joke": {
"title": "Elephant with Diarrhea",
"length": "67",
"clean": "0",
"racial": "0",
"date": "2018-11-05",
"id": "1tO_XKcm3_qYMkk0k19HEgeF",
"text": "What do you give an elephant with diarrhea? \r\n\r\n\r\nLots of room.\r\n\r\n"
}
}
],
"copyright": "2018-20 https://jokes.one"
}
}
application/xml: |-
1
animal
Animal Joke of the day
Animal Joke of the day
Elephant with Diarrhea
67
0
0
2018-11-05
1tO_XKcm3_qYMkk0k19HEgeF
What do you give an elephant with diarrhea?
Lots of room.
2018-20 https://jokes.one
schema:
$ref: '#/definitions/JokeOfTheDayResponse'
security:
- X-JokesOne-API-Secret: []
tags:
- jod
/jod/categories:
get:
description: |
Gets a list of `Joke of the Day` Categories.
produces:
- application/xml
- application/json
responses:
'200':
description: 200 response
examples:
application/json: |-
{
"success": {
"total": 3
},
"contents": {
"categories": {
"jod": {
"category": "jod",
"title": "Joke of the day ",
"description": "Joke of the day ",
"background": ""
},
"animal": {
"category": "animal",
"title": "Animal Joke of the day ",
"description": "Animal Joke of the day ",
"background": ""
},
"blonde": {
"category": "blonde",
"title": "Blonde joke of the day!",
"description": "Blonde joke of the day!",
"background": ""
}
},
"copyright": "2018-20 https://jokes.one"
}
}
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.
parameters:
- description: Joke ID
format: string
in: query
name: id
required: true
type: string
produces:
- application/json
- application/xml
responses:
'200':
description: 200 response
examples:
application/xml: '{}'
'401':
description: 401 response
examples:
application/json: |-
{
"error": {
"code": 401,
"message": "Unauthorized"
}
}
'404':
description: 404 response
examples:
application/json: |-
{
"error": {
"code": 404,
"message": "Not Found: Joke not found"
}
}
security:
- X-JokesOne-API-Secret: []
tags:
- joke
get:
description: Gets a `Joke` with a given `id`.
parameters:
- description: Joke ID
format: string
in: query
name: id
required: false
type: string
produces:
- application/json
- application/xml
responses:
'200':
description: 200 response
examples:
application/json: |-
{
"success": {
"total": 1
},
"contents": {
"jokes": [
{
"title": "Anti aircraft weapon",
"length": "212",
"clean": null,
"racial": null,
"id": "pZdOqARLsLVZ84EkBcWptAeF",
"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"
}
],
"copyright": "2018-20 https://jokes.one"
}
}
application/xml: >-
1
Anti aircraft weapon
212
pZdOqARLsLVZ84EkBcWptAeF
The 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.
2018-20 https://jokes.one
schema:
$ref: '#/definitions/JokeResponse'
'401':
description: 401 response
examples:
application/json: |-
{
"error": {
"code": 401,
"message": "Unauthorized"
}
}
security:
- X-JokesOne-API-Secret: []
tags:
- joke
patch:
description: Update a joke
parameters:
- description: Joke ID
format: string
in: query
name: id
required: true
type: string
- description: title
format: string
in: query
name: title
required: false
type: string
- description: text
format: string
in: query
name: text
required: false
type: string
- description: Joke Author
format: string
in: query
name: author
required: false
type: string
- description: Comma Separated tags
in: query
name: tags
required: false
type: string
responses:
'200':
description: 200 response
examples:
application/json: |-
{
"success": {
"total": 1
},
"content": {
"joke": {
"id": "0tztT1wYHRzdTf7jIccAzweF"
}
}
}
'401':
description: 401 response
examples:
application/json: |-
{
"error": {
"code": 401,
"message": "Unauthorized"
}
}
tags:
- joke
put:
description: Add a new joke to your private collection.
parameters:
- description: Joke Title
format: string
in: query
name: title
required: true
type: string
- description: Joke Text
format: string
in: query
name: text
required: true
type: string
- description: Joke Author
format: string
in: query
name: author
required: false
type: string
- description: Comma Separated tags
format: string
in: query
name: tags
required: false
type: string
responses:
'200':
description: 200 response
examples:
application/json: |-
{
"success": {
"total": 1
},
"content": {
"joke": {
"id": "0tztT1wYHRzdTf7jIccAzweF"
}
}
}
'401':
description: 401 response
examples:
application/json: |-
{
"error": {
"code": 401,
"message": "Unauthorized"
}
}
tags:
- joke
/joke/categories/search:
get:
description: |
Gets a list of `Joke` Categories, based on a query term.
parameters:
- description: Search Query
format: string
in: query
name: query
required: true
type: string
- default: 0
description: >-
Response is paged. This parameter controls where response starts the
listing at
format: int32
in: query
name: start
required: false
type: integer
produces:
- application/xml
- application/json
responses:
'200':
description: 200 response
examples:
application/json: |-
{
"success": {
"total": 8
},
"contents": {
"categories": {
"jod": "Joke of the day",
"work": "Work Related Joke of the day",
"kids": "Joke of the day for kids"
},
"copyright": "2018-20 https://jokes.one"
}
}
security:
- X-JokesOne-API-Secret: []
tags:
- joke
/joke/list:
get:
description: Get the list of jokes in your private collection.
parameters:
- default: 0
description: >-
Response is paged. This parameter controls where response starts the
listing at
format: int32
in: query
name: start
required: false
type: integer
responses:
'200':
description: 200 response
examples:
application/json: |-
{
"success": {
"total": "263",
"range": {
"start": 0,
"end": 5
}
},
"contents": {
"jokes": [
{
"joke": "I think you should defend to the death their right to march, and then go down and meet them with baseball bats.",
"length": "111",
"author": "Woody Allen",
"tags": [],
"id": "GkeLUydBfiAH0Tcs2w_gwAeF"
},
{
"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.",
"length": "310",
"author": "Abraham Lincoln",
"tags": [],
"id": "u6fD9eRFA2NFMHuEoeujaAeF"
},
{
"joke": "Eighty percent of success is showing up.",
"length": "40",
"author": "Woody Allen",
"tags": [
"success",
"tso-top-100"
],
"id": "nLvp0vLfofW06PILxmERHgeF"
},
{
"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.",
"length": "164",
"author": "Napoleon Bonaparte",
"tags": [
"ambition",
"inspire",
"passion"
],
"id": "X8juAoTtvxSEdgA0sGbYeQeF"
},
{
"joke": "I have had dreams, and I have had nightmares. I overcame the nightmares because of my dreams.",
"length": "93",
"author": "Dr. Jonas Salk",
"tags": [
"dream",
"nightmare"
],
"id": "m_6Fj8QcXlVsQiiW7SAMLAeF"
}
]
}
}
'401':
description: 401 response
examples:
application/json: |-
{
"error": {
"code": 401,
"message": "Unauthorized"
}
}
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
examples:
application/json: |-
{
"success": {
"total": 1
},
"contents": {
"jokes": [
{
"title": "Blonde tap dancer",
"length": "86",
"clean": "0",
"racial": "0",
"id": "SVEPCMsk3SbyeWZbERGzKQeF",
"text": "What happened to the blonde tap dancer? \r\nShe slipped off and fell down the drain.\r\n\r\n"
}
],
"copyright": "2018-20 https://jokes.one"
}
}
application/xml: |-
1
Blonde tap dancer
86
0
0
SVEPCMsk3SbyeWZbERGzKQeF
What happened to the blonde tap dancer?
She slipped off and fell down the drain.
2018-20 https://jokes.one
schema:
$ref: '#/definitions/JokeResponse'
'401':
description: 401 response
examples:
application/json: |-
{
"error": {
"code": 401,
"message": "Unauthorized"
}
}
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
format: string
in: query
name: category
required: false
type: string
- description: keyword to search for in the joke
format: string
in: query
name: query
required: false
type: string
- default: 100
description: Joke minimum Length
format: int32
in: query
name: minlength
required: false
type: integer
- default: 300
description: Joke maximum Length
format: int32
in: query
name: maxlength
required: false
type: integer
- description: Joke Author
format: string
in: query
name: author
required: false
type: string
- default: false
description: >-
Should search private collection? Default searches public
collection.
format: boolean
in: query
name: private
required: false
type: boolean
produces:
- application/json
- application/xml
responses:
'200':
description: 200 response
examples:
application/json: |-
{
"success": {
"total": 1
},
"contents": {
"jokes": [
{
"title": "Blonde tap dancer",
"length": "86",
"clean": "0",
"racial": "0",
"id": "SVEPCMsk3SbyeWZbERGzKQeF",
"text": "What happened to the blonde tap dancer? \r\nShe slipped off and fell down the drain.\r\n\r\n"
}
],
"copyright": "2018-20 https://jokes.one"
}
}
application/xml: |-
1
Blonde tap dancer
86
0
0
SVEPCMsk3SbyeWZbERGzKQeF
What happened to the blonde tap dancer?
She slipped off and fell down the drain.
2018-20 https://jokes.one
schema:
$ref: '#/definitions/JokeResponse'
'401':
description: 401 response
examples:
application/json: |-
{
"error": {
"code": 401,
"message": "Unauthorized"
}
}
security:
- X-JokesOne-API-Secret: []
tags:
- joke
/joke/tags/add:
post:
description: Add a tag to a given Joke.
parameters:
- description: Joke ID
format: string
in: query
name: id
required: true
type: string
- description: Comma Separated tags
format: string
in: query
name: tags
required: true
type: string
responses:
'200':
description: 200 response
examples:
application/json: |-
{
}
'401':
description: 401 response
examples:
application/json: |-
{
"error": {
"code": 401,
"message": "Unauthorized"
}
}
'404':
description: 404 response
examples:
application/json: |-
{
"error": {
"code": 404,
"message": "Not Found: Joke not found"
}
}
tags:
- joke
/joke/tags/remove:
post:
description: Remove a tag from a given joke.
parameters:
- description: Joke ID
format: string
in: query
name: id
required: true
type: string
- description: Comma Separated tags
format: string
in: query
name: tags
required: true
type: string
responses:
'200':
description: 200 response
examples:
application/json: |-
{
}
'401':
description: 401 response
examples:
application/json: |-
{
"error": {
"code": 401,
"message": "Unauthorized"
}
}
'404':
description: 404 response
examples:
application/json: |-
{
"error": {
"code": 404,
"message": "Not Found: Joke not found"
}
}
tags:
- joke
definitions:
Joke:
allOf:
- $ref: '#/definitions/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: '#/definitions/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: '#/definitions/JokeOfTheDay'
type: array
success:
description: Metadata about this successful call
type: string
JokeResponse:
properties:
contents:
properties:
jokes:
description: List of jokes
items:
$ref: '#/definitions/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