# Mutations

[Mutations](https://graphql.org/learn/queries/#mutations) allow you to create, update, and delete data. All mutations require authentication, so you will need to [obtain an access token](https://github.com/AniList/ApiV2-GraphQL-Docs/blob/master/guide/auth/README.md) before you can use them.

::: tip Unlike queries, where you can exclude the `query` keyword, mutations require the `mutation` keyword. :::

The majority of our mutations have the following prefixes:

* `Save`: Create new or update existing data

  We usually determine if you would like to create or update data depending on if you provide an `id` or not.
* `Delete`: Delete data

  This will usually return a [`Deleted`](https://studio.apollographql.com/sandbox/schema/reference/objects/Deleted) object type. However, some mutations will return an updated version of the sibling data if this is more useful.
* `Toggle`: Toggle a boolean value

::: info Authorization needed In the examples below, you will also need to include your access token in the `Authorization` header of your request. For the sake of brevity, we will be skipping that step here. :::

## Create

Let's create a new media list entry on our user's list. We'll use [Cowboy Bebop](https://anilist.co/anime/1), which has an ID of `1`, as an example.

:::details Example Query [Apollo Studio](https://studio.apollographql.com/sandbox/explorer?endpoint=https%3A%2F%2Fgraphql.anilist.co\&explorerURLState=N4IgJg9gxgrgtgUwHYBcQC4RxighigSwiQAIAKAEgBsCBnFAUVQCcBPASTHRPdQBoSFRGAK5O3XigEV6%2BGLW4BZBCNwAZOigDKeFPICUJYAB1mx0iS24AbgmWqN9JijZkCXQTScsOYAcNFxQQCxPxJZPQVBCIMjU3MSRJJ3eItEmNpUxIBfVNyzJBA%2BEGtcZlEAIyoEWgwQEwLE4ywVQLBm7gBGPiySZoyOvpAAYQBVACVxhgA5ABVmvJBsoA)

::: code-group

<<< @/guide/snippets/graphql/mutations/create/php.php{php:line-numbers} \[PHP]

:::

The request in the above example will return the following JSON response:

```json
{
  "data": {
    "SaveMediaListEntry": {
        "id": 4,
        "status": "CURRENT"
    }
  }
}
```

Keep in mind that the `id` that was returned is the ID of the newly created list entry.

## Update

Using the `id` returned above, we can update the status of the list entry.

Note how the above mutation includes the `$listEntryId` variable, which is used to identify the list entry to update. It went unused in the example above, but we can make use of it now.

:::details Example Query [Apollo Studio](https://studio.apollographql.com/sandbox/explorer?endpoint=https%3A%2F%2Fgraphql.anilist.co\&explorerURLState=N4IgJg9gxgrgtgUwHYBcQC4RxighigSwiQAIAKAEgBsCBnFAUVQCcBPASTHRPdQBoSFRGAK5O3XigEV6%2BGLW4BZBCNwAZOigDKeFPICUJYAB1mx0iS24AbgmWqN9JijZkCXQTScsOYAcNFxQQCxPxJZPQVBCIMjU3MSRJJ3eItEmNpUxIBfVNyzJBA%2BEGtcZlEAIyoEWgwQEwLE4xAvRh9OZu4AFj4skmaMzv6QAGEAeUUABTUGABUGABFmvJBsoA)

If using the above studio link, you will need to replace the `listEntryId` variable with the ID returned from the previous mutation.

::: code-group

<<< @/guide/snippets/graphql/mutations/update/php.php{php:line-numbers} \[PHP]

:::

The request in the above example will return an identical response to the one above, but with the `status` field updated to `COMPLETED`.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://anilist.gitbook.io/anilist-apiv2-docs/docs/guide/graphql/mutations.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.