Documentation

Introduction

The Gumball API is a free, read-only REST API with data about The Amazing World of Gumball and The Wonderfully Weird World of Gumball. It serves characters, locations, episodes, seasons, songs, games and in-universe media as JSON.

There is no authentication, no API key and no sign-up. Every route is a GET request, so you can call it from a browser, a server or the terminal. Open any Try it panel on this page to send a real request and see the response.

Base URL

All requests start with the base URL below. Its root lists every available resource, which makes it a good first request.

Base URLhttps://gumball-api-server.vercel.app

GET/

Example response

{
  "name": "The Amazing World of Gumball API",
  "description": "A free, read-only REST API about The Amazing World of Gumball and The Wonderfully Weird World of Gumball. No authentication required.",
  "resources": {
    "characters": "/characters",
    "locations": "/locations",
    "episodes": "/episodes",
    "seasons": "/seasons",
    "songs": "/songs",
    "games": "/games",
    "media": "/media"
  }
}

Characters/characters
Locations/locations
Episodes/episodes
Seasons/seasons
Songs/songs
Games/games
Media/media

Rate limit and caching

Each IP address can make up to 100 requests per minute. Every response reports your current usage in the headers below. When the limit is reached, the API answers with 429 Too Many Requests until the window resets.

Header	Type	Description
X-RateLimit-Limit	integer	Requests allowed per minute.
X-RateLimit-Remaining	integer	Requests left in the current window.
X-RateLimit-Reset	integer	Seconds until the window resets.

Lists and single items are cached for 5 minutes with Cache-Control: public, so repeated requests are fast. Random routes are never cached. Please cache responses on your side whenever possible.

Info and pagination

List routes return 20 items per page by default. Use page and limit to move through the results. Besides the items in data, every list response includes meta with totals and links with ready-to-use paths to other pages.

Parameter	Type	Description
page	integer	The page to return, starting at 1.
limit	integer	Items per page, from 1 to 100. Defaults to 20.

Key	Type	Description
data	array	The items of the current page.
meta.page	integer	The current page, starting at 1.
meta.limit	integer	The number of items per page.
meta.totalItems	integer	The total number of items.
meta.totalPages	integer	The total number of pages.
meta.hasNextPage	boolean	Whether a next page exists.
meta.hasPreviousPage	boolean	Whether a previous page exists.
links.self	string	The path of the current page.
links.first	string	The path of the first page.
links.previous	string \| null	The path of the previous page, if any.
links.next	string \| null	The path of the next page, if any.
links.last	string	The path of the last page.

GET /characters?page=2&limit=2

{
  "data": [
    {
      "id": 3,
      "slug": "anais-watterson",
      "name": "Anais Watterson",
      "fullName": "Anais Watterson",
      "aliases": [
        "Jimmy",
        "Runtus Decepticus",
        "The Anaihilator",
        "Clever Girl",
        "Pink One"
      ],
      "description": "The youngest member of the Watterson family and, by far, its most intelligent. Despite being only four years old, she speaks with an advanced vocabulary and attends Elmore Junior High in a higher grade than her older brothers, Gumball and Darwin.",
      "species": "Rabbit",
      "gender": "female",
      "age": 4,
      "occupation": "Student",
      "role": "main",
      "status": "alive",
      "animationStyle": "2d",
      "voiceActors": [
        "Kyla Kowalewski",
        "Kinza Syed Khan"
      ],
      "firstAppearance": {
        "id": 1,
        "slug": "the-dvd",
        "title": "The DVD",
        "code": "S01E01",
        "url": "/episodes/1"
      },
      "colors": [
        "#f9b6ba",
        "#ffffff"
      ],
      "image": "https://arturbomtempo-dev.github.io/arturbomtempo-cdn/assets/images/projects/gumball-api/characters/anais-watterson.webp",
      "url": "/characters/3",
      "createdAt": "2026-09-30T03:52:12.603Z",
      "updatedAt": "2026-09-30T13:59:03.490Z"
    },
    {
      "id": 4,
      "slug": "nicole-watterson",
      "name": "Nicole Watterson",
      "fullName": "Nicole Watterson",
      "aliases": [
        "Nicole Senicourt",
        "Mom"
      ],
      "description": "The mother of the Watterson family and its only truly responsible member. She works hard to support her family, is fiercely devoted to keeping them safe, and has a famously explosive temper when pushed too far.",
      "species": "Cat",
      "gender": "female",
      "age": 38,
      "occupation": "Rainbow Factory employee",
      "role": "main",
      "status": "alive",
      "animationStyle": "2d",
      "voiceActors": [
        "Teresa Gallagher"
      ],
      "firstAppearance": {
        "id": 1,
        "slug": "the-dvd",
        "title": "The DVD",
        "code": "S01E01",
        "url": "/episodes/1"
      },
      "colors": [
        "#4bc5e5",
        "#f7f7f7",
        "#989377",
        "#3c5c61",
        "#d2d4d3"
      ],
      "image": "https://arturbomtempo-dev.github.io/arturbomtempo-cdn/assets/images/projects/gumball-api/characters/nicole-watterson.webp",
      "url": "/characters/4",
      "createdAt": "2026-09-30T03:52:12.603Z",
      "updatedAt": "2026-09-30T13:59:03.490Z"
    }
  ],
  "meta": {
    "page": 2,
    "limit": 2,
    "totalItems": 245,
    "totalPages": 123,
    "hasNextPage": true,
    "hasPreviousPage": true
  },
  "links": {
    "self": "/characters?page=2&limit=2",
    "first": "/characters?page=1&limit=2",
    "previous": "/characters?page=1&limit=2",
    "next": "/characters?page=3&limit=2",
    "last": "/characters?page=123&limit=2"
  }
}

Sorting

Use the sort parameter with a field name for ascending order, or prefix it with - for descending order. Items without a value for that field always come last. Each resource documents its sortable fields.

GET /characters?sort=-name
GET /episodes?sort=usAirDate

Filtering

Every list route accepts filters as query parameters, and they can be combined freely. A few rules apply to all resources:

search is a case-insensitive partial match on the name or title.
Enum values are lowercase and kebab-case, such as stop-motion or school-facility.
ids takes a comma-separated list, such as ids=1,2,3, to fetch several items at once.
Unknown or invalid parameters are rejected with 400 Bad Request, so typos never go unnoticed.

GET /characters?species=cat&status=alive&sort=name

Related resources

Resources link to each other with small reference objects instead of bare ids. Each reference includes a url with the path to the full item.

EpisodeReference

Key	Type	Description
id	integer	The id of the episode.
slug	string	The slug of the episode.
title	string	The title of the episode.
code	string \| null	Season and episode code, such as `S01E01`.
url	string	The path of the episode.

CharacterReference

Key	Type	Description
id	integer	The id of the character.
slug	string	The slug of the character.
name	string	The name of the character.
url	string	The path of the character.

LocationReference

Key	Type	Description
id	integer	The id of the location.
slug	string	The slug of the location.
name	string	The name of the location.
url	string	The path of the location.

Images

Images are served as WebP files from a public CDN through the image field of each item. They are high quality and most character images have a transparent background, so they work on any color.

Errors

Errors use standard HTTP status codes and always return the same JSON shape.

Key	Type	Description
statusCode	integer	The HTTP status code.
error	string	The HTTP status text.
message	string \| string[]	What went wrong. Validation errors list every problem.
path	string	The requested path.
timestamp	datetime	When the error happened.

GET /characters/9999

{
  "statusCode": 404,
  "error": "Not Found",
  "message": "Character with id 9999 not found",
  "path": "/characters/9999",
  "timestamp": "2026-10-01T12:00:00.000Z"
}

Status	Meaning
200	The request succeeded.
400	An id, slug or query parameter is invalid.
404	The item or route does not exist.
429	The rate limit was exceeded. Wait for the window to reset.
500	Something went wrong on our side.

Characters

Every named character of the series, from the Watterson family to the one-episode residents of Elmore.

245 characters available.

Character schema

Key	Type	Description
id	integer	The unique id of the character.
slug	string	A unique, URL-friendly identifier of the character.
name	string	The name the character is best known by.
fullName	string \| null	The full name, when known.
aliases	string[]	Nicknames and alternative names.
description	string \| null	A short description.
species	string \| null	The species or kind of being, such as `Cat` or `Fish`.
gender	enum	The gender of the character. male female other unknown
age	integer \| null	The age in years, when stated in the show.
occupation	string \| null	The main occupation.
role	enum	How important the character is to the series. main supporting minor
status	enum	Whether the character is alive. alive deceased undead unknown
animationStyle	enum	How the character is animated. 2d cgi stop-motion puppet live-action mixed-media other
voiceActors	string[]	The actors who voiced the character.
firstAppearance	EpisodeReference \| null	The episode where the character first appears.
colors	string[]	The main colors of the character, as hex codes.
image	string	URL of the character image (WebP).
url	string	The path of the character in the API, such as `/characters/1`.
createdAt	datetime	When the item was added to the API, in ISO 8601.
updatedAt	datetime	When the item was last updated, in ISO 8601.

Get all characters

Returns a paginated list of characters, 20 per page by default.

GET/characters

Parameter Type Description

page

integer

The page to return, starting at 1.

limit

integer

Items per page, from 1 to 100. Defaults to 20.

sort

string

Field to sort by. Prefix it with - for descending order. Defaults to id.

id
-id
name
-name
createdAt
-createdAt
updatedAt
-updatedAt

Get a single character

Returns one character by its numeric id.

GET/characters/{id}

Example response

{
  "id": 1,
  "slug": "gumball-watterson",
  "name": "Gumball Watterson",
  "fullName": "Gumball Tristopher Watterson",
  "aliases": [
    "Gummypuss",
    "G-Ball",
    "Zach"
  ],
  "description": "The protagonist of the series: a twelve-year-old blue cat who attends Elmore Junior High with his adoptive brother Darwin and his sister Anais. Energetic, impulsive and endlessly overconfident, he constantly gets his family into absurd situations, and he starts dating Penny as of \"The Shell.\"",
  "species": "Cat",
  "gender": "male",
  "age": 12,
  "occupation": "Student",
  "role": "main",
  "status": "alive",
  "animationStyle": "2d",
  "voiceActors": [
    "Logan Grove",
    "Jacob Hopkins",
    "Nicolas Cantu",
    "Duke Cutler",
    "Alkaio Thiele"
  ],
  "firstAppearance": {
    "id": 1,
    "slug": "the-dvd",
    "title": "The DVD",
    "code": "S01E01",
    "url": "/episodes/1"
  },
  "colors": [
    "#4ac2e4",
    "#ffffff",
    "#3e5156",
    "#f4d8b2"
  ],
  "image": "https://arturbomtempo-dev.github.io/arturbomtempo-cdn/assets/images/projects/gumball-api/characters/gumball-watterson.webp",
  "url": "/characters/1",
  "createdAt": "2026-09-30T03:52:12.603Z",
  "updatedAt": "2026-09-30T13:59:03.490Z"
}

Get a character by slug

Slugs are stable, human-readable identifiers, handy for URLs in your own app.

GET/characters/slug/{slug}

Get random characters

Returns an array of random characters. Random responses are never cached, so every request returns a new selection.

GET/characters/random

Parameter	Type	Description
count	integer	How many items to return, from 1 to 20. Defaults to 1.

Filter characters

Combine any of these query parameters with each other, with pagination and with sorting.

Parameter	Type	Description
search	string	Case-insensitive partial match on the name and full name.
species	string	Exact species, case-insensitive.
gender	enum	Filter by gender. male female other unknown
role	enum	Filter by role. main supporting minor
status	enum	Filter by status. alive deceased undead unknown
animationStyle	enum	Filter by animation style. 2d cgi stop-motion puppet live-action mixed-media other
voiceActor	string	Exact name of one of the voice actors.
firstAppearanceId	integer	Id of the episode where it first appears.
ids	integer[]	Comma-separated list of ids, up to 100.
sort	string	Field to sort by. Prefix it with `-` for descending order. Defaults to `id`. id -id name -name createdAt -createdAt updatedAt -updatedAt

GET /characters?species=cat&role=main

Locations

Places of the Gumball universe, organized in a hierarchy: a classroom belongs to a school, which belongs to Elmore.

112 locations available.

Location schema

Key	Type	Description
id	integer	The unique id of the location.
slug	string	A unique, URL-friendly identifier of the location.
name	string	The name of the location.
description	string \| null	A short description.
type	enum	The kind of place. town residence school school-facility shop restaurant business public-service leisure transport nature other-realm other
parent	LocationReference \| null	The location that contains this one.
firstAppearance	EpisodeReference \| null	The episode where the location first appears.
image	string	URL of the location image (WebP).
url	string	The path of the location in the API, such as `/locations/1`.
createdAt	datetime	When the item was added to the API, in ISO 8601.
updatedAt	datetime	When the item was last updated, in ISO 8601.

Get all locations

Returns a paginated list of locations, 20 per page by default.

GET/locations

Parameter Type Description

page

integer

The page to return, starting at 1.

limit

integer

Items per page, from 1 to 100. Defaults to 20.

sort

string

Field to sort by. Prefix it with - for descending order. Defaults to id.

id
-id
name
-name
createdAt
-createdAt
updatedAt
-updatedAt

Get a single location

Returns one location by its numeric id.

GET/locations/{id}

Example response

{
  "id": 1,
  "slug": "elmore",
  "name": "Elmore",
  "description": "The fictional California town where most of the series takes place, with an estimated \"weird\" population of 20,000. It works much like any other town, except that anything in it, from food to furniture, can come to life.",
  "type": "town",
  "parent": null,
  "firstAppearance": {
    "id": 1,
    "slug": "the-dvd",
    "title": "The DVD",
    "code": "S01E01",
    "url": "/episodes/1"
  },
  "image": "https://arturbomtempo-dev.github.io/arturbomtempo-cdn/assets/images/projects/gumball-api/locations/elmore.webp",
  "url": "/locations/1",
  "createdAt": "2026-09-30T04:25:12.603Z",
  "updatedAt": "2026-09-30T13:59:03.490Z"
}

Get a location by slug

Slugs are stable, human-readable identifiers, handy for URLs in your own app.

GET/locations/slug/{slug}

Get random locations

Returns an array of random locations. Random responses are never cached, so every request returns a new selection.

GET/locations/random

Parameter	Type	Description
count	integer	How many items to return, from 1 to 20. Defaults to 1.

Filter locations

Combine any of these query parameters with each other, with pagination and with sorting.

Parameter	Type	Description
search	string	Case-insensitive partial match on the name.
type	enum	Filter by type. town residence school school-facility shop restaurant business public-service leisure transport nature other-realm other
parentId	integer	Id of the parent location.
firstAppearanceId	integer	Id of the episode where it first appears.
ids	integer[]	Comma-separated list of ids, up to 100.
sort	string	Field to sort by. Prefix it with `-` for descending order. Defaults to `id`. id -id name -name createdAt -createdAt updatedAt -updatedAt

GET /locations?type=school-facility

Episodes

All episodes, specials, shorts and pilots, with air dates, credits and links to the previous and next episode.

305 episodes available.

Episode schema

Key	Type	Description
id	integer	The unique id of the episode.
slug	string	A unique, URL-friendly identifier of the episode.
title	string	The title of the episode.
description	string \| null	A short synopsis.
series	enum	The series the episode belongs to. amazing-world wonderfully-weird-world
type	enum	The kind of episode. episode special short pilot film
status	enum	Whether the episode was released. released unreleased scrapped
season	integer \| null	The season number.
episodeNumber	integer \| null	The number of the episode within its season.
overallNumber	integer \| null	The number of the episode across the whole series.
code	string \| null	Season and episode code, such as `S01E01`.
productionCode	string \| null	The production code.
usAirDate	date \| null	First US air date.
ukAirDate	date \| null	First UK air date.
writers	string[]	The writers of the episode.
storyboardArtists	string[]	The storyboard artists of the episode.
previous	EpisodeReference \| null	The previous episode in order.
next	EpisodeReference \| null	The next episode in order.
image	string	URL of the episode image (WebP).
url	string	The path of the episode in the API, such as `/episodes/1`.
createdAt	datetime	When the item was added to the API, in ISO 8601.
updatedAt	datetime	When the item was last updated, in ISO 8601.

Get all episodes

Returns a paginated list of episodes, 20 per page by default.

GET/episodes

Parameter Type Description

page

integer

The page to return, starting at 1.

limit

integer

Items per page, from 1 to 100. Defaults to 20.

sort

string

Field to sort by. Prefix it with - for descending order. Defaults to id.

id
-id
title
-title
overallNumber
-overallNumber
usAirDate
-usAirDate
createdAt
-createdAt
updatedAt
-updatedAt

Get a single episode

Returns one episode by its numeric id.

GET/episodes/{id}

Example response

{
  "id": 1,
  "slug": "the-dvd",
  "title": "The DVD",
  "description": "Gumball and Darwin will do anything to avoid paying the late fee on an overdue DVD, no matter how extreme their schemes get.",
  "series": "amazing-world",
  "type": "episode",
  "status": "released",
  "season": 1,
  "episodeNumber": 1,
  "overallNumber": 1,
  "code": "S01E01",
  "productionCode": null,
  "usAirDate": "2011-05-03",
  "ukAirDate": "2011-09-05",
  "writers": [
    "Ben Bocquelet",
    "Jon Foster",
    "James Lamont"
  ],
  "storyboardArtists": [
    "Benjamin Marsaud"
  ],
  "previous": null,
  "next": {
    "id": 2,
    "slug": "the-responsible",
    "title": "The Responsible",
    "code": "S01E02",
    "url": "/episodes/2"
  },
  "image": "https://arturbomtempo-dev.github.io/arturbomtempo-cdn/assets/images/projects/gumball-api/episodes/the-dvd.webp",
  "url": "/episodes/1",
  "createdAt": "2026-09-30T05:03:47.171Z",
  "updatedAt": "2026-09-30T05:03:47.171Z"
}

Get an episode by slug

Slugs are stable, human-readable identifiers, handy for URLs in your own app.

GET/episodes/slug/{slug}

Get random episodes

Returns an array of random episodes. Random responses are never cached, so every request returns a new selection.

GET/episodes/random

Parameter	Type	Description
count	integer	How many items to return, from 1 to 20. Defaults to 1.

Filter episodes

Combine any of these query parameters with each other, with pagination and with sorting.

Parameter	Type	Description
search	string	Case-insensitive partial match on the title.
series	enum	Filter by series. amazing-world wonderfully-weird-world
type	enum	Filter by type. episode special short pilot film
status	enum	Filter by status. released unreleased scrapped
season	integer	Season number.
writer	string	Exact name of one of the writers.
storyboardArtist	string	Exact name of one of the storyboard artists.
airedFrom	date	Aired in the US on or after this date (`YYYY-MM-DD`).
airedTo	date	Aired in the US on or before this date (`YYYY-MM-DD`).
ids	integer[]	Comma-separated list of ids, up to 100.
sort	string	Field to sort by. Prefix it with `-` for descending order. Defaults to `id`. id -id title -title overallNumber -overallNumber usAirDate -usAirDate createdAt -createdAt updatedAt -updatedAt

GET /episodes?season=1&sort=-usAirDate

Seasons

The six seasons of The Amazing World of Gumball and the seasons of The Wonderfully Weird World of Gumball.

8 seasons available.

Season schema

Key	Type	Description
id	integer	The unique id of the season.
slug	string	A unique, URL-friendly identifier of the season.
number	integer	The season number across both series.
title	string	The title of the season.
description	string \| null	A short overview.
series	enum	The series the season belongs to. amazing-world wonderfully-weird-world
seriesSeasonNumber	integer	The season number within its series.
status	enum	Whether the season is completed, airing or upcoming. completed airing upcoming
episodeCount	integer \| null	The planned number of episodes.
releasedEpisodeCount	integer	The number of episodes already released.
networks	string[]	The networks that aired it.
usPremiereDate	date \| null	US premiere date.
usFinaleDate	date \| null	US finale date.
ukPremiereDate	date \| null	UK premiere date.
ukFinaleDate	date \| null	UK finale date.
episodes	string	Path that lists the episodes of the season.
image	string	URL of the season image (WebP).
url	string	The path of the season in the API, such as `/seasons/1`.
createdAt	datetime	When the item was added to the API, in ISO 8601.
updatedAt	datetime	When the item was last updated, in ISO 8601.

Get all seasons

Returns a paginated list of seasons, 20 per page by default.

GET/seasons

Parameter Type Description

page

integer

The page to return, starting at 1.

limit

integer

Items per page, from 1 to 100. Defaults to 20.

sort

string

Field to sort by. Prefix it with - for descending order. Defaults to number.

id
-id
number
-number
title
-title
usPremiereDate
-usPremiereDate
createdAt
-createdAt
updatedAt
-updatedAt

Get a single season

Returns one season by its numeric id.

GET/seasons/{id}

Example response

{
  "id": 1,
  "slug": "season-1",
  "number": 1,
  "title": "Season 1",
  "description": "The debut season of The Amazing World of Gumball, introducing Gumball, Darwin and the rest of the Watterson family. It premiered in the US on May 3, 2011 with \"The DVD\" and wrapped up 36 episodes later with \"The Fight.\"",
  "series": "amazing-world",
  "seriesSeasonNumber": 1,
  "status": "completed",
  "episodeCount": 36,
  "releasedEpisodeCount": 36,
  "networks": [
    "Cartoon Network"
  ],
  "usPremiereDate": "2011-05-03",
  "usFinaleDate": "2012-03-13",
  "ukPremiereDate": "2011-09-05",
  "ukFinaleDate": "2012-04-01",
  "episodes": "/episodes?season=1",
  "image": "https://arturbomtempo-dev.github.io/arturbomtempo-cdn/assets/images/projects/gumball-api/seasons/season-1.webp",
  "url": "/seasons/1",
  "createdAt": "2026-09-30T13:34:03.707Z",
  "updatedAt": "2026-09-30T13:34:03.707Z"
}

Get a season by slug

Slugs are stable, human-readable identifiers, handy for URLs in your own app.

GET/seasons/slug/{slug}

Get random seasons

Returns an array of random seasons. Random responses are never cached, so every request returns a new selection.

GET/seasons/random

Parameter	Type	Description
count	integer	How many items to return, from 1 to 10. Defaults to 1.

Filter seasons

Combine any of these query parameters with each other, with pagination and with sorting.

Parameter	Type	Description
search	string	Case-insensitive partial match on the title.
series	enum	Filter by series. amazing-world wonderfully-weird-world
status	enum	Filter by status. completed airing upcoming
ids	integer[]	Comma-separated list of ids, up to 100.
sort	string	Field to sort by. Prefix it with `-` for descending order. Defaults to `number`. id -id number -number title -title usPremiereDate -usPremiereDate createdAt -createdAt updatedAt -updatedAt

GET /seasons?series=amazing-world

Songs

Songs performed in the show, from the opening theme to the musical numbers of each episode.

156 songs available.

Song schema

Key	Type	Description
id	integer	The unique id of the song.
slug	string	A unique, URL-friendly identifier of the song.
title	string	The title of the song.
description	string \| null	A short description.
type	enum	The kind of song. episode theme web
episode	EpisodeReference \| null	The episode where the song is performed.
characters	CharacterReference[]	The characters who sing it.
vocalists	string[]	The real-world vocalists.
genres	string[]	Musical genres.
duration	string \| null	Duration formatted as `m:ss`.
durationSeconds	integer \| null	Duration in seconds.
musicalKey	string \| null	The musical key.
image	string \| null	URL of the song image (WebP).
url	string	The path of the song in the API, such as `/songs/1`.
createdAt	datetime	When the item was added to the API, in ISO 8601.
updatedAt	datetime	When the item was last updated, in ISO 8601.

Get all songs

Returns a paginated list of songs, 20 per page by default.

GET/songs

Parameter Type Description

page

integer

The page to return, starting at 1.

limit

integer

Items per page, from 1 to 100. Defaults to 20.

sort

string

Field to sort by. Prefix it with - for descending order. Defaults to id.

id
-id
title
-title
durationSeconds
-durationSeconds
createdAt
-createdAt
updatedAt
-updatedAt

Get a single song

Returns one song by its numeric id.

GET/songs/{id}

Example response

{
  "id": 1,
  "slug": "opening-theme",
  "title": "Opening theme",
  "description": "The theme song of the series. Most countries air the full introduction, while the United States usually airs a shortened version. The Wonderfully Weird World of Gumball introduced a new version.",
  "type": "theme",
  "episode": {
    "id": 1,
    "slug": "the-dvd",
    "title": "The DVD",
    "code": "S01E01",
    "url": "/episodes/1"
  },
  "characters": [],
  "vocalists": [],
  "genres": [],
  "duration": "0:20",
  "durationSeconds": 20,
  "musicalKey": "G major",
  "image": "https://arturbomtempo-dev.github.io/arturbomtempo-cdn/assets/images/projects/gumball-api/songs/opening-theme.webp",
  "url": "/songs/1",
  "createdAt": "2026-09-30T13:47:38.110Z",
  "updatedAt": "2026-09-30T13:47:38.110Z"
}

Get a song by slug

Slugs are stable, human-readable identifiers, handy for URLs in your own app.

GET/songs/slug/{slug}

Get random songs

Returns an array of random songs. Random responses are never cached, so every request returns a new selection.

GET/songs/random

Parameter	Type	Description
count	integer	How many items to return, from 1 to 20. Defaults to 1.

Filter songs

Combine any of these query parameters with each other, with pagination and with sorting.

Parameter	Type	Description
search	string	Case-insensitive partial match on the title.
type	enum	Filter by type. episode theme web
episodeId	integer	Id of the episode.
season	integer	Season number of the episode.
characterId	integer	Id of a character who sings it.
vocalist	string	Exact name of one of the vocalists.
genre	string	Exact name of one of the genres.
ids	integer[]	Comma-separated list of ids, up to 100.
sort	string	Field to sort by. Prefix it with `-` for descending order. Defaults to `id`. id -id title -title durationSeconds -durationSeconds createdAt -createdAt updatedAt -updatedAt

GET /songs?characterId=1&sort=-durationSeconds

Games

Official games set exclusively in the Gumball universe, from browser games to mobile apps.

81 games available.

Game schema

Key	Type	Description
id	integer	The unique id of the game.
slug	string	A unique, URL-friendly identifier of the game.
title	string	The title of the game.
description	string \| null	A short description.
platforms	enum[]	The platforms the game was released on. web mobile roblox voice-assistant
status	enum	Whether the game is still available. available discontinued unknown
releaseDate	date \| null	The release date.
releaseYear	integer \| null	The release year.
developers	string[]	The studios behind the game.
image	string	URL of the game image (WebP).
url	string	The path of the game in the API, such as `/games/1`.
createdAt	datetime	When the item was added to the API, in ISO 8601.
updatedAt	datetime	When the item was last updated, in ISO 8601.

Get all games

Returns a paginated list of games, 20 per page by default.

GET/games

Parameter Type Description

page

integer

The page to return, starting at 1.

limit

integer

Items per page, from 1 to 100. Defaults to 20.

sort

string

Field to sort by. Prefix it with - for descending order. Defaults to id.

id
-id
title
-title
releaseDate
-releaseDate
createdAt
-createdAt
updatedAt
-updatedAt

Get a single game

Returns one game by its numeric id.

GET/games/{id}

Example response

{
  "id": 1,
  "slug": "school-house-rush",
  "title": "School House Rush",
  "description": "A 2D side-scrolling platformer in which Gumball and Darwin save students trapped in a flooded Elmore Junior High and fix the broken pipe outside.",
  "platforms": [
    "web"
  ],
  "status": "discontinued",
  "releaseDate": "2012-01-30",
  "releaseYear": 2012,
  "developers": [],
  "image": "https://arturbomtempo-dev.github.io/arturbomtempo-cdn/assets/images/projects/gumball-api/games/school-house-rush.webp",
  "url": "/games/1",
  "createdAt": "2026-09-30T16:15:16.273Z",
  "updatedAt": "2026-09-30T16:15:16.273Z"
}

Get a game by slug

Slugs are stable, human-readable identifiers, handy for URLs in your own app.

GET/games/slug/{slug}

Get random games

Returns an array of random games. Random responses are never cached, so every request returns a new selection.

GET/games/random

Parameter	Type	Description
count	integer	How many items to return, from 1 to 20. Defaults to 1.

Filter games

Combine any of these query parameters with each other, with pagination and with sorting.

Parameter	Type	Description
search	string	Case-insensitive partial match on the title.
platform	enum	Filter by platform. web mobile roblox voice-assistant
status	enum	Filter by status. available discontinued unknown
developer	string	Exact name of one of the developers.
releaseYear	integer	Release year.
ids	integer[]	Comma-separated list of ids, up to 100.
sort	string	Field to sort by. Prefix it with `-` for descending order. Defaults to `id`. id -id title -title releaseDate -releaseDate createdAt -createdAt updatedAt -updatedAt

GET /games?platform=mobile&status=available

Media

Movies, shows, books and games that exist inside the Gumball universe, many of them parodies of real ones.

16 media items available.

Media schema

Key	Type	Description
id	integer	The unique id of the media item.
slug	string	A unique, URL-friendly identifier of the media item.
title	string	The title of the media item.
description	string \| null	A short description.
type	enum	The kind of media. tv-show movie comic book app video-game video
parodyOf	string \| null	The real-world work it parodies.
firstAppearance	EpisodeReference \| null	The episode where it first appears.
image	string	URL of the media image (WebP).
url	string	The path of the media item in the API, such as `/media/1`.
createdAt	datetime	When the item was added to the API, in ISO 8601.
updatedAt	datetime	When the item was last updated, in ISO 8601.

Get all media

Returns a paginated list of media items, 20 per page by default.

GET/media

Parameter Type Description

page

integer

The page to return, starting at 1.

limit

integer

Items per page, from 1 to 100. Defaults to 20.

sort

string

Field to sort by. Prefix it with - for descending order. Defaults to id.

id
-id
title
-title
createdAt
-createdAt
updatedAt
-updatedAt

Get a single media item

Returns one media item by its numeric id.

GET/media/{id}

Example response

{
  "id": 1,
  "slug": "alligators-on-a-train",
  "title": "Alligators on a Train",
  "description": "The action movie Nicole rents from Laser Video in \"The DVD.\" After Gumball accidentally ruins the disc, he and Darwin try to remake the entire film themselves to avoid paying the late fee.",
  "type": "movie",
  "parodyOf": "Snakes on a Plane",
  "firstAppearance": {
    "id": 1,
    "slug": "the-dvd",
    "title": "The DVD",
    "code": "S01E01",
    "url": "/episodes/1"
  },
  "image": "https://arturbomtempo-dev.github.io/arturbomtempo-cdn/assets/images/projects/gumball-api/in-universe-media/alligators-on-a-train.webp",
  "url": "/media/1",
  "createdAt": "2026-10-01T00:54:23.135Z",
  "updatedAt": "2026-10-01T00:54:23.135Z"
}

Get a media item by slug

Slugs are stable, human-readable identifiers, handy for URLs in your own app.

GET/media/slug/{slug}

Get random media

Returns an array of random media items. Random responses are never cached, so every request returns a new selection.

GET/media/random

Parameter	Type	Description
count	integer	How many items to return, from 1 to 20. Defaults to 1.

Filter media

Combine any of these query parameters with each other, with pagination and with sorting.

Parameter	Type	Description
search	string	Case-insensitive partial match on the title.
type	enum	Filter by type. tv-show movie comic book app video-game video
firstAppearanceId	integer	Id of the episode where it first appears.
ids	integer[]	Comma-separated list of ids, up to 100.
sort	string	Field to sort by. Prefix it with `-` for descending order. Defaults to `id`. id -id title -title createdAt -createdAt updatedAt -updatedAt

GET /media?type=movie