Endpoint reference

This page describes the public gateway surface. Scraper service ports are implementation details; integrations should call the gateway.

Canonical machine API

`POST /v1/scrape`

Authentication: X-API-Key

Request:

{"url":"https://www.instagram.com/p/SHORTCODE/"}

Returns the stable API v1 {data, meta} envelope. This is the canonical route for new machine integrations.

`POST /scrape`

Authentication: X-API-Key

Compatibility route using the same validation/routing limits but returning the older flat response. Existing clients can continue using it; new clients should use /v1/scrape.

`GET /media/{path...}`

Authentication: X-API-Key

Serves protected files from the shared media cache. Supports byte-range behavior required by media players/downloaders. A media URL returned by a machine scrape is not intentionally public; send the same machine credential when retrieving it.

Browser-session API

These routes are consumed by Pinchana Web’s server-side BFF, not directly by ordinary browser UI code.

`POST /web/verify`

Accepts a one-use Cloudflare Turnstile token. API calls Siteverify, validates configured hostname/action, and returns a signed browser-session token on success.

`GET /web/session`

Validates the signed browser-session bearer token and returns its status/expiry metadata.

`GET /web/identity`

Publicly returns the configured project-issued custom-instance certificate envelope. If no certificate is installed, the route can return 503.

`GET /web/build`

Public sanitized build manifest containing the API release and public repository/module revisions baked into the deployment. It does not expose secret configuration or infrastructure details.

`POST /v1/web/scrape`

Authentication: signed web-session bearer token

Canonical browser scrape route. Returns the same normalized v1 contract as /v1/scrape, but protected media paths are under /web/media/....

The current Pinchana Web client requires this route.

`POST /web/scrape`

Legacy browser compatibility route. Current Web uses /v1/web/scrape instead.

`GET /web/media/{path...}`

Authentication: signed web-session bearer token

Streams protected cache media for a verified browser session, including range requests.

`GET /web/capabilities`

Authentication: signed web-session bearer token

Advertises optional browser features. Current Web checks whether DLP reports available: true and protocol: 2, then narrows its YouTube controls to advertised option lists.

`POST /web/convert/gif`

Authentication: signed web-session bearer token

Converts an authenticated already-cached media file to GIF with bounded server-side FFmpeg limits. It does not accept arbitrary uploads or remote URLs.

Browser DLP routes

When DLP_ENABLED=true and the internal DLP stack is healthy, the gateway exposes owner-bound routes under /web/dlp/jobs... for:

allocating a job;
submitting validated fixed download options and optional cookie ciphertext;
reading job state/progress;
streaming the completed file.

Pinchana Web proxies these as same-origin /api/dlp/jobs... routes. The internal pinchana-dlp API is not exposed directly to browsers.

See DLP protocol v2 for the job and encryption model.

Health and administration

`GET /health`

Public gateway/VPN health summary used for deployment checks.

`GET /admin/vpn/status`

Authentication: X-API-Key

Returns VPN/Gluetun status information.

`POST /admin/vpn/rotate`

Authentication: X-API-Key

Requests an immediate VPN rotation through the configured Gluetun control API.

`GET /admin/modules`

Authentication: X-API-Key

Returns configured module status/metadata.

`DELETE /admin/mobile/installations/{installation_id}`

Authentication: X-API-Key

Revokes a native-client installation and its refresh-token families when mobile installation sessions are in use.

Mobile installation sessions

These endpoints belong to the API but are not used by Pinchana Web:

POST /v1/mobile/challenges
POST /v1/mobile/grants
POST /v1/mobile/session/refresh
DELETE /v1/mobile/session
POST /v1/mobile/attest — deprecated alias for older clients

They use scoped installation access/refresh tokens rather than machine keys or browser sessions.

Errors

API v1 errors use:

{
  "error": {
    "code": "unsupported_url",
    "message": "...",
    "details": null
  }
}

See Errors and media lifecycle for authentication, upstream, cache, and media behavior.