Overview

Pinchana separates extraction, browser UX, authentication, and private downloads into clear trust boundaries.

Pinchana API

Pinchana/pinchana-api is the public orchestration repository. The gateway accepts URLs, matches them against config/modules.yaml, calls the appropriate scraper service, stores downloadable assets in a shared cache, and adapts results to the stable API v1 schema.

Production scraper and gateway containers share Gluetun’s network namespace. The gateway is the public HTTP entry point; individual scraper services are not meant to be exposed directly in production.

The normal module set is:

TikTok · Instagram · YouTube Shorts · SoundCloud · YouTube Music · Spotify · Deezer · Threads · Twitter/X

General YouTube downloads are not another scraper module. They use the optional DLP stack, an asynchronous browser-oriented service with per-job workers and encrypted cookie handoff.

Pinchana Web

Pinchana/pinchana-web is the official browser interface. It is a Next.js 16 server-backed application rather than a static API client.

The browser calls only same-origin /api/... routes. Next.js route handlers know the selected Pinchana API origin, forward signed browser sessions, rewrite protected media URLs, stream downloads, and keep the following values out of browser JavaScript:

• the server-only API URL;
• browser-session bearer tokens;
• project instance verification keys;
• API machine keys and API-side secrets.

Visitors are gated by Cloudflare Turnstile. Pinchana API verifies the one-use Turnstile token and returns a signed web-session token; Pinchana Web stores that token in an HttpOnly cookie.

Custom API instances

The official Web client does not accept arbitrary API URLs. A custom HTTPS origin must publish a project-issued Ed25519 certificate from GET /web/identity. The certificate binds the exact API origin, the Web hostname’s public Turnstile site key, issuance time, and expiry time.

This prevents the Web server from becoming a generic server-side request proxy and lets users distinguish project-approved instances from arbitrary endpoints.

Licenses

• Pinchana API and its public service repositories use the MIT license unless a repository states otherwise.
• Pinchana Web is AGPL-3.0-only.
• These docs describe public API/Web behavior only.

Continue with Supported platforms for URL coverage or Web architecture and authentication for the request flow.