API Endpoints

Host Manifest

GET /

Returns the host manifest containing metadata about the host and a list of available sources. This is the first endpoint Alethia calls when a user adds a new host URL. It serves as the discovery mechanism for all sources provided by the host.

Alethia uses this endpoint to:

• Display the host name and author in the UI
• Enumerate available sources for the user to browse
• Check source versions and detect updates via hash comparison

Response Fields

Response

{
  "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"
    }
  }
}

Source Status Values

Source Metadata

GET /:source

Returns the complete configuration for a specific source. This endpoint provides Alethia with all the information needed to interact with the source, including supported search options, filters, authentication requirements, and UI presets.

Alethia calls this endpoint when:

• A user first enables a source
• Checking for source configuration updates
• Building the search UI with available filters and sort options

Response Fields

Response

{
  "name": "MangaDex",
  "slug": "mangadex",
  "icon": "https://example.com/icon.png",
  "languages": ["en"],
  "nsfw": false,
  "url": "https://mangadex.org",
  "referer": "https://mangadex.org",
  "auth": {
    "type": "none",
    "required": false
  },
  "search": {
    "sort": ["relevance", "latest", "popularity"],
    "filters": ["status", "contentRating", "includeTag"],
    "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"
}

Health Check

GET /:source/health

Returns the health status of the source itself. This is a lightweight endpoint that confirms the source adapter is running and can respond to requests. It does not check upstream connectivity — use /ping for that.

Use this endpoint for:

• Load balancer health checks
• Kubernetes liveness probes
• Basic monitoring and alerting

Response

{
  "status": "ok"
}

Upstream Ping

GET /:source/ping

Tests connectivity to the upstream source by making a lightweight request to the upstream API. Returns the connection status and latency. This helps diagnose whether issues are with your host or the upstream source.

Use this endpoint for:

• Diagnosing connectivity issues
• Monitoring upstream availability
• Displaying source status in the UI

Response Fields

Response (Success)

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

Response (Failure)

{
  "status": "down",
  "latencyMs": 5000,
  "error": "Connection timeout"
}

Authentication

POST /:source/authenticate

Alethia supports a degree of source-specific authentication. Technically, this involves providing (on the client), fields based on what is depended on the source's auth.type configuration. On success, returns headers that Alethia will include in subsequent requests to authenticated endpoints. (stored in Keychain and will clear on logout/reauth/authorization failure - usually an indicator of authentication expiring).

Alethia stores the returned headers securely and includes them in requests to /search, /:mangaSlug, /:mangaSlug/chapters, and /:mangaSlug/chapters/:chapterSlug.

Authentication Flow

Using Authentication Headers

When Alethia makes requests to the above mentioned endpoints, it includes any necessary authentication headers returned from the /authenticate route. Your host from here has a number of responsibilities:

1. Forwarding headers to upstream — Pass the authentication headers (Authorization, Cookie, etc.) to the upstream API when making requests (typically these are done through headers but some GraphQL-like services actually pass them into the body of the request - but generally your host is responsible for handling this nuance).
2. Validating auth requirements — If your source has auth.required: true, check that valid auth headers are present before processing the request. (technically not required but it's a good practice to avoid unnecessary upstream calls).
3. Returning appropriate errors — If auth is required but headers are missing or invalid, return an UNAUTHORIZED error (see Error Response).

Authentication Types

Sources declare their authentication requirements in the auth field of their configuration. Alethia currently supports the following six authentication types.

None

No authentication required. The /authenticate endpoint returns empty headers. Most public sources use this type.

Source Configuration

{
  "auth": {
    "type": "none",
    "required": false
  }
}

Request Body — Not needed, but if called:

{}

Response

{
  "success": true,
  "headers": {}
}

Basic

Username and password authentication. Typically used for sources with traditional login systems. The host validates credentials against the upstream API and returns an Authorization header.

Source Configuration

{
  "auth": {
    "type": "basic",
    "required": true,
    "fields": ["username", "password"]
  }
}

Request Body

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

Response

{
  "success": true,
  "headers": {
    "Authorization": "Basic dXNlcjpwYXNz..."
  }
}

Session

Username and password authentication that returns session cookies. Similar to basic auth but the upstream uses cookie-based sessions instead of stateless tokens. Common for traditional web applications.

Source Configuration

{
  "auth": {
    "type": "session",
    "required": true,
    "fields": ["username", "password"]
  }
}

Request Body

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

Response

{
  "success": true,
  "headers": {
    "Cookie": "session=abc123; user_id=456"
  }
}

API Key

Single API key authentication. Useful for sources that issue API keys through a dashboard or settings page rather than traditional username/password login. Common for self-hosted services like Komga.

Source Configuration

{
  "auth": {
    "type": "api_key",
    "required": true,
    "fields": ["apiKey"]
  }
}

Request Body

{
  "apiKey": "sk-abc123def456"
}

Response

{
  "success": true,
  "headers": {
    "X-API-Key": "sk-abc123def456"
  }
}

Bearer

Bearer token authentication. The user provides a pre-obtained token directly (e.g., from an OAuth flow, settings page, or external authentication). The host doesn't perform authentication — it just validates and passes through the token.

Source Configuration

{
  "auth": {
    "type": "bearer",
    "required": true,
    "fields": ["token"]
  }
}

Request Body

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

Response

{
  "success": true,
  "headers": {
    "Authorization": "Bearer eyJhbGciOiJIUzI1NiIs..."
  }
}

Cookie

Direct cookie authentication. The user provides raw cookie values, typically copied from browser developer tools. This is a fallback for sources with complex authentication (e.g., Cloudflare challenges, CAPTCHAs) that can't be automated.

Source Configuration

{
  "auth": {
    "type": "cookie",
    "required": true,
    "fields": ["cookie"]
  }
}

Request Body

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

Response

{
  "success": true,
  "headers": {
    "Cookie": "session=abc123; cf_clearance=xyz789"
  }
}

Error Responses

All authentication types are expected to return the same error format on failure:

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

Error Codes

(Ideal, but should generally be a valid kind of error code, to see all possible error codes, see the list of error responses..)

Search

POST /:source/search

Search for manga on the source. This is a POST request with a JSON body containing the search query, pagination, sorting, and filter parameters. The available sort options and filters depend on what the source declared in its configuration.

This endpoint powers:

• The main search functionality in Alethia
• Browse/discover pages using presets
• Filtered browsing by tags, status, etc.

Request Fields

Request Body

{
  "query": "one piece",
  "page": 1,
  "limit": 20,
  "sort": "relevance",
  "direction": "desc",
  "filters": {
    "status": ["ongoing"],
    "contentRating": ["safe", "suggestive"]
  }
}

Response Fields

Response

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

Entry Fields

Manga Details

GET /:source/:mangaSlug

Get detailed information about a specific manga. The mangaSlug comes from a search result's slug field (see Slugs). This endpoint returns comprehensive metadata including synopsis, authors, all covers, and full tag information.

Alethia calls this endpoint when:

• A user taps on a manga from search results
• Refreshing manga details in the library
• Building the manga detail page UI

Path Parameters

Response Fields

Response

{
  "slug": "one-piece",
  "url": "https://mangadex.org/title/...",
  "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...",
  "covers": ["https://...", "https://..."],
  "tags": ["action", "adventure", "comedy"],
  "classification": "Safe",
  "publication": "Ongoing",
  "createdAt": "2020-01-15T10:30:00Z",
  "updatedAt": "2024-12-01T08:00:00Z"
}

Chapters

GET /:source/:mangaSlug/chapters

Get the list of available chapters for a manga. Returns chapters in reverse chronological order (newest first). Each chapter includes metadata for display and a slug for fetching pages (see Slugs).

Alethia calls this endpoint when:

• Displaying the chapter list on a manga's detail page
• Checking for new chapters during library updates
• Building download queues

Path Parameters

Response Fields (per chapter)

Response

[
  {
    "slug": "chapter-1100",
    "url": "https://...",
    "title": "Chapter 1100: My Dear Hero",
    "number": 1100,
    "date": "2024-01-15T00:00:00Z",
    "language": "en",
    "scanlator": "TCB Scans"
  },
  {
    "slug": "chapter-1099",
    "url": "https://...",
    "title": "Chapter 1099",
    "number": 1099,
    "date": "2024-01-08T00:00:00Z",
    "language": "en",
    "scanlator": "TCB Scans"
  }
]

Chapter Pages

GET /:source/:mangaSlug/chapters/:chapterSlug

Get the page image URLs for a specific chapter. Returns an ordered array of image URLs that Alethia will display in the reader. The chapterSlug comes from the chapter list response (see Slugs).

Alethia calls this endpoint when:

• A user opens a chapter to read
• Pre-fetching pages for smoother reading
• Downloading chapters for offline reading

Path Parameters

Response

An array of image URLs in reading order:

[
  "https://uploads.mangadex.org/.../1.png",
  "https://uploads.mangadex.org/.../2.png",
  "https://uploads.mangadex.org/.../3.png"
]