URL Scheme
snipkap:// action reference. Path segments map to CLI positionals and query keys map to options. Current action Schema is 6.
snipkap:// shares action Schema 6, the same validation, and the same result codes as the CLI. Use it from browsers, Shortcuts, Raycast, Alfred, and other desktop apps.
A URL cannot return the result to the calling page. For a reliable result, use the CLI and pass --to for queries or OCR.
snipkap://<command>/<positional>?<query>Path segments map to CLI positional arguments. Query keys must be one of the names below. Order does not matter.
Encoding and limits
- Paths, spaces, and special characters must be UTF-8 percent-encoded. Space is
%20, plus is%2B. Example:/tmp/a b.png→%2Ftmp%2Fa%20b.png. - Credentials, ports,
#fragments, control characters, NUL, malformed encoding, empty query items, and undeclared parameters are rejected. - The same query name cannot repeat, except
pathonpin-paths. - Do not put secrets, tokens, or other sensitive values in a URL.
Dangerous URLs require confirmation
Web pages can also fire a custom scheme. Closing pins, quitting, writing any local file, deleting a history item, or clearing history asks the user to confirm. The CLI is treated as an explicit local instruction and skips that prompt, but it still never overwrites an existing file.
capture
snipkap://capture?mode=<mode>&output=<output>&irregular=<pen|freehand>&horizontal=<bool>&sides=<3..64>&width=<1..32768>&height=<1..32768>&to=<encoded-path>Include only the parameters the current mode needs. horizontal=true maps to the CLI --horizontal flag.
| Parameter | Type | Required | Notes |
|---|---|---|---|
mode | enum | no | rect, irregular, long, gif, fixed, delay, whiteboard. Aliases: rectangle, shape |
output | enum | no | interactive, clipboard, save, pin, history |
irregular | enum | freeform only | pen or freehand |
horizontal | boolean | no | Scrolling capture only. true / false / on / off / 1 / 0 |
sides | 3..64 | fixed shape only | Regular polygon sides |
width / height | 1..32768 | fixed shape only | Must appear together |
to | encoded path | when saving | Implies save. The target must not exist |
gif, delay, and whiteboard accept the default interactive output only.
snipkap://capture?mode=rect&output=clipboard
snipkap://capture?mode=long&horizontal=true&output=pin
snipkap://capture?mode=fixed&sides=6&width=800&height=600&to=%2Ftmp%2Fc.pngCreate pins
snipkap://pin-clipboard
snipkap://pin-paths?path=<encoded-path>&path=<encoded-path>...
snipkap://restore-pins| URL | Notes |
|---|---|
pin-clipboard | Pin the clipboard |
pin-paths | One pin per path, at most 256 items |
restore-pins | Restore the last saved click-through pins |
snipkap://pin-paths?path=%2Ftmp%2Fone.png&path=%2Ftmp%2Ftwo.pngpins
snipkap://pins/list[?to=<encoded-json-path>]
snipkap://pins/close/<id|all>
snipkap://pins/passthrough/<id|all>/<on|off>
snipkap://pins/rotate/<id|all>/<left|right|180>
snipkap://pins/mirror/<id|all>
snipkap://pins/opacity/<id|all>/<10..100>
snipkap://pins/scale/<id|all>/<10..1000>
snipkap://pins/reset/<id|all>
snipkap://pins/copy/<id>
snipkap://pins/save/<id>?to=<encoded-image-path>copy and save reject all. close and save ask the user to confirm.
snipkap://pins/passthrough/all/on
snipkap://pins/save/0123456789abcdef0123456789abcdef?to=%2Ftmp%2Fpin.pnghistory
snipkap://history/enable
snipkap://history/disable
snipkap://history/pause
snipkap://history/resume
snipkap://history/settings?days=<1..365>&maxEntries=<1..10000>
snipkap://history/open
snipkap://history/list[?to=<encoded-json-path>]
snipkap://history/latest
snipkap://history/pin?id=<id>
snipkap://history/copy?id=<id>
snipkap://history/save?id=<id>&to=<encoded-image-path>
snipkap://history/delete?id=<id>
snipkap://history/clear
snipkap://history/dock/show
snipkap://history/dock/hide
snipkap://history/dock/toggle| Query | CLI equivalent | Notes |
|---|---|---|
days | --days | Retention days 1..365. Must be paired with maxEntries |
maxEntries | --max-entries | Max items 1..10000. Camel case, not max-entries |
id | positional | 32 lowercase hex history ID |
to | --to | New file path; must not already exist |
delete and clear ask the user to confirm.
snipkap://history/settings?days=7&maxEntries=1024
snipkap://history/dock/showocr
snipkap://ocr/history/<id>[?output=<panel|clipboard|text|json>&to=<encoded-path>]
snipkap://ocr/path?path=<encoded-image-path>&output=<panel|clipboard|text|json>&to=<encoded-path>Default output=panel. text / json require to; panel / clipboard reject to.
| Parameter | Used by | Notes |
|---|---|---|
path | ocr/path only | Encoded local image path |
output | both sources | panel, clipboard, text, json |
to | text / json | New result file |
snipkap://ocr/history/0123456789abcdef0123456789abcdef?output=clipboard
snipkap://ocr/path?path=%2Ftmp%2Fimage.png&output=json&to=%2Ftmp%2Focr.jsonCapabilities and status
snipkap://capabilities[?to=<encoded-json-path>]
snipkap://status[?to=<encoded-json-path>]With to, a new JSON file is written and the user must confirm. Without to, only a desktop notice is shown. Agents should use the CLI --to form.
Settings and lifecycle
snipkap://smart-paste?enabled=<bool>
snipkap://launch-at-login?enabled=<bool>
snipkap://settings/open/general
snipkap://settings/open/ocr
snipkap://settings/open/capture-hotkey
snipkap://settings/open/pin-hotkey
snipkap://settings/open/permissions
snipkap://settings/open/history
snipkap://settings/open/personalization
snipkap://settings/open/watermark
snipkap://settings/open/translation
snipkap://settings/open/about
snipkap://preferences
snipkap://entitlement
snipkap://tool/scale-ruler
snipkap://tool/caliper
snipkap://tool/angle
snipkap://help
snipkap://about
snipkap://quitsmart-paste and launch-at-login require exactly the enabled query. watermark is an alias of the personalization watermark page. preferences opens General on Windows and the capture-hotkey page on macOS. quit asks the user to confirm.
Result codes
Same as the CLI. A URL cannot return the code to the calling page; machine callers should use the CLI.
| Code | Meaning |
|---|---|
0 | Success or accepted |
1 | Execution failed |
2 | Invalid arguments |
3 | Busy |
4 | File, history item, or pin not found |
5 | Permission denied or user declined |
6 | Unsupported on this platform |
7 | Resource limit exceeded |