Local API

The local API exposes JPGBoost as an HTTP/JSON service on your machine. It lets you drive imports, settings, and exports from any language capable of sending an HTTP request.

Enabling the API

The API is disabled by default. It activates in seconds:

1. Open Settings (⌘,) then the Local API tab.
2. Check the activation box. The server starts right away.
3. Adjust the port if needed. The default value is 51823.
4. Copy the authentication token shown just below. A button lets you regenerate it at any time.

Authentication

Every request must carry the Authorization header with your token. Without it, or with an invalid token, the API responds 401.

TOKEN="<token shown in Settings>"
BASE="http://127.0.0.1:51823/v1"

curl -s -H "Authorization: Bearer $TOKEN" "$BASE/status"

Route reference

All routes are prefixed with /v1 and return structured JSON: size before and after, compression ratio, and any error for each file.

Step-by-step examples

Check the current state

curl -s -H "Authorization: Bearer $TOKEN" "$BASE/status"

Import files

curl -s -X POST -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"paths": ["/path/to/image1.png", "/path/to/image2.jpg"]}' \
  "$BASE/import"

Change quality and format

curl -s -X POST -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"quality": 80, "format": "webp"}' \
  "$BASE/settings"

List the current images

The response gives, for each image, its ID, its status, its size before and after, its ratio, and any error.

curl -s -H "Authorization: Bearer $TOKEN" "$BASE/images"

Export the batch

Export waits for any compression in progress to finish before writing files. This wait timeout is configurable with waitTimeoutSeconds, set to 30 seconds by default.

curl -s -X POST -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"folder": "/output/path", "waitTimeoutSeconds": 30}' \
  "$BASE/export"

Clear the list

curl -s -X POST -H "Authorization: Bearer $TOKEN" "$BASE/clear"

Acting on a specific image

Every image has an ID, returned by /v1/images. It lets you handle it individually.

# Quality specific to one image
curl -s -X POST -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"quality": 92}' \
  "$BASE/images/<id>/quality"

# Revert to the global setting for this image
curl -s -X POST -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"quality": null}' \
  "$BASE/images/<id>/quality"

# Export a single image to a specific path
curl -s -X POST -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"path": "/output/path/photo.webp"}' \
  "$BASE/images/<id>/export"

# Remove an image from the batch
curl -s -X DELETE -H "Authorization: Bearer $TOKEN" "$BASE/images/<id>"

Export profiles via the API

The API exposes the same list of profiles as the interface. See the Export Profiles guide for the priority rule. On JPGBoost Free, the single-profile limit applies here too: POST /v1/profiles refuses to create a second profile, but still accepts overwriting the existing one under the same name.

# Create or replace a profile (same name = overwrite)
curl -s -X POST -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "Web JPEG", "format": "jpeg", "quality": 70, "destinationFolder": "/output/path"}' \
  "$BASE/profiles"

# List profiles
curl -s -H "Authorization: Bearer $TOKEN" "$BASE/profiles"

# Delete a profile (the space becomes %20 in the URL)
curl -s -X DELETE -H "Authorization: Bearer $TOKEN" "$BASE/profiles/Web%20JPEG"

# Apply a profile to the global settings
curl -s -X POST -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"profile": "Web JPEG"}' "$BASE/settings"

# Export to the profile's folder, without passing "folder" again
curl -s -X POST -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"profile": "Web JPEG"}' "$BASE/export"

Checking that everything works

Two scripts ship inside the app, under Contents/Resources. Run them with JPGBoost open and the API enabled. They prompt for the token on the keyboard, unless the TOKEN environment variable is already set, which lets you chain them in a continuous integration pipeline.

Check suite

Checks authentication, routing, and parameter validation, with a ✓/✗ output. Read-only by default; when given an image, it also performs a real import-and-export cycle.

SCRIPTS=/Applications/JPGBoost.app/Contents/Resources

"$SCRIPTS/test_local_api.sh"
"$SCRIPTS/test_local_api.sh" /path/to/image.png

Guided walkthrough

Steps through the full sequence described above in a readable way, from the refusal without a token to the final export, passing through status, import, settings, and the list.

"$SCRIPTS/local_api_demo.sh" /path/to/image.png

Security and privacy

• The server only listens on the loopback interface (127.0.0.1), meaning it's only reachable from your Mac. It is never exposed to the internet.
• No image ever travels over the internet. The API only drives the local compression engine.
• The token is generated on your machine. Regenerate it if you think it may have been exposed, for example after pasting it into a shared script.
• Disable the API when you're not using it: that's its default state.