Data Schemas

This page documents the JSON structures used throughout the Alethia Host API. Use these as a reference when implementing your host in any language.

Slugs

Slugs are unique identifier strings used throughout the API to distinguish resources and build URLs for fetching data. They appear in endpoint paths (:mangaSlug, :chapterSlug) and in response payloads.

Slug Types

Type	Example	Used In
Source slug	`mangadex`	`GET /:source`, `POST /:source/search`
Manga slug	`one-piece-abc123`	`GET /:source/:mangaSlug`
Chapter slug	`chapter-1100-en`	`GET /:source/:mangaSlug/chapters/:chapterSlug`
Tag slug	`action`	`filters.includeTag`, `filters.excludeTag`

Guidelines

Keep them stable — Slugs should not change over time. If the upstream resource ID is stable, derive slugs deterministically from it.
Make them deterministic — Given the same upstream resource, always generate the same slug. This ensures consistency across requests and caching.
Use meaningful identifiers — Where possible, include human-readable context (e.g., one-piece-abc123 rather than just abc123).

URL Safety

Slugs used in endpoint paths (:mangaSlug, :chapterSlug) must be URL-safe. Avoid spaces, special characters, and non-ASCII characters. Stick to lowercase alphanumeric characters, hyphens, and underscores. If upstream IDs contain unsafe characters, encode or transform them.

Core Definitions

Entry

A search result entry containing minimal information for display in lists. This is a lightweight object used in search results.

{
  "slug": "one-piece",
  "title": "One Piece",
  "cover": "https://example.com/covers/one-piece.jpg"
}

Field	Type	Required	Description
`slug`	string	Yes	Unique identifier used in URLs to fetch details (see Slugs)
`title`	string	Yes	Display title
`cover`	string \| null	Yes	URL to cover image (can be null if no cover available)

Minimal Data

Entry is intentionally minimal to keep search responses lightweight. Full metadata (tags, classification, etc.) is fetched via the manga details endpoint upon actual request.

Manga

General Content Object

Despite terminology used as "Manga" here and spread elsewhere in these docs - this is a general content object representing any serialized work (manga, manhwa, webtoon, novel, etc.) depending on the source.

Full manga details returned by the GET /:source/:mangaSlug endpoint.

{
  "slug": "one-piece",
  "url": "https://mangadex.org/title/a1c7c817-4e59-43b7-9365-09675a149a6f",
  "title": "One Piece",
  "alternativeTitles": ["ワンピース", "OP", "海贼王"],
  "authors": ["Oda Eiichiro"],
  "synopsis": "Gol D. Roger, a man referred to as the \"Pirate King,\" is set to be executed by the World Government...",
  "covers": [
    "https://example.com/covers/one-piece-vol1.jpg",
    "https://example.com/covers/one-piece-vol2.jpg"
  ],
  "tags": ["action", "adventure", "comedy", "fantasy"],
  "classification": "Safe",
  "publication": "Ongoing",
  "createdAt": "2020-01-15T10:30:00Z",
  "updatedAt": "2024-12-01T08:00:00Z"
}

Field	Type	Required	Description
`slug`	string	Yes	Unique identifier (matches URL parameter, see Slugs)
`url`	string	Yes	URL to the manga on the upstream source
`title`	string	Yes	Primary display title (defaults to "Unknown Title")
`alternativeTitles`	string[]	Yes	Other titles (translations, abbreviations). Can be empty array.
`authors`	string[]	Yes	List of author names. Can be empty array.
`synopsis`	string	Yes	Description/summary (defaults to "No Description.")
`covers`	string[]	Yes	Cover image URLs. Can be empty array.
`tags`	string[]	Yes	Array of tag slugs (strings, not full tag objects)
`classification`	Classification	Yes	Content rating
`publication`	Publication	Yes	Publication status
`createdAt`	string	Yes	ISO 8601 timestamp of when the manga was added
`updatedAt`	string	Yes	ISO 8601 timestamp of last update

Chapter

Chapter metadata returned by the GET /:source/:mangaSlug/chapters endpoint.

{
  "slug": "en-chapter-1100-abc123",
  "url": "https://mangadex.org/chapter/abc123",
  "title": "Chapter 1100: My Dear Hero",
  "number": 1100,
  "date": "2024-01-15T12:00:00Z",
  "language": "en",
  "scanlator": "TCB Scans"
}

Field	Type	Required	Description
`slug`	string	Yes	Unique identifier for the chapter (used to fetch pages, see Slugs)
`url`	string	Yes	URL to the chapter on the upstream source
`title`	string	Yes	Chapter title for display (defaults to "No Title")
`number`	number	Yes	Chapter number (ideally unique, must be >= 0)
`date`	string	Yes	ISO 8601 timestamp of release/upload date
`language`	string	Yes	Language code in ISO 639-1 format (e.g., `en`, `ja`, `pt-br`)
`scanlator`	string	Yes	Scanlation group name (defaults to "Unknown Scanlator")

Chapter Numbers

The number field should be a numeric value for proper sorting. For special chapters (e.g., "Chapter 100.5"), use decimal values like 100.5. For non-numeric chapters (e.g., "Oneshot"), use 0 or another appropriate value.

Chapter Deduplication

When multiple chapters share the same number (e.g., different scanlators or languages), the client displays only one version per number based on user-configured source and scanlator priorities (unified chapter list). To avoid confusion, aim for unique chapter numbers where possible. If duplicates are unavoidable, ensure the scanlator and language fields are accurate, or the titles are well-defined to distinguish easier.

Tag

Tag information used in source configuration. Tags define the available genres/categories users can filter by.

{
  "slug": "action",
  "name": "Action",
  "nsfw": false
}

Field	Type	Required	Description
`slug`	string	Yes	Unique identifier (used in filters and manga tags array, see Slugs)
`name`	string	Yes	Display name (1-50 characters)
`nsfw`	boolean	Yes	Whether this tag indicates NSFW content (defaults to false)

Tags in Context

Tags appear in two places: as full objects in source configuration (search.tags), and as slug strings in manga details (tags: ["action", "adventure"]).

Enumerations

These are the allowed string values for enumerated fields.

Notice

Values defined here are in PascalCase.

Classification

Content rating classification for manga.

Value	Description
`Unknown`	Classification not determined
`Safe`	Appropriate for all ages
`Suggestive`	May contain mild sexual content or themes
`Explicit`	Contains explicit content
`Pornographic`	Contains pornographic content

Publication

Publication status of a manga. This indicates whether the manga is still being released.

Value	Description
`Unknown`	Status cannot be determined
`Ongoing`	Currently being published
`Completed`	Publication finished
`Cancelled`	Permanently discontinued
`Hiatus`	On temporary break

Sort Options

Standard sort option values. Sources declare which ones they support in their search.sort configuration array.

About Sort Options

The below list is quite generic and may not all be supported by every source. I don't believe adding new ones will be truly beneficial unless otherwise desired, as typically whatever these 'new' sorting options are would likely be extremely niche or can fall under an existing sorting category. Please get in contact otherwise if you have a specific use case in mind.

Value	Description
`relevance`	Search relevance (only meaningful with a query)
`latest`	Recently updated
`title`	Alphabetical by title
`popularity`	Most popular
`rating`	Highest rated
`chapters`	Number of chapters
`year`	Publication year
`views`	View count
`follows`	Follower/subscriber count
`createdAt`	Date added (unstable reference for when a series was actually created, don't depend on this)
`updatedAt`	Last updated

About Filter Options

The below list is quite generic and may not all be supported by every source. I don't believe adding new ones will be truly beneficial unless otherwise desired, as typically whatever these 'new' filter options are would likely be extremely niche or can fall under an existing filtering category. Please get in contact otherwise if you have a specific use case in mind.

Standard filter keys. These are defined capabilities that a source would be able to perform and should be declared in the search.filters configuration array.

Key	Value Type	Description
`genre`	string[]	Filter by genre slugs
`status`	string[]	Filter by publication status values
`contentRating`	string[]	Filter by classification values
`year`	number	Publication year
`originalLanguage`	string[]	Filter by original language codes
`translatedLanguage`	string[]	Filter by available translation languages
`author`	string	Filter by author name
`artist`	string	Filter by artist name
`includeTag`	string[]	Include manga with these tag slugs
`excludeTag`	string[]	Exclude manga with these tag slugs
`demographic`	string[]	Filter by demographic (shounen, seinen, etc.)
`publisher`	string	Filter by publisher name
`minChapters`	number	Minimum number of chapters

API Request/Response Schemas

This section expands on the request and response formats for each endpoint. See Endpoints for full endpoint documentation.

Search Request

POST body for the POST /:source/search endpoint.

{
  "query": "one piece",
  "page": 1,
  "limit": 20,
  "sort": "relevance",
  "direction": "desc",
  "filters": {
    "status": ["Ongoing", "Completed"],
    "contentRating": ["Safe", "Suggestive"],
    "includeTag": ["action"],
    "excludeTag": ["romance"]
  }
}

Field	Type	Required	Default	Description
`query`	string	No	`""`	Search query text
`page`	number	Yes	—	Page number (1-indexed)
`limit`	number	No	`20`	Results per page (max: 100)
`sort`	string	Yes	—	Sort option from source's supported list
`direction`	string	No	`"desc"`	Sort direction: `asc` or `desc`
`filters`	object	No	`{}`	Filter key-value pairs

Search Response

Response from the POST /:source/search endpoint.

{
  "results": [
    {
      "slug": "one-piece",
      "title": "One Piece",
      "cover": "https://..."
    }
  ],
  "page": 1,
  "more": true
}

Field	Type	Description
`results`	Entry[]	Array of matching entries
`page`	number	Current page number
`more`	boolean	`true` if more results exist on the next page

Auth Request

POST body for the POST /:source/authenticate endpoint. Fields depend on the source's auth.fields configuration.

Basic/Session auth:

{
  "username": "user@example.com",
  "password": "password123"
}

API Key auth:

{
  "apiKey": "sk-abc123def456"
}

Bearer auth:

{
  "token": "eyJhbGciOiJIUzI1NiIs..."
}

Cookie auth:

{
  "cookie": "session=abc123; cf_clearance=xyz789"
}

Auth Response

Response from the POST /:source/authenticate endpoint.

Success:

{
  "success": true,
  "headers": {
    "Authorization": "Bearer eyJhbGciOiJIUzI1NiIs...",
    "Cookie": "session=abc123"
  }
}

Failure:

{
  "success": false,
  "error": {
    "code": "INVALID_CREDENTIALS",
    "message": "Invalid username or password"
  }
}

Field	Type	Description
`success`	boolean	Whether authentication succeeded
`headers`	object	Headers to include in authenticated requests (success only)
`error`	object	Error details (failure only)
`error.code`	string	Machine-readable error code
`error.message`	string	Human-readable error message

Ping Response

Response from the GET /:source/ping endpoint.

{
  "status": "ok",
  "latencyMs": 150
}

Field	Type	Description
`status`	string	`ok` if upstream is reachable, `down` otherwise
`latencyMs`	number	Round-trip time in milliseconds
`error`	string	Error message (only present when status is `down`)

Configuration Schemas

Host

Response from the GET / endpoint.

{
  "name": "myhost",
  "author": "developer",
  "repository": "https://github.com/developer/myhost",
  "version": "1.0.0",
  "hash": "abc123def456",
  "sources": ["mangadex"],
  "manifest": {
    "mangadex": {
      "version": "1.0.0",
      "hash": "xyz789",
      "status": "active"
    }
  }
}

Field	Type	Description
`name`	string	Host name (lowercase a-z only, 2-50 characters)
`author`	string	Host maintainer (lowercase a-z only, 2-50 characters)
`repository`	string	URL to source code repository
`version`	string	Semantic version (e.g., `1.0.0`)
`hash`	string	Content hash for change detection
`sources`	string[]	Array of available source slugs
`manifest`	object	Per-source metadata

Source

Response from the GET /:source endpoint.

{
  "name": "MangaDex",
  "slug": "mangadex",
  "icon": "https://example.com/mangadex-icon.png",
  "languages": ["en", "ja"],
  "nsfw": false,
  "url": "https://mangadex.org",
  "referer": "https://mangadex.org",
  "auth": {
    "type": "none",
    "required": false
  },
  "search": {
    "sort": ["relevance", "latest", "popularity"],
    "filters": ["status", "contentRating", "includeTag", "excludeTag"],
    "tags": [
      { "slug": "action", "name": "Action", "nsfw": false }
    ]
  },
  "presets": [
    {
      "name": "Latest Updates",
      "description": "Recently updated manga",
      "request": {
        "query": "",
        "page": 1,
        "limit": 20,
        "sort": "latest",
        "direction": "desc"
      }
    }
  ],
  "version": "1.0.0",
  "hash": "abc123",
  "updatedAt": "2025-01-01T00:00:00Z"
}

Field	Type	Description
`name`	string	Display name (2-50 characters)
`slug`	string	Unique identifier (lowercase a-z only)
`icon`	string	URL to source icon
`languages`	string[]	Supported language codes (at least one required)
`nsfw`	boolean	Whether source contains NSFW content by default
`url`	string	Base URL of upstream source
`referer`	string	Referer header for image requests (defaults to empty)
`auth`	object	Authentication configuration
`search`	object	Search capabilities (sort, filters, tags)
`presets`	array	Predefined search configurations
`version`	string	Semantic version
`hash`	string	Content hash for change detection
`updatedAt`	string	ISO 8601 timestamp of last update

Error Response

Standard error response format used across all endpoints.

{
  "error": {
    "code": "MANGA_NOT_FOUND",
    "message": "The requested manga could not be found"
  }
}

Field	Type	Description
`error.code`	string	Machine-readable error code (SCREAMING_SNAKE_CASE)
`error.message`	string	Human-readable error description

Common Error Codes

Code	HTTP Status	Description
`NOT_FOUND`	404	Resource not found
`MANGA_NOT_FOUND`	404	Manga does not exist
`CHAPTER_NOT_FOUND`	404	Chapter does not exist
`SOURCE_NOT_FOUND`	404	Source slug is invalid
`INVALID_REQUEST`	400	Request body is malformed
`MISSING_FIELDS`	400	Required fields not provided
`INVALID_CREDENTIALS`	401	Authentication failed
`RATE_LIMITED`	429	Too many requests
`UPSTREAM_ERROR`	502	Upstream source returned an error
`UPSTREAM_TIMEOUT`	504	Upstream source did not respond

Schemas

On this page