### Example: Thumbnail URLs

Source: https://api.mangadex.org/docs/03-manga/covers

Examples showing the constructed URLs for 256px and 512px thumbnail versions of a specific manga cover.

```url
https://uploads.mangadex.org/covers/8f3e1818-a015-491d-bd81-3addc4d7d56a/26dd2770-d383-42e9-a42b-32765a4d99c8.png.256.jpg
```

```url
https://uploads.mangadex.org/covers/8f3e1818-a015-491d-bd81-3addc4d7d56a/26dd2770-d383-42e9-a42b-32765a4d99c8.png.512.jpg
```

--------------------------------

### Query Parameter Examples

Source: https://api.mangadex.org/docs/04-chapter/search

Examples demonstrating the usage of query parameters for filtering chapter results.

```APIDOC
## Examples

### Show only future published chapters
```
/manga/{id}/feed?includeFuturePublishAt=1
```

### Show only past published chapters
```
/manga/{id}/feed?includeFuturePublishAt=0
```

### Show future published chapters and no external URLs
```
/manga/{id}/feed?includeFuturePublishAt=1&includeExternalUrl=0
```
```

--------------------------------

### Basic Python Hello World Example

Source: https://api.mangadex.org/docs/contributing

A simple 'Hello, World!' example in Python, demonstrating the expected format for code blocks.

```python
print("Hello, World!")
```

--------------------------------

### Example: Full Cover URL

Source: https://api.mangadex.org/docs/03-manga/covers

An example demonstrating the full URL for a specific manga cover, including its ID and filename.

```url
https://uploads.mangadex.org/covers/8f3e1818-a015-491d-bd81-3addc4d7d56a/26dd2770-d383-42e9-a42b-32765a4d99c8.png
```

--------------------------------

### MangaDex@Home Report Example: Success

Source: https://api.mangadex.org/docs/04-chapter/retrieving-chapter

Example of reporting a successful image retrieval. Ensure all fields are accurately populated.

```http
POST https://api.mangadex.network/report
Content-Type: application/json

{
  "url": "https://foo.bar:5678/abcdef/1a2b3c4d/data/3303dd03ac8d27452cce3f2a882e94b2/2-2a5e95dfec7f15cd01f9a63835be18a22fb77a10fd2d62858c7dcbb6e6c622f9.png",
  "success": true,
  "bytes": 674687,
  "duration": 235,
  "cached": true
}
```

--------------------------------

### Authenticate with Username and Password (Python)

Source: https://api.mangadex.org/docs/02-authentication/personal-clients

Python example using the requests library to authenticate with MangaDex using username and password.

```python
import requests

creds = {
    "grant_type": "password",
    "username": "<your_username>",
    "password": "<your_password>",
    "client_id": "<your_client_id>",
    "client_secret": "<your_client_secret>"
}

r = requests.post(
    "https://auth.mangadex.org/realms/mangadex/protocol/openid-connect/token",
    data=creds
)
r_json = r.json()

access_token = r_json["access_token"]
refresh_token = r_json["refresh_token"]

print(access_token, refresh_token)
```

--------------------------------

### MangaDex@Home Report Example: Failure

Source: https://api.mangadex.org/docs/04-chapter/retrieving-chapter

Example of reporting a failed image retrieval. For connection failures, set bytes to 0.

```http
POST https://api.mangadex.network/report
Content-Type: application/json

{
  "url": "https://foo.bar:5678/abcdef/1a2b3c4d/data/3303dd03ac8d27452cce3f2a882e94b2/2-2a5e95dfec7f15cd01f9a63835be18a22fb77a10fd2d62858c7dcbb6e6c622f9.png",
  "success": false,
  "bytes": 25,
  "duration": 235,
  "cached": false
}
```

--------------------------------

### Get Chapter Server Details

Source: https://api.mangadex.org/docs/04-chapter/feed

Fetches server details required to download chapter pages. This includes the base URL, chapter hash, and image data arrays.

```Python
chapter_id = "27cd0902-ad4c-490a-b752-ae032f0503c9"
```

```Python
import requests

base_url = "https://api.mangadex.org"

r = requests.get(f"{base_url}/at-home/server/{chapter_id}")
r_json = r.json()

host = r_json["baseUrl"]
chapter_hash = r_json["chapter"]["hash"]
data = r_json["chapter"]["data"]
data_saver = r_json["chapter"]["dataSaver"]
```

--------------------------------

### Get Chapter Image Server Metadata

Source: https://api.mangadex.org/docs/04-chapter/retrieving-chapter

Use this endpoint to get the base URL and hash for chapter images. The baseUrl can vary and should be used as-is.

```http
GET https://api.mangadex.org/at-home/server/a54c491c-8e4c-4e97-8873-5b79e59da210
```

--------------------------------

### Get Chapter Server Information

Source: https://api.mangadex.org/docs/04-chapter/retrieving-chapter

Call this endpoint with a chapter ID to get the necessary fields for constructing image URLs. The base URL is time-limited.

```http
GET https://api.mangadex.org/at-home/server/:chapterId
```

--------------------------------

### Python Example: Fetch Manga Statistics

Source: https://api.mangadex.org/docs/03-manga/statistics

This Python script demonstrates how to fetch and display manga statistics, including mean rating, Bayesian rating, and follows, using the requests library.

```python
manga_id = "0301208d-258a-444a-8ef7-66e433d801b1"
```

```python
import requests

base_url = "https://api.mangadex.org"

r = requests.get(f"{base_url}/statistics/manga/{manga_id}")

rating, follows, *others = r.json()["statistics"][manga_id].values()

print(
    f"Mean Rating: {rating.average}\n"
    + f"Bayesian Rating: {rating.bayesian}\n"
    + f"Follows: {follows}"
)
```

--------------------------------

### Refresh Access Token (Python)

Source: https://api.mangadex.org/docs/02-authentication/personal-clients

Python example using the requests library to refresh an expired access token using a refresh token.

```python
import requests

creds = {
    "grant_type": "refresh_token",
    "refresh_token": "<your_refresh_token>",
    "client_id": "<your_client_id>",
    "client_secret": "<your_client_secret>"
}

r = requests.post(
    "https://auth.mangadex.org/realms/mangadex/protocol/openid-connect/token",
    data=creds,
)

access_token = r.json()["access_token"]

print(access_token)
```

--------------------------------

### GET /manga

Source: https://api.mangadex.org/docs/swagger.html

Retrieves a list of manga.

```APIDOC
## GET /manga

### Description
Retrieve a list of manga.

### Method
GET

### Endpoint
/manga
```

--------------------------------

### Commit Upload Session Response

Source: https://api.mangadex.org/docs/04-chapter/upload

Example response after successfully committing an upload session. The `data.id` can be used to construct the chapter's URL.

```json
{
  "result": "ok",
  "data": {
    "id": "14d4639b-5a8f-4f42-a277-b222412930ca",
    "type": "chapter",
    "attributes": {
      "volume": "1",
      "chapter": "2.5",
      "title": "The name of the chapter, if applicable",
      "translatedLanguage": "en",
      "publishAt": null,
      "createdAt": "2021-06-16T00:40:22+00:00",
      "updatedAt": "2021-06-16T00:40:22+00:00",
      "version": 1
    },
    "relationships": [
      {
        "id": "145f9110-0a6c-4b71-8737-6acb1a3c5da4",
        "type": "scanlation_group"
      },
      {
        "id": "f9c33607-9180-4ba6-b85c-e4b5faee7192",
        "type": "manga"
      },
      {
        "id": "41ce3e1a-8325-45b5-af8e-06aaf648a0df",
        "type": "user"
      }
    ]
  }
}
```

--------------------------------

### Get Chapter Server Information

Source: https://api.mangadex.org/docs/04-chapter/retrieving-chapter

This endpoint retrieves the necessary information to construct chapter page URLs. It returns a base URL, chapter hash, and filenames for both original and compressed image qualities.

```APIDOC
## GET /at-home/server/:chapterId

### Description
Retrieves the base URL, chapter hash, and filenames required to construct chapter page URLs.

### Method
GET

### Endpoint
https://api.mangadex.org/at-home/server/:chapterId

### Parameters
#### Path Parameters
- **chapterId** (string) - Required - The ID of the chapter for which to retrieve image server information.

### Response
#### Success Response (200)
- **baseUrl** (string) - A valid base URL for accessing chapter images. This URL is time-limited (guaranteed 15 minutes).
- **chapter.hash** (string) - The hash for the chapter, used in constructing page URLs.
- **chapter.data** (array of strings) - An ordered list of filenames for the original quality images.
- **chapter.dataSaver** (array of strings) - An ordered list of filenames for the compressed quality images.

### Response Example
```json
{
  "baseUrl": "https://uploads.mangadex.org",
  "chapter": {
    "hash": "some_chapter_hash",
    "data": [
      "page1.jpg",
      "page2.jpg"
    ],
    "dataSaver": [
      "page1_sav.jpg",
      "page2_sav.jpg"
    ]
  }
}
```

### Notes
Page URLs are constructed using the format: `$.baseUrl / $QUALITY / $.chapter.hash / $.chapter.$QUALITY[*]` where `$QUALITY` is either `data` or `data-saver`, and `$.chapter.$QUALITY[*]` refers to the filenames within the respective arrays.
```

--------------------------------

### GET /ping

Source: https://api.mangadex.org/docs/swagger.html

Performs a health check on the API infrastructure.

```APIDOC
## GET /ping

### Description
Performs a health check on the API infrastructure.

### Method
GET

### Endpoint
/ping
```

--------------------------------

### GET /manga/{id}

Source: https://api.mangadex.org/docs/swagger.html

Retrieves details for a specific manga by its ID.

```APIDOC
## GET /manga/{id}

### Description
Get details for a specific manga.

### Method
GET

### Endpoint
/manga/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The ID of the manga
```

--------------------------------

### Successful File Upload Response

Source: https://api.mangadex.org/docs/04-chapter/upload

This is an example of a successful response after uploading one or more files to an upload session. It includes a list of successfully uploaded files with their attributes.

```json
{
  "result": "ok",
  "errors": [],
  "data": [
    {
      "id": "12cc211a-c3c3-4f64-8493-f26f9b98c6f6",
      "type": "upload_session_file",
      "attributes": {
        "originalFileName": "testimage1.png",
        "fileHash": "bbf9b9548ee4605c388acb09e8ca83f625e5ff8e241f315eab5291ebd8049c6f",
        "fileSize": 18920,
        "mimeType": "image/png",
        "version": 1
      }
    },
    ...
  ]
}
```

--------------------------------

### GET /manga Endpoint

Source: https://api.mangadex.org/docs/03-manga/search

This is the base endpoint for searching manga. It supports pagination and reference expansion.

```http
GET /manga
```

--------------------------------

### Constructing Page URLs

Source: https://api.mangadex.org/docs/04-chapter/retrieving-chapter

Demonstrates how to construct the full URLs for chapter images using the baseUrl, hash, and filenames obtained from the '/at-home/server/{chapterId}' endpoint.

```APIDOC
## Constructing Page URLs

### DATA (source/original quality)
To construct the full URLs for the original quality images, prepend the `baseUrl` and append `/data/` followed by the chapter `hash` and the respective filename from the `data` array.

**Example URL Format:**
`{baseUrl}/data/{hash}/{filename}`

**Example URLs:**
```
https://uploads.mangadex.org/data/3303dd03ac8d27452cce3f2a882e94b2/1-f7a76de10d346de7ba01786762ebbedc666b412ad0d4b73baa330a2a392dbcdd.png
https://uploads.mangadex.org/data/3303dd03ac8d27452cce3f2a882e94b2/2-2a5e95dfec7f15cd01f9a63835be18a22fb77a10fd2d62858c7dcbb6e6c622f9.png
https://uploads.mangadex.org/data/3303dd03ac8d27452cce3f2a882e94b2/3-d06c6f764fdc3c76ea7ae3b76493fdf1a32b8926f2b60ed207b5c2fed13d002e.png
https://uploads.mangadex.org/data/3303dd03ac8d27452cce3f2a882e94b2/4-a614d6456b9b13931bc5c5ef23cb5f744671f0e1e08c7335682a32de78482f71.png
https://uploads.mangadex.org/data/3303dd03ac8d27452cce3f2a882e94b2/5-1105a368fd73ae99a06d7aebd165a1ff4322539ba50022a967f7b5fb0a185ce5.png
https://uploads.mangadex.org/data/3303dd03ac8d27452cce3f2a882e94b2/6-e8a3eac12d879c541c4a36da550d2c69cc9450cb9b1840a079f890facf5f0c89.png
```

### DATA-SAVER (compressed)
Similarly, for the data-saver quality images, prepend the `baseUrl` and append `/data-saver/` followed by the chapter `hash` and the respective filename from the `dataSaver` array.

**Example URL Format:**
`{baseUrl}/data-saver/{hash}/{filename}`

**Example URLs:**
```
https://uploads.mangadex.org/data-saver/3303dd03ac8d27452cce3f2a882e94b2/1-27e7476475e60ad4cc4cefdb9b2dce29d84f490e145211f6b2e14b13bdb57f33.jpg
https://uploads.mangadex.org/data-saver/3303dd03ac8d27452cce3f2a882e94b2/2-b4e2cd69df2648279b7d87d44f7860d3fc760aa442e08c49579359f3cf4b4f14.jpg
https://uploads.mangadex.org/data-saver/3303dd03ac8d27452cce3f2a882e94b2/3-b45f66bdac44652ea2eae40bb5788afe34b8ab5a66e69f0d406257804ddaeda1.jpg
https://uploads.mangadex.org/data-saver/3303dd03ac8d27452cce3f2a882e94b2/4-92b328471cca1b032bd99cd8506c945a2c3b5a5fd32275b0c4dbfd8ddcfe7e0a.jpg
https://uploads.mangadex.org/data-saver/3303dd03ac8d27452cce3f2a882e94b2/5-b2336d540fe4a2f9f452cec8e4b2d2ef894f66535e45a4468bf59a6d37f025fe.jpg
https://uploads.mangadex.org/data-saver/3303dd03ac8d27452cce3f2a882e94b2/6-09f2deb563e802464c161bf7bfa2b094a4727efb4f962d30cf8ee2857a0a66c8.jpg
```

**Important Note:** Do not send authentication headers when fetching images. Requests to image servers with authentication headers will be rejected. If you are using a MangaDex@Home node, ensure you are not leaking authentication tokens.
```

--------------------------------

### Construct Chapter Image URLs

Source: https://api.mangadex.org/docs/04-chapter/retrieving-chapter

Combine the baseUrl and hash from the server metadata with the image filenames to form complete URLs. Do not send authentication headers when fetching images.

```url
https://uploads.mangadex.org/data/3303dd03ac8d27452cce3f2a882e94b2/1-f7a76de10d346de7ba01786762ebbedc666b412ad0d4b73baa330a2a392dbcdd.png
https://uploads.mangadex.org/data/3303dd03ac8d27452cce3f2a882e94b2/2-2a5e95dfec7f15cd01f9a63835be18a22fb77a10fd2d62858c7dcbb6e6c622f9.png
https://uploads.mangadex.org/data/3303dd03ac8d27452cce3f2a882e94b2/3-d06c6f764fdc3c76ea7ae3b76493fdf1a32b8926f2b60ed207b5c2fed13d002e.png
https://uploads.mangadex.org/data/3303dd03ac8d27452cce3f2a882e94b2/4-a614d6456b9b13931bc5c5ef23cb5f744671f0e1e08c7335682a32de78482f71.png
https://uploads.mangadex.org/data/3303dd03ac8d27452cce3f2a882e94b2/5-1105a368fd73ae99a06d7aebd165a1ff4322539ba50022a967f7b5fb0a185ce5.png
https://uploads.mangadex.org/data/3303dd03ac8d27452cce3f2a882e94b2/6-e8a3eac12d879c541c4a36da550d2c69cc9450cb9b1840a079f890facf5f0c89.png
```

```url
https://uploads.mangadex.org/data-saver/3303dd03ac8d27452cce3f2a882e94b2/1-27e7476475e60ad4cc4cefdb9b2dce29d84f490e145211f6b2e14b13bdb57f33.jpg
https://uploads.mangadex.org/data-saver/3303dd03ac8d27452cce3f2a882e94b2/2-b4e2cd69df2648279b7d87d44f7860d3fc760aa442e08c49579359f3cf4b4f14.jpg
https://uploads.mangadex.org/data-saver/3303dd03ac8d27452cce3f2a882e94b2/3-b45f66bdac44652ea2eae40bb5788afe34b8ab5a66e69f0d406257804ddaeda1.jpg
https://uploads.mangadex.org/data-saver/3303dd03ac8d27452cce3f2a882e94b2/4-92b328471cca1b032bd99cd8506c945a2c3b5a5fd32275b0c4dbfd8ddcfe7e0a.jpg
https://uploads.mangadex.org/data-saver/3303dd03ac8d27452cce3f2a882e94b2/5-b2336d540fe4a2f9f452cec8e4b2d2ef894f66535e45a4468bf59a6d37f025fe.jpg
https://uploads.mangadex.org/data-saver/3303dd03ac8d27452cce3f2a882e94b2/6-09f2deb563e802464c161bf7bfa2b094a4727efb4f962d30cf8ee2857a0a66c8.jpg
```

--------------------------------

### Prepare Image Files for Upload

Source: https://api.mangadex.org/docs/04-chapter/upload/upload-chapter

This script collects image files from a specified folder, filters them by extension, and creates a list of dictionaries containing file details. Ensure the folder path and accepted extensions are correctly configured.

```Python
import os

page_map = []
batch_size = 5
folder_path = "Mangadex/chapter"

for filename in os.listdir(folder_path):
    # omitting non-accepted mimetypes
    if "." not in filename or filename.split(".")[-1].lower() not in ["jpg", "jpeg", "png", "gif"]:
        continue

    page_map.append(
        {
            "filename": filename,
            "extension": filename.split(".")[-1].lower(),
            "path": f"{folder_path}/{filename}",
        }
    )

```

--------------------------------

### Download Chapter Pages

Source: https://api.mangadex.org/docs/04-chapter/feed

Downloads all pages for a given chapter using the server details obtained from the /at-home/server endpoint. Images are saved to a local directory.

```Python
import os

# Making a folder to store the images in.
folder_path = f"Mangadex/{chapter_id}"
os.makedirs(folder_path, exist_ok=True)
```

```Python
import requests

for page in data:
    r = requests.get(f"{host}/data/{chapter_hash}/{page}")

    with open(f"{folder_path}/{page}", mode="wb") as f:
        f.write(r.content)

print(f"Downloaded {len(data)} pages.")
```

--------------------------------

### Get Manga Statistics

Source: https://api.mangadex.org/docs/01-concepts/comments

This endpoint retrieves statistics for a given manga, including information about its associated comment thread.

```APIDOC
## GET /statistics/manga/{id}

### Description
Retrieves statistics for a specific manga, including comment thread details.

### Method
GET

### Endpoint
/statistics/manga/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the manga.

### Response
#### Success Response (200)
- **result** (string) - Indicates the status of the request ('ok').
- **statistics** (object) - An object containing statistics for the requested entity.
  - **{id}** (object) - Statistics specific to the manga ID.
    - **comments** (object | null) - Information about the comment thread.
      - **threadId** (integer) - The ID of the comment thread.
      - **repliesCount** (integer) - The number of replies in the comment thread.

### Response Example (Entity has comment thread)
```json
{
  "result": "ok",
  "statistics": {
    "8b34f37a-0181-4f0b-8ce3-01217e9a602c": {
      "comments": {
        "threadId": 1069290,
        "repliesCount": 12
      }
    }
  }
}
```

### Response Example (Entity does not have comment thread)
```json
{
  "result": "ok",
  "statistics": {
    "8b34f37a-0181-4f0b-8ce3-01217e9a602c": {
      "comments": null
    }
  }
}
```
```

--------------------------------

### Begin New Upload Session

Source: https://api.mangadex.org/docs/04-chapter/upload

Initiate a new upload session by providing the manga ID and scanlation group IDs. The response contains the upload session ID.

```http
POST /upload/begin
```

```json
{
  "manga": "f9c33607-9180-4ba6-b85c-e4b5faee7192",
  "groups": [
    "145f9110-0a6c-4b71-8737-6acb1a3c5da4"
  ]
}
```

```json
{
  "result": "ok",
  "data": {
    "id": "113b7724-dcc2-4fbc-968f-9d775fcb1cd6",
    "type": "upload_session",
    "attributes": {
      "isCommitted": false,
      "isProcessed": false,
      "isDeleted": false
    },
    "relationships": [
      {
        "id": "41ce3e1a-8325-45b5-af8e-06aaf648a0df",
        "type": "user"
      },
      {
        "id": "f9c33607-9180-4ba6-b85c-e4b5faee7192",
        "type": "manga"
      },
      {
        "id": "145f9110-0a6c-4b71-8737-6acb1a3c5da4",
        "type": "scanlation_group"
      }
    ]
  }
}
```

--------------------------------

### Initialize Group and Manga IDs

Source: https://api.mangadex.org/docs/04-chapter/upload/upload-chapter

Set the group and manga IDs for the chapter upload. Uses test IDs for demonstration.

```python
group_ids = ["18dadd0b-cbce-41c4-a8a9-5e653780b9ff"]
manga_id = "f9c33607-9180-4ba6-b85c-e4b5faee7192"
```

--------------------------------

### Create Custom List

Source: https://api.mangadex.org/docs/03-manga/mdlist

Creates a new custom list with a specified name and visibility. Manga can be optionally added during creation.

```APIDOC
## POST /list

### Description
Creates a new custom list.

### Method
POST

### Endpoint
/list

### Parameters
#### Request Body
- **name** (string) - Required - The name of the custom list.
- **visibility** (string) - Required - The visibility of the list (e.g., "public", "private").
- **manga** (array) - Optional - An array of manga IDs to initially add to the list.

### Request Example
```json
{
  "name": "Hidden Gems",
  "visibility": "public",
  "manga": ["manga_id_1", "manga_id_2"]
}
```

### Response
#### Success Response (200)
- **data** (object) - Contains details of the created list, including its **id**.
```

--------------------------------

### Get Manga Statistics

Source: https://api.mangadex.org/docs/03-manga/statistics

Retrieves the statistics for a specific manga, including its average rating, Bayesian score, and follow count.

```APIDOC
## GET /statistics/manga/{uuid}

### Description
A Manga's average rating is represented by an mean score, and a Bayesian score of values between 1 and 10. The Bayesian score is used to avoid little-known Manga to be greatly affected by a few people's opinion. The Bayesian Average ultimately converges to the mean, as the reviews populate.

### Method
GET

### Endpoint
/statistics/manga/{uuid}

### Parameters
#### Path Parameters
- **uuid** (string) - Required - The unique identifier of the manga.

### Request Example
```python
manga_id = "0301208d-258a-444a-8ef7-66e433d801b1"
```

```javascript
import requests

base_url = "https://api.mangadex.org"

r = requests.get(f"{base_url}/statistics/manga/{manga_id}")

rating, follows, *others = r.json()["statistics"][manga_id].values()

print(
    f"Mean Rating: {rating.average}\n"
    + f"Bayesian Rating: {rating.bayesian}\n"
    + f"Follows: {follows}"
)
```

### Response
#### Success Response (200)
- **statistics** (object) - Contains statistics for the requested manga.
  - **[manga_uuid]** (object)
    - **rating** (object)
      - **average** (number) - The mean rating of the manga.
      - **bayesian** (number) - The Bayesian rating of the manga.
    - **follows** (number) - The number of users following the manga.

#### Response Example
```json
{
  "statistics": {
    "0301208d-258a-444a-8ef7-66e433d801b1": {
      "rating": {
        "average": 7.5,
        "bayesian": 7.2
      },
      "follows": 1500
    }
  }
}
```
```

--------------------------------

### Create Upload Session

Source: https://api.mangadex.org/docs/04-chapter/upload/upload-chapter

Initiates an upload session by sending group and manga IDs to the `/upload/begin` endpoint. Requires an active session token for authentication. If an existing session is found, it must be abandoned first.

```APIDOC
## POST /upload/begin

### Description
Creates a new upload session for uploading chapters.

### Method
POST

### Endpoint
/upload/begin

### Parameters
#### Request Body
- **groups** (array of strings) - Required - The IDs of the groups working on the chapter.
- **manga** (string) - Required - The ID of the manga to which the chapter belongs.

### Request Example
```json
{
  "groups": ["18dadd0b-cbce-41c4-a8a9-5e653780b9ff"],
  "manga": "f9c33607-9180-4ba6-b85c-e4b5faee7192"
}
```

### Response
#### Success Response (200)
- **data** (object) - Contains the ID of the newly created upload session.
  - **id** (string) - The unique identifier for the upload session.

#### Response Example
```json
{
  "result": "ok",
  "response": "entity",
  "data": {
    "id": "a1b2c3d4-e5f6-7890-1234-567890abcdef"
  }
}
```

### Error Handling
- **400 Bad Request**: If the request body is invalid or if an active session already exists and is not abandoned.
- **401 Unauthorized**: If the session token is invalid or expired.
```

--------------------------------

### Begin Edit Session

Source: https://api.mangadex.org/docs/04-chapter/upload

Initiate an edit session for an existing chapter using its ID. This pre-fills the session with the chapter's current pages.

```http
POST /upload/begin/{chapterId}
```

--------------------------------

### Get Manga Feed

Source: https://api.mangadex.org/docs/04-chapter/feed

Fetches a list of chapter IDs for a given manga ID. This is the initial step to find chapters of a specific manga.

```Python
manga_id = "f98660a1-d2e2-461c-960d-7bd13df8b76d"
```

```Python
import requests

base_url = "https://api.mangadex.org"

r = requests.get(f"{base_url}/manga/{manga_id}/feed")

print([chapter["id"] for chapter in r.json()["data"]])
```

--------------------------------

### Create a Custom List

Source: https://api.mangadex.org/docs/03-manga/mdlist

Create a new custom list with a specified name and visibility. You can optionally add manga IDs during creation. Requires authentication.

```Python
options = {
    "name": "Hidden Gems",
    "visibility": "public",
}
```

```text
session_token = "somesessiontoken"
```

```Python
import requests

base_url = "https://api.mangadex.org"

r = requests.post(
    f"{base_url}/list",
    headers={
        "Authorization": f"Bearer {session_token}"
    },
    json=options,
)

print(
    "List created with ID:",
    r.json()["data"]["id"],
)
```

--------------------------------

### Fetch Manga Statistics

Source: https://api.mangadex.org/docs/01-concepts/comments

Use this endpoint to get statistics for a specific manga, including comment thread information. This is the first step to checking if an entity has comments.

```http
GET https://api.mangadex.org/statistics/manga/8b34f37a-0181-4f0b-8ce3-01217e9a602c
```

--------------------------------

### Get Manga Statistics by UUID

Source: https://api.mangadex.org/docs/03-manga/statistics

Use this endpoint to retrieve statistics for a specific manga using its UUID. The response includes average and Bayesian ratings, and follow counts.

```http
GET /statistics/manga/{uuid}
```

--------------------------------

### POST /auth/login

Source: https://api.mangadex.org/docs/swagger.html

Authenticates a user and returns a session token.

```APIDOC
## POST /auth/login

### Description
Login to the MangaDex service.

### Method
POST

### Endpoint
/auth/login
```

--------------------------------

### Create Upload Session

Source: https://api.mangadex.org/docs/04-chapter/upload/upload-chapter

Initiates an upload session using the POST /upload/begin endpoint. Requires an active session token and group/manga IDs. Handles cases where another session is active.

```python
import requests

base_url = "https://api.mangadex.org"

r = requests.post(
    f"{base_url}/upload/begin",
    headers={
        "Authorization": f"Bearer {session_token}"
    },
    json={"groups": group_ids, "manga": manga_id},
)

if r.ok:
    session_id = r.json()["data"]["id"]
    print(f"Created a new Upload Session with ID: {session_id}")
else:
    print("Another session found, please abandon it before creating a new one.")
```

--------------------------------

### Get Chapter Image Delivery Metadata

Source: https://api.mangadex.org/docs/04-chapter/retrieving-chapter

This endpoint retrieves the metadata required to access chapter images, including the base URL and image hashes. It requires a chapter ID as a path parameter.

```APIDOC
## GET /at-home/server/{chapterId}

### Description
Retrieves the image delivery metadata for a given chapter.

### Method
GET

### Endpoint
/at-home/server/{chapterId}

### Parameters
#### Path Parameters
- **chapterId** (string) - Required - The ID of the chapter to retrieve image metadata for.

### Response
#### Success Response (200)
- **result** (string) - Indicates the success of the request ('ok').
- **baseUrl** (string) - The base URL for accessing chapter images. This can vary and should be used as-is.
- **chapter** (object) - Contains image data.
  - **hash** (string) - A unique hash associated with the chapter's images.
  - **data** (array of strings) - An array of image filenames for the original quality.
  - **dataSaver** (array of strings) - An array of image filenames for the data-saver (compressed) quality.

### Request Example
```
GET https://api.mangadex.org/at-home/server/a54c491c-8e4c-4e97-8873-5b79e59da210
```

### Response Example
```json
{
  "result": "ok",
  "baseUrl": "https://uploads.mangadex.org",
  "chapter": {
    "hash": "3303dd03ac8d27452cce3f2a882e94b2",
    "data": [
      "1-f7a76de10d346de7ba01786762ebbedc666b412ad0d4b73baa330a2a392dbcdd.png",
      "2-2a5e95dfec7f15cd01f9a63835be18a22fb77a10fd2d62858c7dcbb6e6c622f9.png",
      "3-d06c6f764fdc3c76ea7ae3b76493fdf1a32b8926f2b60ed207b5c2fed13d002e.png",
      "4-a614d6456b9b13931bc5c5ef23cb5f744671f0e1e08c7335682a32de78482f71.png",
      "5-1105a368fd73ae99a06d7aebd165a1ff4322539ba50022a967f7b5fb0a185ce5.png",
      "6-e8a3eac12d879c541c4a36da550d2c69cc9450cb9b1840a079f890facf5f0c89.png"
    ],
    "dataSaver": [
      "1-27e7476475e60ad4cc4cefdb9b2dce29d84f490e145211f6b2e14b13bdb57f33.jpg",
      "2-b4e2cd69df2648279b7d87d44f7860d3fc760aa442e08c49579359f3cf4b4f14.jpg",
      "3-b45f66bdac44652ea2eae40bb5788afe34b8ab5a66e69f0d406257804ddaeda1.jpg",
      "4-92b328471cca1b032bd99cd8506c945a2c3b5a5fd32275b0c4dbfd8ddcfe7e0a.jpg",
      "5-b2336d540fe4a2f9f452cec8e4b2d2ef894f66535e45a4468bf59a6d37f025fe.jpg",
      "6-09f2deb563e802464c161bf7bfa2b094a4727efb4f962d30cf8ee2857a0a66c8.jpg"
    ]
  }
}
```
```

--------------------------------

### Settings API

Source: https://api.mangadex.org/docs/swagger.html

Endpoints for managing user settings and templates.

```APIDOC
## GET /settings/template
### Description
Get latest Settings template
### Method
GET
### Endpoint
/settings/template

## POST /settings/template
### Description
Create Settings template
### Method
POST
### Endpoint
/settings/template

## GET /settings/template/{version}
### Description
Get Settings template by version id
### Method
GET
### Endpoint
/settings/template/{version}

## GET /settings
### Description
Get an User Settings
### Method
GET
### Endpoint
/settings

## POST /settings
### Description
Create or update an User Settings
### Method
POST
### Endpoint
/settings
```

--------------------------------

### Download a Chapter

Source: https://api.mangadex.org/docs/04-chapter/feed

Retrieve the image data for a specific chapter. This endpoint provides URLs for both original quality and compressed versions of the chapter images.

```APIDOC
## GET /at-home/server/{id}

### Description
Retrieves the server information and image data for a specific chapter, including URLs for different quality options.

### Method
GET

### Endpoint
/at-home/server/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the chapter.
```

--------------------------------

### Constructing Manga Cover Thumbnail URLs

Source: https://api.mangadex.org/docs/03-manga/covers

Generate URLs for premade thumbnail versions of a manga cover. Specify the desired width (256 or 512 pixels) and append it to the filename. The full cover filename, including its original extension, is required.

```url
https://uploads.mangadex.org/covers/:manga-id/:cover-filename.{256, 512}.jpg
```

--------------------------------

### Begin Edit Session for Chapter

Source: https://api.mangadex.org/docs/04-chapter/upload

Initiates an edit session for a published chapter, pre-filling it with the current version's pages. This allows for modification of pages, including adding, removing, and reordering.

```APIDOC
## POST /upload/begin/{chapterId}

### Description
Begins an edit session for a published chapter. This session is pre-populated with the chapter's current pages, allowing for modifications such as adding, removing, and reordering pages before committing the changes.

### Method
POST

### Endpoint
/upload/begin/{chapterId}

### Parameters
#### Path Parameters
- **chapterId** (string) - Required - The ID of the chapter to begin editing.

### Note
This endpoint generates an "edit" session, which functions similarly to an upload session but starts with existing chapter content. The process of uploading to and committing this session is analogous to a standard upload session.
```

--------------------------------

### Authenticate with Username and Password

Source: https://api.mangadex.org/docs/02-authentication/personal-clients

Use this form data to obtain an access token and refresh token pair. Ensure the Content-Type is application/x-www-form-urlencoded.

```http
POST https://auth.mangadex.org/realms/mangadex/protocol/openid-connect/token

grant_type=password
username=<your_username>
password=<your_password>
client_id=<your_client_id>
client_secret=<your_client_secret>
```

--------------------------------

### Sort Pages and Commit Upload Session

Source: https://api.mangadex.org/docs/04-chapter/upload/upload-chapter

Sorts uploaded pages by filename and commits the upload session with chapter metadata. Ensure files are zero-padded for correct sorting.

```python
successful.sort(key=lambda a: a["filename"])

page_order = [page["id"] for page in successful]

chapter_draft = {
    "volume": None,
    "chapter": "5",
    "translatedLanguage": "en",
    "title": "MD Docs Python code example test",
}
```

```python
import requests

base_url = "https://api.mangadex.org"

r = requests.post(
    f"{base_url}/upload/{session_id}/commit",
    headers={
        "Authorization": f"Bearer {session_token}"
    },
    json={
        "chapterDraft": chapter_draft,
        "pageOrder": page_order,
    },
)

if r.ok:
    print(
        "Upload Session successfully committed, entity ID is:",
        r.json()["data"]["id"],
    )
else:
    print("An error occurred.")
    print(r.json())
```

--------------------------------

### AtHome Rate Limits

Source: https://api.mangadex.org/docs/2-limitations

Rate limits for the MangaDex@Home endpoints.

```APIDOC
## GET /at-home/server/{id}

### Description
Retrieves server information for MangaDex@Home.

### Method
GET

### Endpoint
`/at-home/server/{id}`

### Rate Limit
40 requests per 1 minute
```

--------------------------------

### Constructing Manga Cover URL

Source: https://api.mangadex.org/docs/03-manga/covers

Use this URL format to retrieve the full-size cover image for a manga. Requires the manga ID and the cover's filename.

```url
https://uploads.mangadex.org/covers/:manga-id/:cover-filename
```

--------------------------------

### Check for Active Upload Session

Source: https://api.mangadex.org/docs/04-chapter/upload

Before creating a new upload session, verify if one is already active. A 404 response indicates no active session.

```http
GET /upload
```

```json
{
  "errors": [
    {
      "..."
      "detail": "No upload session found"
    }
  ]
}
```

--------------------------------

### List Manga Chapters with Future Publish Dates and No External URL

Source: https://api.mangadex.org/docs/04-chapter/search

Combine `includeFuturePublishAt=1` and `includeExternalUrl=0` to filter for chapters with future publish dates and no external URL.

```http
/manga/{id}/feed?includeFuturePublishAt=1&includeExternalUrl=0
```

--------------------------------

### Find a Manga's Chapters

Source: https://api.mangadex.org/docs/04-chapter/feed

Retrieve a list of chapters for a specific manga. This is the first step to finding a chapter you want to read.

```APIDOC
## GET /manga/{id}/feed

### Description
Retrieves a collection of chapters for a given manga. The response includes chapter details such as number, volume, and language.

### Method
GET

### Endpoint
/manga/{id}/feed

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the manga.
```

--------------------------------

### List Custom List Chapters

Source: https://api.mangadex.org/docs/04-chapter/search

Lists all chapters for a given custom list. By default, it only shows chapters published at or before the current time.

```APIDOC
## GET /list/{id}/feed

### Description
Lists all chapters for a given CustomList.

### Method
GET

### Endpoint
/list/{id}/feed

### Query Parameters
- **includeEmptyPages** (integer) - Optional - Used to show Chapters with no pages available.
- **includeFuturePublishAt** (integer) - Optional - Used to show Chapters with a publishAt date set in the future.
- **includeExternalUrl** (integer) - Optional - Used to show Chapters that have an external URL attached to them.

### Response
#### Success Response (200)
- **chapters** (array) - List of chapter objects.
- **limit** (integer) - The limit of chapters returned.
- **offset** (integer) - The offset of chapters returned.
- **total** (integer) - The total number of chapters available.
```

--------------------------------

### Expand Manga Relationships

Source: https://api.mangadex.org/docs/01-concepts/reference-expansion

Use the `includes` parameter to expand relationships like author, artist, and cover art for a manga resource. This reduces the number of API calls needed to fetch complete data.

```http
GET /manga/f9c33607-9180-4ba6-b85c-e4b5faee7192?includes[]=author&includes[]=artist&includes[]=cover_art
```

--------------------------------

### Add Manga to Reading List

Source: https://api.mangadex.org/docs/03-manga/mdlist

Use this endpoint to add a manga to your reading list. Pass `null` for the status to remove it. Requires authentication.

```Python
manga_id = "bbdaa3a3-ea49-4f12-9e1c-baa452f0830d"
status = "reading"
```

```text
session_token = "somesessiontoken"
```

```Python
import requests

base_url = "https://api.mangadex.org"

r = requests.post(
    f"{base_url}/manga/{manga_id}/status",
    headers={
        "Authorization": f"Bearer {session_token}"
    },
    json={"status": status},
)

print(r.json()["result"])
```

--------------------------------

### Add Manga to Follows List

Source: https://api.mangadex.org/docs/03-manga/mdlist

Adds a manga to the user's follows list to receive updates on new chapters.

```APIDOC
## POST /manga/{id}/follow

### Description
Adds a manga to the user's follows list.

### Method
POST

### Endpoint
/manga/{id}/follow

### Parameters
#### Path Parameters
- **id** (string) - Required - The ID of the manga to follow.

### Response
#### Success Response (200)
- **result** (string) - Indicates the success of the operation.
```