{"openapi":"3.1.0","info":{"title":"Mr Farts API","version":"1.0.0","description":"Free fart sounds, Mr Farts songs and cartoons from HUGO FM GAMES. No sign-in. Action endpoints return text to show or speak and a playlist of media to play.","contact":{"name":"HUGO FM GAMES","url":"https://hugo.fm/contact"},"termsOfService":"https://fart.shoutoutgames.com/terms"},"externalDocs":{"description":"Developer documentation","url":"https://fart.shoutoutgames.com/api"},"servers":[{"url":"https://fart.shoutoutgames.com/v1"}],"tags":[{"name":"Catalogue","description":"Browse sounds, songs and cartoons"},{"name":"Actions","description":"Pick something to play"}],"paths":{"/categories":{"get":{"tags":["Catalogue"],"operationId":"listCategories","summary":"List the packs","parameters":[{"name":"locale","in":"query","required":false,"schema":{"type":"string","maxLength":20,"example":"en-US"},"description":"Language for titles: en-US, de-DE, fr-FR or es-ES."}],"responses":{"200":{"description":"The packs","content":{"application/json":{"schema":{"type":"object","properties":{"categories":{"type":"array","items":{"$ref":"#/components/schemas/Category"}}},"required":["categories"]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/sounds":{"get":{"tags":["Catalogue"],"operationId":"listSounds","summary":"Search the catalogue","parameters":[{"name":"category","in":"query","required":false,"schema":{"type":"string","enum":["sounds","animal","music","cartoon","christmas","easter","halloween","valentine"]},"description":"Limit to one pack."},{"name":"query","in":"query","required":false,"schema":{"type":"string","maxLength":150},"description":"Search text. Empty lists the whole pack."},{"name":"locale","in":"query","required":false,"schema":{"type":"string","maxLength":20,"example":"en-US"},"description":"Language for titles: en-US, de-DE, fr-FR or es-ES."},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"maximum":1000,"default":0}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":30}}],"responses":{"200":{"description":"Matching items","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SoundList"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/sounds/{id}":{"get":{"tags":["Catalogue"],"operationId":"getSound","summary":"Get one item","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"sounds:24"}},{"name":"locale","in":"query","required":false,"schema":{"type":"string","maxLength":20,"example":"en-US"},"description":"Language for titles: en-US, de-DE, fr-FR or es-ES."}],"responses":{"200":{"description":"The item","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Media"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No item with this ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/fart":{"post":{"tags":["Actions"],"operationId":"fart","summary":"Play a fart","description":"A fart: random by default, or a named sound, animal, person-name joke, seasonal pack, extreme, the fart of the day, or 1 to 100 sounds in a row. Unknown names play a random fart.","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"locale":{"type":"string","maxLength":20},"timezone":{"type":"string","maxLength":80},"selection":{"description":"Catalog ID or a name/synonym from the user. Omit for a random choice.","type":"string","minLength":1,"maxLength":150},"category":{"type":"string","enum":["sounds","animal","music","cartoon","christmas","easter","halloween","valentine"]},"personName":{"type":"string","minLength":1,"maxLength":100},"mode":{"type":"string","enum":["random","extreme","daily"]},"count":{"type":"integer","minimum":1,"maximum":100}},"additionalProperties":false}}}},"responses":{"200":{"description":"What to play","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlayResult"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/music":{"post":{"tags":["Actions"],"operationId":"playFartMusic","summary":"Play a Mr Farts song","description":"A Mr Farts song by title or catalogue ID, or at random.","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"locale":{"type":"string","maxLength":20},"timezone":{"type":"string","maxLength":80},"selection":{"description":"Catalog ID or a name/synonym from the user. Omit for a random choice.","type":"string","minLength":1,"maxLength":150}},"additionalProperties":false}}}},"responses":{"200":{"description":"What to play","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlayResult"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/cartoon":{"post":{"tags":["Actions"],"operationId":"playFartCartoon","summary":"Play a Mr Farts cartoon","description":"A Mr Farts cartoon video by title or catalogue ID, or at random.","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"locale":{"type":"string","maxLength":20},"timezone":{"type":"string","maxLength":80},"selection":{"description":"Catalog ID or a name/synonym from the user. Omit for a random choice.","type":"string","minLength":1,"maxLength":150}},"additionalProperties":false}}}},"responses":{"200":{"description":"What to play","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlayResult"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/countdown":{"post":{"tags":["Actions"],"operationId":"startFartCountdown","summary":"Fart after a countdown","description":"Counts down 1 to 1,800 seconds (default 60), then farts. Wait delaySeconds before playing.","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"locale":{"type":"string","maxLength":20},"timezone":{"type":"string","maxLength":80},"seconds":{"type":"integer","minimum":1,"maximum":1800}},"additionalProperties":false}}}},"responses":{"200":{"description":"What to play","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlayResult"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/fart-time":{"post":{"tags":["Actions"],"operationId":"fartTime","summary":"Tell the time in farts","description":"Tells the time with fart sounds. Pass an IANA timezone; the default is UTC.","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"locale":{"type":"string","maxLength":20},"timezone":{"type":"string","maxLength":80}},"additionalProperties":false}}}},"responses":{"200":{"description":"What to play","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlayResult"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/weather":{"post":{"tags":["Actions"],"operationId":"fartWeather","summary":"The windy weather joke","description":"The Mr Farts windy-weather joke. It is not a real forecast.","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"locale":{"type":"string","maxLength":20},"timezone":{"type":"string","maxLength":80}},"additionalProperties":false}}}},"responses":{"200":{"description":"What to play","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlayResult"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/prank":{"post":{"tags":["Actions"],"operationId":"fartPrank","summary":"The come-closer prank","description":"The come-closer prank: show the text, wait delaySeconds, then play.","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"locale":{"type":"string","maxLength":20},"timezone":{"type":"string","maxLength":80}},"additionalProperties":false}}}},"responses":{"200":{"description":"What to play","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlayResult"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"schemas":{"Category":{"type":"object","properties":{"id":{"type":"string","enum":["sounds","animal","music","cartoon","christmas","easter","halloween","valentine"]},"title":{"type":"string"},"count":{"type":"integer"}},"required":["id","title","count"]},"Media":{"type":"object","properties":{"id":{"type":"string","example":"sounds:24"},"title":{"type":"string","example":"Wet"},"category":{"type":"string","enum":["sounds","animal","music","cartoon","christmas","easter","halloween","valentine"]},"audioUrl":{"type":"string","format":"uri","description":"MP3"},"videoUrl":{"type":"string","format":"uri","description":"MP4"},"imageUrl":{"type":"string","format":"uri","description":"Thumbnail image"}},"required":["id","title","category"]},"SoundList":{"type":"object","properties":{"total":{"type":"integer"},"offset":{"type":"integer"},"limit":{"type":"integer"},"items":{"type":"array","items":{"$ref":"#/components/schemas/Media"}}},"required":["total","offset","limit","items"]},"PlayResult":{"type":"object","properties":{"title":{"type":"string","description":"Short title of what plays"},"text":{"type":"string","description":"Text to show or speak"},"playlist":{"type":"array","items":{"$ref":"#/components/schemas/Media"},"description":"Media to play, in order"},"delaySeconds":{"type":"integer","description":"Wait this long before playing (countdown, prank)"},"view":{"type":"string","enum":["clock"],"description":"Present on fart-time: show a clock"},"locale":{"type":"string"},"timezone":{"type":"string"},"suggestion":{"type":"string","description":"Another request the user might like"}},"required":["title","text","playlist","delaySeconds","locale","timezone","suggestion"]},"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]}}}}