Skip to main content

Authentication

API keys​

An API key acts for your account, not for the person who created it: a key keeps working when that colleague leaves, and records it creates name no person. Create one key per backend, script or automation, so you can revoke them one by one.

Create keys in the web app's account menu under Settings › API keys. If you logged in more than 10 minutes ago, Ghostpull asks you to confirm it's you first, with your passkey or a code from your email. The key is shown once, right after you create it. Store it in your password manager or your server's secrets; Ghostpull keeps only a hash and cannot show it again. A lost key is revoked and replaced.

Send it with every call:

curl "$GHOSTPULL_URL/api/v1/media/assets" -H "x-api-key: $GHOSTPULL_API_KEY"

Only the x-api-key header works; never put a key in a URL, and never into code that runs in a browser.

Permissions​

A key may only call what its permissions allow. Each operation in the API reference names the permission it needs.

PermissionAllows
addons:readList the Addons the account can run, with their inputs and price.
brands:readList the account's brands and read each brand and brand analysis.
brands:writeAnalyze a shop's brand from its URL, approve and edit brands, choose the default and delete brands.
media:readList and read every asset in the account's library, with download links.
media:uploadUpload images and videos into the account's library.
products:readList the account's catalogs and products, read each product, and follow product imports.
products:writeCreate, rename and delete catalogs, import product files and batches, and delete products.
runs:readList and follow every run of the account and read its results.
runs:createStart Addon runs and batches for the account, and make finished runs again with a note. Each run pays its price in credits.
runs:manageCancel the account's batches, start their failed items again, make finished items again with a note and choose which version an item shows. Each new run pays its price in credits.

A permission covers all of the account's data, not only what the key created. Select all gives a key the permissions that exist today; a permission added later is never on an existing key until you add it.

Expiry and revoking​

Every key gets an expiry when it is created: a period, a date, or Forever. An expired key stops working and has to be replaced.

Revoking a key stops new calls at once. Download links and open streams it already received remain usable until they expire or close. Runs it started keep running, but its batches start no more items; see Run batches.

Public API scope​

The current preview lets keys list Addons, upload and read media, start runs and batches, list and follow the account's runs and batches, cancel, retry and redo batches, redo runs with a note, manage catalogs and products, import product files from a shop's export, and analyze and manage brands. Keys cannot import into the media library from a URL, delete or restore media, or manage identity and billing. See Start runs, Follow runs, Run batches, Import products and Analyze a brand.

Creating keys and changing their permissions is available in the web app, not through an account key. Each operation in the API reference names the permission it needs.