Mr Farts REST API | Fart Sounds

Version 1.0.0 · Last updated: 9 October 2026 · Publisher: HUGO FM GAMES (hugo.fm)

Overview

https://fart.shoutoutgames.com/v1

Authentication	None. No sign-in, account or API key.
Format	JSON in and out. Send request bodies with `Content-Type: application/json`.
Specification	OpenAPI 3.1: `https://fart.shoutoutgames.com/v1/openapi.json`
Price	Free. Every sound, song and cartoon is free.
State	Stateless. Nothing is stored between requests.
Browsers	CORS is open (`Access-Control-Allow-Origin: *`), so web pages on any site can call the API.
Languages	Titles and text in English, German, French and Spanish: pass `locale` as `en-US`, `de-DE`, `fr-FR` or `es-ES`.
Media	Pre-recorded MP3 and MP4 files and thumbnail images, linked under `https://fart.shoutoutgames.com/media/`. Nothing is AI-generated.

The API has two kinds of endpoint. Catalogue endpoints (GET) list what exists. Action endpoints (POST) pick something to play, the same way our Alexa skill and MCP server do, and return the text to say and a playlist.

Quick start

Ask for a wet fart:

curl -s https://fart.shoutoutgames.com/v1/fart \
  -H 'Content-Type: application/json' \
  -d '{"selection":"wet"}'

{
  "title": "Wet",
  "text": "Here comes Wet fart!",
  "playlist": [
    {
      "id": "sounds:24",
      "title": "Wet",
      "category": "sounds",
      "audioUrl": "https://fart.shoutoutgames.com/media/farts/24.mp3",
      "videoUrl": "https://fart.shoutoutgames.com/media/short-vid-farts/24.mp4"
    }
  ],
  "delaySeconds": 0,
  "locale": "en-US",
  "timezone": "UTC",
  "suggestion": "Play a wet fart!"
}

Show or say text, then play the audioUrl. That's it.

All endpoints

Endpoint	What it does
GET `/v1/categories`	Lists the 8 packs and how many items each has.
GET `/v1/sounds`	Searches the catalogue, or lists a whole pack.
GET `/v1/sounds/{id}`	Gets one item by its ID.
POST `/v1/fart`	A fart: random, named, an animal, a seasonal pack, extreme, the fart of the day, a name joke, or up to 100 in a row.
POST `/v1/music`	A Mr Farts song.
POST `/v1/cartoon`	A Mr Farts cartoon video.
POST `/v1/countdown`	A fart after a countdown of 1 to 1,800 seconds.
POST `/v1/fart-time`	Tells the time in farts.
POST `/v1/weather`	The windy-weather joke. Not a real forecast.
POST `/v1/prank`	The "come closer" prank.
GET `/v1`	Lists the endpoints and links to these docs.
GET `/v1/openapi.json`	The OpenAPI 3.1 specification.

Catalogue

Catalogue responses can be cached for 5 minutes (Cache-Control: public, max-age=300).

GET/v1/categories

Query: optional locale.

{
  "categories": [
    { "id": "sounds", "title": "Fart sounds", "count": 145 },
    { "id": "animal", "title": "Animal farts", "count": 30 },
    { "id": "music", "title": "Mr Farts songs", "count": 61 },
    { "id": "cartoon", "title": "Mr Farts cartoons", "count": 10 },
    { "id": "christmas", "title": "Christmas farts", "count": 22 },
    { "id": "easter", "title": "Easter farts", "count": 11 },
    { "id": "halloween", "title": "Halloween farts", "count": 8 },
    { "id": "valentine", "title": "Valentine's Day farts", "count": 11 }
  ]
}

GET/v1/sounds

Query	Type	Notes
`category`	`sounds`, `animal`, `music`, `cartoon`, `christmas`, `easter`, `halloween` or `valentine`	Limits the search to one pack.
`query`	string, up to 150 characters	Search text. Empty lists the whole pack (or everything).
`locale`	string	Language for titles and for matching names.
`offset`	integer, 0 to 1000	Default 0.
`limit`	integer, 1 to 100	Default 30.

curl -s 'https://fart.shoutoutgames.com/v1/sounds?query=wet&limit=2'

{
  "total": 4,
  "offset": 0,
  "limit": 2,
  "items": [
    {
      "id": "sounds:24",
      "title": "Wet",
      "category": "sounds",
      "audioUrl": "https://fart.shoutoutgames.com/media/farts/24.mp3",
      "videoUrl": "https://fart.shoutoutgames.com/media/short-vid-farts/24.mp4"
    },
    {
      "id": "sounds:23",
      "title": "Wet and Squeaky",
      "category": "sounds",
      "audioUrl": "https://fart.shoutoutgames.com/media/farts/23.mp3",
      "videoUrl": "https://fart.shoutoutgames.com/media/short-vid-farts/23.mp4"
    }
  ]
}

GET/v1/sounds/{id}

Returns one Media item, or 404 not_found. Query: optional locale.

curl -s https://fart.shoutoutgames.com/v1/sounds/cartoon:1

{
  "id": "cartoon:1",
  "title": "The Train Driver",
  "category": "cartoon",
  "videoUrl": "https://fart.shoutoutgames.com/media/cartoon/Train.mp4",
  "imageUrl": "https://fart.shoutoutgames.com/media/Images/cartoon-thumbnails/Train.jpg"
}

Actions

Every action is a POST with an optional JSON body and returns a PlayResult. Results are random where the request allows it, so they are never cached (Cache-Control: no-store). Every body field is optional, and unknown fields are rejected with 400 invalid_request.

Two fields work on every action:

Field	Type	Notes
`locale`	string, up to 20 characters	`en-US` (default), `de-DE`, `fr-FR` or `es-ES`.
`timezone`	string, up to 80 characters	An IANA name such as `Europe/London`. Default `UTC`. Used by fart time and the fart of the day.

POST/v1/fart

Field	Type	Notes
`selection`	string, 1 to 150 characters	A catalogue ID such as `sounds:24`, or a name such as `wet` or `cow`. Unknown names play a random fart. Omit for a random fart.
`category`	a pack ID	Pick from one pack, for example `animal` or `halloween`.
`personName`	string, 1 to 100 characters	A first name for the name joke, for example "James Just Does Big Juicy Wet Ones".
`mode`	`random`, `extreme` or `daily`	`daily` is the fart of the day, chosen from the date in `timezone`.
`count`	integer, 1 to 100	How many farts in a row. Default 1.

curl -s https://fart.shoutoutgames.com/v1/fart \
  -H 'Content-Type: application/json' \
  -d '{"category":"animal","selection":"cow"}'

POST/v1/music

Field: selection (a song title or ID such as music:4). Omit it for a random song.

{
  "title": "Disco Farts",
  "text": "Now Playing Disco Farts",
  "playlist": [
    {
      "id": "music:4",
      "title": "Disco Farts",
      "category": "music",
      "audioUrl": "https://fart.shoutoutgames.com/media/fartMusicClipped/4.mp3",
      "imageUrl": "https://fart.shoutoutgames.com/media/Images/musicImages/4.png"
    }
  ],
  "delaySeconds": 0,
  "locale": "en-US",
  "timezone": "UTC",
  "suggestion": "Fart in 10 seconds!"
}

POST/v1/cartoon

Field: selection (a cartoon title or ID such as cartoon:1). Omit it for a random cartoon. Cartoons have a videoUrl and an imageUrl, and no audio file.

POST/v1/countdown

Field: seconds, an integer from 1 to 1,800 (default 60). Wait delaySeconds, then play.

{
  "title": "10s",
  "text": "Farting will start in 10 seconds.",
  "playlist": [
    {
      "id": "sounds:38",
      "title": "Countdown Selection",
      "category": "sounds",
      "audioUrl": "https://fart.shoutoutgames.com/media/farts/38.mp3"
    }
  ],
  "delaySeconds": 10,
  "locale": "en-US",
  "timezone": "UTC",
  "suggestion": "Do 50 farts in a row!"
}

POST/v1/fart-time

Tells the current time with one fart per hour. Pass timezone, or you get UTC. The result has "view": "clock", so you can show a clock with the title (for example 10:19).

POST/v1/weather

The Mr Farts windy-weather joke: a short forecast for "your location" that is always windy, with fart sounds. It does not look up real weather or use your location.

POST/v1/prank

The "come closer" prank. Show or say text, wait delaySeconds (2), then play.

Playing a result

Show or say text.
Wait delaySeconds (0 for most actions).
Play the playlist items in order. Use audioUrl for sound only, or videoUrl where you can show video. Cartoons only have video.
Optionally offer suggestion as a next request.

PlayResult

Field	Type	Notes
`title`	string	Short title of what plays.
`text`	string	Plain text to show or speak, in the requested language.
`playlist`	array of Media	What to play, in order. At least one item.
`delaySeconds`	integer	Seconds to wait before playing.
`view`	`clock`	Only on fart time.
`locale`, `timezone`	string	The language and timezone used.
`suggestion`	string	Another request the user might like, such as "Play a wet fart!"

Media

Field	Type	Notes
`id`	string	Catalogue ID, such as `sounds:24`. Joke and sequence clips have IDs like `clip:0` or `sequence:20`.
`title`	string	Display name.
`category`	string	The pack it belongs to.
`audioUrl`	URL, optional	MP3.
`videoUrl`	URL, optional	MP4.
`imageUrl`	URL, optional	Thumbnail for songs and cartoons.

Errors and limits

Errors return JSON with a code and a readable message:

{
  "error": {
    "code": "invalid_request",
    "message": "count: Too big: expected number to be <=100"
  }
}

Status	Code	Meaning
`400`	`invalid_request`	A field is the wrong type, out of range or unknown, or the timezone is not a valid IANA name. The message names the field.
`400`	`invalid_json`	The body is not valid JSON.
`404`	`not_found`	Unknown item ID or endpoint.
`405`	`method_not_allowed`	Actions need `POST`. The `Allow` header says which methods work.
`413`	`too_large`	The body is over 10 KB.
`500`	`server_error`	Something went wrong on our side. Retry.

Unknown sound, song or cartoon names are not errors: a random item from that pack plays, and the result names what played.

Media links are cached by Cloudflare and limited to 10 requests per second, with a burst of 40. Over that, they return HTTP 429.
Request body: 10 KB.

Data and privacy

Stored: nothing. The API keeps no sessions, and a first name sent in personName is used for that response only.
Logs: our app logs the endpoint, status and duration of each request, never request bodies or query strings. Web server access logs (IP address, time, the address requested and client details) rotate daily and are kept for about 14 days.
Hosting: DigitalOcean behind Cloudflare.
Not collected: accounts, email, location, contacts, payment details, microphone or camera. No cookies.

Full details: Privacy policy.

Support

Questions and bug reports: hugo.fm/contact.

The Mr Farts API is published by HUGO FM GAMES, a trading name of HUGO.FM Games Limited (company no. 14615936) (hugo.fm). Terms of use.