Skip to content
Pinchana Docs

API quickstart

Pinchana API is a parent orchestration repository with Git submodules. Clone it recursively.

Terminal window
git clone --recurse-submodules https://github.com/Pinchana/pinchana-api.git
cd pinchana-api
cp .env.example .env
chmod 600 .env

Production minimum

Section titled “Production minimum”

The production Compose stack routes scraper traffic through Gluetun. Configure a WireGuard key and at least one independently revocable machine API key:

WIREGUARD_PRIVATE_KEY=REPLACE_WITH_PROVIDER_WIREGUARD_PRIVATE_KEY
PINCHANA_API_KEYS={"automation":"REPLACE_WITH_LONG_RANDOM_MACHINE_KEY"}

Spotify additionally requires:

SPOTIFY_CLIENT_ID=REPLACE_WITH_CLIENT_ID
SPOTIFY_CLIENT_SECRET=REPLACE_WITH_CLIENT_SECRET

If you are deploying Pinchana Web against this API, configure the separate Turnstile/browser-session values described in Authentication.

Pin coherent release images

Section titled “Pin coherent release images”

Do not deploy a mixture of mutable stable tags. Resolve the newest coherent release and write immutable digests into .env:

Terminal window
python scripts/update_rolling.py --env-file .env --dry-run
python scripts/update_rolling.py --env-file .env

The default updater advances the gateway and normal scraper images. Add --dlp only when the DLP profile should advance as part of the same release:

Terminal window
python scripts/update_rolling.py --env-file .env --dlp --dry-run
python scripts/update_rolling.py --env-file .env --dlp

Start the API

Section titled “Start the API”
Terminal window
docker compose --env-file .env config --quiet
docker compose --env-file .env up --detach
docker compose --env-file .env ps

Check the gateway:

Terminal window
curl --fail-with-body --silent --show-error http://127.0.0.1:8080/health

Call API v1

Section titled “Call API v1”
Terminal window
curl --fail-with-body --silent --show-error \
  --request POST http://127.0.0.1:8080/v1/scrape \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: REPLACE_WITH_MACHINE_KEY' \
  --data '{"url":"https://www.instagram.com/p/REPLACE_WITH_PUBLIC_SHORTCODE/"}'

A successful response uses the normalized shape:

{
  "data": {
    "id": "...",
    "source": {"platform": "instagram", "url": "https://...", "application": null},
    "content": {"title": null, "text": "...", "html": null, "published_at": null},
    "author": {"name": "...", "username": "..."},
    "media": []
  },
  "meta": {"api_version": "1"}
}

The API can add optional music, engagement, safety, and link metadata. Downloadable assets are always represented in the ordered data.media list.

Development stack

Section titled “Development stack”

For local source development without production VPN credentials:

Terminal window
docker compose --env-file .env -f docker-compose.dev.yml up --detach --build

The development Compose file uses normal bridge networking and direct service ports instead of sharing Gluetun’s namespace.

Next: Authentication, Endpoint reference, and Schemas.