Hacktoberfest 2026: the issues maintainers tagged for October, open and beginner-friendly. Browse Hacktoberfest issues

Add provider: Knaben (JSON meta-indexer API)

Open
  • Is something wrong?
#175 0 comments 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 1 day

Nobody has claimed this yet.

Assessment

Difficulty
3/5
Estimated time
1-2 days
Newbie friendliness
58/100
Issue type
Feature
Clarity
Clearly specified
Activity status
Active
Tech stack
javascript
Domain
api, backend

Research direction

Start with scraper/providers/_template.js and its Shape B JSON API branch, then read lib/magnetHelper.js and lib/httpClient.js for info hash extraction and POST support. Register the provider in providers/index.js; run npm test from scraper and try the two provided movie and series curl requests. Done means results use the specified API mapping and both requests return streams.

Written by the indexing model from the issue text.

Description

enhancement good first issue provider

The site

Knaben is a meta-indexer: it aggregates many trackers and
exposes a single JSON API, so one provider widens coverage across all of them.

It has a real documented JSON API, which makes this the most pleasant
provider in the codebase to write. No HTML scraping, no Cloudflare.

The API

POST https://api.knaben.org/v1 with a JSON body.

curl -X POST https://api.knaben.org/v1 \
  -H 'Content-Type: application/json' \
  -d '{
    "query": "The Godfather 1972",
    "search_type": "100%",
    "size": 50,
    "order_by": "seeders",
    "order_direction": "desc",
    "hide_unsafe": true
  }'

Use search_type: "100%". This matters and is the one thing to get right.
Verified against the live API:

search_type Top result for "The Godfather 1972"
"100%" The Godfather (1972) 1080p BrRip x264 - YIFY (1046 seeders)
"score" Advanced SystemCare Ultimate 12.1.0.119 (unrelated)
"all_words" no results

score sorts by the site's own relevance metric and returns garbage for this
shape of query.

Response shape

Each entry in hits[]:

{
  "title": "The Godfather (1972) 1080p BrRip x264 - YIFY",
  "hash": "144E5E1787668A9D9F6460674F597835E957C70E",
  "magnetUrl": "magnet:?xt=urn:btih:144E5E...",
  "bytes": 854600000,
  "seeders": 1046,
  "liveSeeders": 941,
  "peers": 0,
  "livePeers": 0,
  "category": "Movies / HD",
  "categoryId": [2000000],
  "tracker": "1337x",
  "date": "2026-09-15T15:01:00+00:00",
  "virusDetection": 0.0
}

Mapping notes, all of which are the interesting part of this task:

  • hash is UPPERCASE hex. Do not use it directly. Pass magnetUrl through
    extractInfoHash from lib/magnetHelper.js, which handles the casing and
    the base32 case. See #174 for why this is not a nitpick.
  • Prefer liveSeeders over seeders. seeders is the value cached from
    the origin tracker and goes stale; liveSeeders is from a recent scrape. Fall
    back to seeders when liveSeeders is missing or 0.
  • bytes maps straight to size. No parsing needed.
  • category is a string like "Movies / HD", "TV / HD", "Audio". The
    aggregator's content filter will drop obvious mismatches anyway, but
    filtering out non-video categories here saves work downstream. categoryId
    2000000 is the Movies/TV range.
  • Set hide_unsafe: true. There is also a virusDetection float per hit.

How to start

cd scraper/providers
cp _template.js knaben.js

Use the Shape B (JSON API) branch in the template. You will need a POST
rather than a GET, so take the limiterKey: id pattern from the template and
call axios through lib/httpClient.js. If httpClient has no POST helper,
adding a minimal one alongside get is in scope for this issue; keep the same
rate limiter and header defaults.

Then register it in providers/index.js and verify:

cd scraper && npm test
curl "localhost:8080/streams/movie/tt0068646?providers=knaben"
curl "localhost:8080/streams/series/tt0944947:2:3?providers=knaben"

Full walkthrough: CONTRIBUTING.md

Comment here to claim it.

Dominant language
JavaScript
Stars
48
Forks
18
Avg merge
1h 37m
Merged PRs (30d)
22

Getting set up

  • Ships a Dockerfile or Docker Compose file
  • No pull request template
  • No contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from peterdsp/Magnetio

All issues in peterdsp/Magnetio

Similar issues

More JavaScript issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.