Source Configuration

When Alethia requests GET /:source, your host must return a JSON object describing the source's metadata and capabilities. This tells Alethia what your source can do.

Full Example

{
  "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", "rating"],
    "filters": ["status", "contentRating", "includeTag", "excludeTag"],
    "tags": [
      { "slug": "action", "name": "Action", "nsfw": false },
      { "slug": "romance", "name": "Romance", "nsfw": false },
      { "slug": "adult", "name": "Adult", "nsfw": true }
    ]
  },
  "presets": [
    {
      "name": "Latest Updates",
      "description": "Recently updated manga",
      "request": {
        "query": "",
        "page": 1,
        "limit": 20,
        "sort": "latest",
        "direction": "desc"
      }
    }
  ],
  "version": "1.0.0",
  "hash": "abc123def456",
  "updatedAt": "2025-01-01T00:00:00Z"
}

Field Reference

Identity

Field	Type	Required	Description
`name`	string	Yes	Display name (2-50 characters)
`slug`	string	Yes	Unique identifier, lowercase letters only (a-z). See Slugs.
`icon`	string	Yes	URL to source icon image
`url`	string	Yes	Base URL of the upstream source
`referer`	string	No	Referer header for image requests (defaults to empty)

Content

Field	Type	Required	Description
`languages`	string[]	Yes	Array of supported language codes (e.g., `["en", "ja"]`)
`nsfw`	boolean	No	Whether source contains NSFW content by default (defaults to `false`)

Authentication

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

Field	Type	Values	Description
`type`	string	`none`, `basic`, `session`, `api_key`, `bearer`, `cookie`	Authentication method
`required`	boolean		Whether auth is required to use the source
`fields`	string[]		Field names required for auth (e.g., `["username", "password"]`)

Authentication Types:

Type	Fields	Description
`none`	—	No authentication required
`basic`	`username`, `password`	Username/password returning Authorization header
`session`	`username`, `password`	Username/password returning session cookies
`api_key`	`apiKey`	Single API key authentication
`bearer`	`token`	Pre-obtained bearer token
`cookie`	`cookie`	Raw cookie values (fallback for complex auth)

If type is "none", the source doesn't require authentication. See Endpoints > Authentication for detailed examples.

Search Capabilities

"search": {
  "sort": ["relevance", "latest", "popularity"],
  "filters": ["status", "contentRating"],
  "tags": []
}

Sort Options

Declare which sort options your source supports:

Value	Description
`relevance`	Search relevance
`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 to source
`updatedAt`	Last updated

Declare which filters your source supports:

Value	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

Presets

Presets are predefined searches configurations that users will by default have available when browsing on this particular source.

Mainly useful for showing initial content like the "Latest Updates" or "Popular This Week" at a glance. Users themselves can configure, remove or add new presets themselves on the actual client.

Request Translation

The preset request object uses the same standardized format that Alethia sends to your host's search endpoint. Your adapter is responsible for translating these fields into whatever format your upstream source expects — REST query parameters, different JSON structures, GraphQL queries, or custom headers. This abstraction allows Alethia to work with any source regardless of the upstream API design.

"presets": [
  {
    "name": "Popular This Week",
    "description": "Most popular manga this week",
    "request": {
      "query": "",
      "page": 1,
      "limit": 20,
      "sort": "popularity",
      "direction": "desc"
    }
  }
]

Versioning

Field	Type	Description
`version`	string	Semantic version (e.g., `1.0.0`)
`hash`	string	Content hash for change detection
`updatedAt`	string	ISO 8601 timestamp of last update

Alethia uses version and hash to detect when sources have been updated and prompt users to refresh.

Configuration