Sharing and bookmarklets

Share video URLs with bookmarklets and scoped tokens

Available in 2026.10.19. Bookmarklets open a video URL for review in your signed-in browser. Scoped share tokens let an external shortcut or tool submit a single video using one fixed media profile.

These are two separate flows: the bookmarklet does not need a share token, and the token API submits download work without an interactive review screen.

Use the bookmarklet

1. Open Settings > API & Access and find the bookmarklet section.
2. Save the provided bookmarklet to your browser's bookmarks bar.
3. Open a YouTube video and activate that bookmark.
4. Sign in to Pinchflat-ngx if required. Review the video and profile in Browse, then explicitly submit the download.

Opening the bookmarklet alone does not enqueue a download. It uses the configured External Base URL when present, otherwise the current application origin/path. If it opens the wrong address, correct External Base URL and copy the bookmarklet again. A browser that blocks bookmarklets or new windows may require you to paste the URL manually instead.

Create a scoped token

1. Create the intended media profile first.
2. Open Settings > API & Access > Create New Share Token.
3. Enter a client name and choose the Bound Media Profile.
4. Choose Never or 30 days under Expires after, then choose Create Token.
5. Copy the secret immediately and store it in your client. It is shown only once. Dismiss the secret banner when finished.

The token cannot change the assigned profile, download format, output path or settings, and cannot force a download past normal restrictions. Treat it as a credential. The token list shows status, expiry and last use without revealing the secret again.

Submit from a shortcut or API client

Send a JSON POST to your application's /api/share/intake route:

curl --request POST 'https://pinchflat.example.com/api/share/intake' \
  --header 'Authorization: Bearer YOUR_SHARE_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{"url":"https://www.youtube.com/watch?v=VIDEO_ID"}'

Replace the host, token and VIDEO_ID with your values. Include your deployment prefix when using a subpath. The example queues work when run with a valid eligible video; it is not a read-only check. Use the generated example in Settings for the current application address.

Only an individual YouTube video is accepted. Channels/playlists and profile/force overrides are rejected. The body limit is 8 KiB and the per-token rate limit is 10 requests per minute. A 202 response means accepted, not completed.

Response	Next step
401	Check token validity, expiry and revocation.
409	Video is already present or queued; inspect it instead of repeating the request.
413 / 415	Reduce the body size / send application/json.
422	Check the video URL, bound profile and reported download policy.
429	Wait according to Retry-After before retrying.
423 / 503 during migration	Complete migration review or transfer before submitting more work.

Revoke access

Choose Revoke beside the token and confirm. New requests are rejected; already accepted downloads are not cancelled. Delete removes the token record. If you lose the secret or a profile is deleted, create a new token for a valid profile and update the client.

Scoped tokens do not authorize general management API calls. See API access for Basic Auth and OIDC behavior.

All feature guides