Introduction

This documentation will help you get familiar with the resources of the Rick and Morty API and show you how to make different queries, so that you can get the most out of it.

GraphQL

https://rickandmortyapi.com/graphql/

Sample query

query {
  characters(page: 2, filter: { name: "rick" }) {
    info {
      count
    }
    results {
      name
    }
  }
  character(id: 1) {
    id
  }
}

Check here to know more about how to filter.

New to GraphQL? check the docs here

REST

Base url: https://rickandmortyapi.com/api/

The base url contains information about all available API's resources. All requests are GET requests and go over https. All responses will return data in json.

Sample request

https://rickandmortyapi.com/api/
{
  "characters": "https://rickandmortyapi.com/api/character",
  "locations": "https://rickandmortyapi.com/api/location",
  "episodes": "https://rickandmortyapi.com/api/episode"
}

There are currently three available resources:

  • Character: used to get all the characters.
  • Location: used to get all the locations.
  • Episode: used to get all the episodes.

Info and Pagination

The API will automatically paginate the responses. You will receive up to 20 documents per page.

Each resource contains an info object with information about the response.

KeyTypeDescription
countintThe length of the response
pagesintThe amount of pages
nextstring (url)Link to the next page (if it exists)
prevstring (url)Link to the previous page (if it exists)

Sample request

https://rickandmortyapi.com/api/character/
{
  "info": {
    "count": 394,
    "pages": 20,
    "next": "https://rickandmortyapi.com/api/character/?page=2",
    "prev": ""
  },
  "results": [
    // ...
  ]
}

You can access different pages with the page parameter. If you don't specify any page, the first page will be shown. For example, in order to access page 2, add ?page=2 to the end of the URL.

Sample request

https://rickandmortyapi.com/api/character/?page=19
{
  "info": {
    "count": 394,
    "pages": 20,
    "next": "https://rickandmortyapi.com/api/character/?page=20",
    "prev": "https://rickandmortyapi.com/api/character/?page=18"
  },
  "results": [
    {
      "id": 361,
      "name": "Toxic Rick",
      "status": "Dead",
      "species": "Humanoid",
      "type": "Rick's Toxic Side",
      "gender": "Male",
      "origin": {
        "name": "Alien Spa",
        "url": "https://rickandmortyapi.com/api/location/64"
      },
      "location": {
        "name": "Earth",
        "url": "https://rickandmortyapi.com/api/location/20"
      },
      "image": "https://rickandmortyapi.com/api/character/avatar/361.jpeg",
      "episode": [
        "https://rickandmortyapi.com/api/episode/27"
      ],
      "url": "https://rickandmortyapi.com/api/character/361",
      "created": "2018-01-10T18:20:41.703Z"
    },
    // ...
  ]
}

Character

There is a total of 591 characters sorted by id.

Character schema

KeyTypeDescription
idintThe id of the character.
namestringThe name of the character.
statusstringThe status of the character ('Alive', 'Dead' or 'unknown').
speciesstringThe species of the character.
typestringThe type or subspecies of the character.
genderstringThe gender of the character ('Female', 'Male', 'Genderless' or 'unknown').
originobjectName and link to the character's origin location.
locationobjectName and link to the character's last known location endpoint.
imagestring (url)Link to the character's image. All images are 300x300px and most are medium shots or portraits since they are intended to be used as avatars.
episodearray (urls)List of episodes in which this character appeared.
urlstring (url)Link to the character's own URL endpoint.
createdstringTime at which the character was created in the database.

Get all characters

You can access the list of characters by using the /character endpoint.

https://rickandmortyapi.com/api/character/
{
  "info": {
    "count": 394,
    "pages": 20,
    "next": "https://rickandmortyapi.com/api/character/?page=2",
    "prev": ""
  },
  "results": [
    {
      "id": 1,
      "name": "Rick Sanchez",
      "status": "Alive",
      "species": "Human",
      "type": "",
      "gender": "Male",
      "origin": {
        "name": "Earth",
        "url": "https://rickandmortyapi.com/api/location/1"
      },
      "location": {
        "name": "Earth",
        "url": "https://rickandmortyapi.com/api/location/20"
      },
      "image": "https://rickandmortyapi.com/api/character/avatar/1.jpeg",
      "episode": [
        "https://rickandmortyapi.com/api/episode/1",
        "https://rickandmortyapi.com/api/episode/2",
        // ...
      ],
      "url": "https://rickandmortyapi.com/api/character/1",
      "created": "2017-11-04T18:48:46.250Z"
    },
    // ...
  ]
}

Get a single character

You can get a single character by adding the id as a parameter: /character/2

https://rickandmortyapi.com/api/character/2
{
  "id": 2,
  "name": "Morty Smith",
  "status": "Alive",
  "species": "Human",
  "type": "",
  "gender": "Male",
  "origin": {
    "name": "Earth",
    "url": "https://rickandmortyapi.com/api/location/1"
  },
  "location": {
    "name": "Earth",
    "url": "https://rickandmortyapi.com/api/location/20"
  },
  "image": "https://rickandmortyapi.com/api/character/avatar/2.jpeg",
  "episode": [
    "https://rickandmortyapi.com/api/episode/1",
    "https://rickandmortyapi.com/api/episode/2",
    // ...
  ],
  "url": "https://rickandmortyapi.com/api/character/2",
  "created": "2017-11-04T18:50:21.651Z"
}

Get multiple characters

You can get multiple characters by adding an array of ids as parameter: /character/[1,2,3] or /character/1,2,3

https://rickandmortyapi.com/api/character/1,183
[
  {
    "id": 1,
    "name": "Rick Sanchez",
    "status": "Alive",
    "species": "Human",
    "type": "",
    "gender": "Male",
    "origin": {
      "name": "Earth (C-137)",
      "url": "https://rickandmortyapi.com/api/location/1"
    },
    "location": {
      "name": "Earth (Replacement Dimension)",
      "url": "https://rickandmortyapi.com/api/location/20"
    },
    "image": "https://rickandmortyapi.com/api/character/avatar/1.jpeg",
    "episode": [
      "https://rickandmortyapi.com/api/episode/1",
      "https://rickandmortyapi.com/api/episode/2",
      // ...
    ],
    "url": "https://rickandmortyapi.com/api/character/1",
    "created": "2017-11-04T18:48:46.250Z"
  },
  {
    "id": 183,
    "name": "Johnny Depp",
    "status": "Alive",
    "species": "Human",
    "type": "",
    "gender": "Male",
    "origin": {
      "name": "Earth (C-500A)",
      "url": "https://rickandmortyapi.com/api/location/23"
    },
    "location": {
      "name": "Earth (C-500A)",
      "url": "https://rickandmortyapi.com/api/location/23"
    },
    "image": "https://rickandmortyapi.com/api/character/avatar/183.jpeg",
    "episode": [
      "https://rickandmortyapi.com/api/episode/8"
    ],
    "url": "https://rickandmortyapi.com/api/character/183",
    "created": "2017-12-29T18:51:29.693Z"
  }
]

Filter characters

You can also include filters in the URL by including additional query parameters. To start filtering add a ? followed by the query <query>=<value>. If you want to chain several queries in the same call, use & followed by the query.

For example, If you want to check how many alive Ricks exist, just add ?name=rick&status=alive to the URL.

Available parameters:

  • name: filter by the given name.
  • status: filter by the given status (alive, dead or unknown).
  • species: filter by the given species.
  • type: filter by the given type.
  • gender: filter by the given gender (female, male, genderless or unknown).

Sample request

https://rickandmortyapi.com/api/character/?name=rick&status=alive

  "info": {
    "count": 15,
    "pages": 1,
    "next": "",
    "prev": ""
  },
  "results": [
    {
      "id": 1,
      "name": "Rick Sanchez",
      "status": "Alive",
      "species": "Human",
      "type": "",
      "gender": "Male",
      "origin": {
        "name": "Earth",
        "url": "https://rickandmortyapi.com/api/location/1"
      },
      "location": {
        "name": "Earth",
        "url": "https://rickandmortyapi.com/api/location/20"
      },
      "image": "https://rickandmortyapi.com/api/character/avatar/1.jpeg",
      "episode": [
        "https://rickandmortyapi.com/api/episode/1",
        "https://rickandmortyapi.com/api/episode/2",
        //...
      ],
      "url": "https://rickandmortyapi.com/api/character/1",
      "created": "2017-11-04T18:48:46.250Z"
    },
    // ...
  ]
}

Location

There is a total of 94 locations sorted by id.

Location schema

KeyTypeDescription
idintThe id of the location.
namestringThe name of the location.
typestringThe type of the location.
dimensionstringThe dimension in which the location is located.
residentsarray (urls)List of character who have been last seen in the location.
urlstring (url)Link to the location's own endpoint.
createdstringTime at which the location was created in the database.

Get all locations

You can access the list of locations by using the /location endpoint.

https://rickandmortyapi.com/api/location/

  "info": {
    "count": 67,
    "pages": 4,
    "next": "https://rickandmortyapi.com/api/location?page=2",
    "prev": ""
  },
  "results": [
    {
      "id": 1,
      "name": "Earth",
      "type": "Planet",
      "dimension": "Dimension C-137",
      "residents": [
        "https://rickandmortyapi.com/api/character/1",
        "https://rickandmortyapi.com/api/character/2",
        // ...
      ],
      "url": "https://rickandmortyapi.com/api/location/1",
      "created": "2017-11-10T12:42:04.162Z"
    }
    // ...
  ]
}

Get multiple locations

You can get multiple locations by adding an array of ids as parameter: /location/[1,2,3] or /location/1,2,3

https://rickandmortyapi.com/api/location/3,21
[
  {
    "id": 3,
    "name": "Citadel of Ricks",
    "type": "Space station",
    "dimension": "unknown",
    "residents": [
      "https://rickandmortyapi.com/api/character/8",
      "https://rickandmortyapi.com/api/character/14",
      // ...
    ],
    "url": "https://rickandmortyapi.com/api/location/3",
    "created": "2017-11-10T13:08:13.191Z"
  },
  {
    "id": 21,
    "name": "Testicle Monster Dimension",
    "type": "Dimension",
    "dimension": "Testicle Monster Dimension",
    "residents": [
      "https://rickandmortyapi.com/api/character/7",
      "https://rickandmortyapi.com/api/character/436"
    ],
    "url": "https://rickandmortyapi.com/api/location/21",
    "created": "2017-11-18T19:41:01.605Z"
  }
]

Get a single location

You can get a single location by adding the id as a parameter: /location/3

https://rickandmortyapi.com/api/location/3
{
  "id": 3,
  "name": "Citadel of Ricks",
  "type": "Space station",
  "dimension": "unknown",
  "residents": [
    "https://rickandmortyapi.com/api/character/8",
    "https://rickandmortyapi.com/api/character/14",
    // ...
  ],
  "url": "https://rickandmortyapi.com/api/location/3",
  "created": "2017-11-10T13:08:13.191Z"
}

Filter locations

Available parameters:

  • name: filter by the given name.
  • type: filter by the given type.
  • dimension: filter by the given dimension.

If you want to know how to use queries, check here

Sample request

https://rickandmortyapi.com/api/location/?name=earth

  "info": {
    "count": 18,
    "pages": 1,
    "next": "",
    "prev": ""
  },
  "results": [
    {
      "id": 1,
      "name": "Earth",
      "type": "Planet",
      "dimension": "Dimension C-137",
      "residents": [
        "https://rickandmortyapi.com/api/character/1",
        "https://rickandmortyapi.com/api/character/2",
        // ...
      ],
      "url": "https://rickandmortyapi.com/api/location/1",
      "created": "2017-11-10T12:42:04.162Z"
    },
    // ...
  ]
}

Episode

There is a total of 36 episodes sorted by id (which is of course the order of the episodes)

Episode schema

KeyTypeDescription
idintThe id of the episode.
namestringThe name of the episode.
air_datestringThe air date of the episode.
episodestringThe code of the episode.
charactersarray (urls)List of characters who have been seen in the episode.
urlstring (url)Link to the episode's own endpoint.
createdstringTime at which the episode was created in the database.

Get all episodes

You can access the list of episodes by using the /episode endpoint.

https://rickandmortyapi.com/api/episode/
{
  "info": {
    "count": 31,
    "pages": 2,
    "next": "https://rickandmortyapi.com/api/episode?page=2",
    "prev": ""
  },
  "results": [
    {
      "id": 1,
      "name": "Pilot",
      "air_date": "December 2, 2013",
      "episode": "S01E01",
      "characters": [
        "https://rickandmortyapi.com/api/character/1",
        "https://rickandmortyapi.com/api/character/2",
        //...
      ],
      "url": "https://rickandmortyapi.com/api/episode/1",
      "created": "2017-11-10T12:56:33.798Z"
    },
    // ...
  ]
}

Get a single episode

You can get a single episode by adding the id as a parameter: /episode/28

https://rickandmortyapi.com/api/episode/28
{
  "id": 28,
  "name": "The Ricklantis Mixup",
  "air_date": "September 10, 2017",
  "episode": "S03E07",
  "characters": [
    "https://rickandmortyapi.com/api/character/1",
    "https://rickandmortyapi.com/api/character/2",
    // ...
  ],
  "url": "https://rickandmortyapi.com/api/episode/28",
  "created": "2017-11-10T12:56:36.618Z"
}

Get multiple episodes

You can get multiple episodes by adding an array of ids as parameter: /episode/[1,2,3] or /episode/1,2,3

https://rickandmortyapi.com/api/episode/10,28
[
  {
    "id": 10,
    "name": "Close Rick-counters of the Rick Kind",
    "air_date": "April 7, 2014",
    "episode": "S01E10",
    "characters": [
      "https://rickandmortyapi.com/api/character/1",
      "https://rickandmortyapi.com/api/character/2",
      // ...
    ],
    "url": "https://rickandmortyapi.com/api/episode/10",
    "created": "2017-11-10T12:56:34.747Z"
  },
  {
    "id": 28,
    "name": "The Ricklantis Mixup",
    "air_date": "September 10, 2017",
    "episode": "S03E07",
    "characters": [
      "https://rickandmortyapi.com/api/character/1",
      "https://rickandmortyapi.com/api/character/2",
      // ...
    ],
    "url": "https://rickandmortyapi.com/api/episode/28",
    "created": "2017-11-10T12:56:36.618Z"
  }
]

Filter episodes

Available parameters:

  • name: filter by the given name.
  • episode: filter by the given episode code.

If you want to know how to use queries, check here

Libraries

Here you will find a list of helper libraries to use the Rick and Morty API with your preferred language.

Elixir

ExShla - The Rick and Morty API Wrapper by l1h3r

Go

The Rick and Morty API Go client by Leopoldo Caballero

Java

Rick and Morty API Java Client by Adriano Rocha

JavaScript

The Rick and Morty API JavaScript client by Simple Rick

.NET

RickAndMorty.Net.Api by Carlj28

Python

Python implementation for the Rick and Morty API by Rohan Hazra

R

mortyr by Mike Page

Ruby

The Rick and Morty API Gem by Tommy Spielhoelle

Swift

The Rick and Morty API Swift Client by Benjamin Bruch