Skip to main content

Analyze a brand

Start an analysis of a shop's address, read the brand Ghostpull drafts from its home page, approve it, and pass the brand to Addon runs. Starting and approving need brands:write; reading needs brands:read. An analysis costs no credits.

Before you start​

Set GHOSTPULL_URL and GHOSTPULL_API_KEY as in the quickstart, with a key that has both brands permissions. The shop's home page must be public. The bash/zsh and fish examples also need jq.

A wrong guess is never saved by itself: only approving makes or replaces a brand. Approve a draft only after a person has checked it.

1. Start the analysis​

startBrandAnalysis takes the shop's address in any form (yourshop.com, https://www.yourshop.com/products/x). A shop is told apart by its host, so analyzing it again drafts the same shop's brand again. The call answers 202 with the analysis:

curl --fail-with-body -X POST "$GHOSTPULL_URL/api/v1/brands/analyses" \
-H "x-api-key: $GHOSTPULL_API_KEY" -H "Content-Type: application/json" \
--data '{"url":"yourshop.com"}' --output analysis.json
ANALYSIS_ID=$(jq -r '.id' analysis.json)
{ "id": "0193…", "url": "https://yourshop.com/", "status": "reading", "failure": null, "events": [], "draft": {}, "logoUrl": null, "iconUrl": null, "brandId": null, … }

A key may start 10 analyses an hour and 30 a day. Over a limit the call answers 429; wait the seconds in Retry-After. An address that is no public web address answers 400 with brands.invalid_url.

2. Read the draft​

getBrandAnalysis answers the analysis as it stands. Call it every second or two until status is done or failed. The draft is ready in about 20 seconds, and an analysis never runs longer than a minute:

curl --fail-with-body "$GHOSTPULL_URL/api/v1/brands/analyses/$ANALYSIS_ID" \
-H "x-api-key: $GHOSTPULL_API_KEY" --output analysis.json
jq -r '.status' analysis.json

While it runs, status goes from reading to analyzing, events lists what was found in order, and draft fills in as findings arrive: the logo first, then the colors, the fonts and the tone. Each part of the draft, such as colors, comes whole or not at all:

{
"status": "done",
"events": [{ "key": "read", "text": "…", "at": "…" }, …],
"draft": {
"name": "Your Shop",
"colors": { "primary": "#1a2b3c", "secondary": "#…", "accent": "#…", "background": "#…", "text": "#…", "extra": [] },
"fonts": { "heading": { "family": "…", "fallback": "serif", "source": "google" }, "body": { … } },
"tone": { "summary": "…", "keywords": ["…"], "audience": "…" },
"look": "…",
"voice": "…",
"logo": { "key": "…", "mediaType": "image/png" },
…
},
"logoUrl": "https://…",
"iconUrl": "https://…",
"brandId": null,
…
}

logoUrl and iconUrl show the draft's logo and icon. They are made again with every answer and stop working within 15 minutes, sometimes sooner: read the brand or analysis again for fresh ones, and never store them. The profile itself holds only references to the files, logo and icon, and requests send only those.

A done analysis can still have an empty look and voice and a neutral tone, when Ghostpull could not draft them (for example, the drafting step failed). Check them before you approve.

A failed analysis has a failure and saved nothing; start it again with startBrandAnalysis:

failureMeaning
not_publicThe address does not name a public site: its name does not resolve, or it points to a private network.
blockedThe shop refused the visit or keeps automated visitors out.
not_foundThe home page answered that it does not exist.
not_htmlThe address is not a web page.
unreachableThe shop did not answer in time, answered with an error, or the connection was lost.

3. Approve it​

approveBrandAnalysis saves the brand of a done analysis and answers it. Without a profile, the draft becomes the brand as it is:

curl --fail-with-body -X POST "$GHOSTPULL_URL/api/v1/brands/analyses/$ANALYSIS_ID/approve" \
-H "x-api-key: $GHOSTPULL_API_KEY" -H "Content-Type: application/json" \
--data '{}' --output brand.json
BRAND_ID=$(jq -r '.id' brand.json)

To approve what the person changed, send the whole brand profile as profile. This keeps the draft, changes the name, and sends it:

jq '{profile: (.draft | .name = "Your Shop Ltd")}' analysis.json > approve-request.json
curl --fail-with-body -X POST "$GHOSTPULL_URL/api/v1/brands/analyses/$ANALYSIS_ID/approve" \
-H "x-api-key: $GHOSTPULL_API_KEY" -H "Content-Type: application/json" \
--data-binary @approve-request.json --output brand.json

A shop has one brand. If it has none, approving creates it, and it becomes the account's default when the account has no default yet. If it has one, approving replaces its fields and keeps its id and default flag. So to refresh a brand, analyze its shop again and approve the result; the new profile replaces every field, edits included.

logo and icon must be the account's own ready images or SVGs: the analysis' own, or a library asset you reference. Anything else answers 400 with brands.invalid_image, and details.field names the field. Approving an analysis that is not done answers 409 with brands.analysis_not_done; details.status says where it is. Approving the same analysis again stores the same profile again.

4. Use the brand in a run​

An Addon that takes a brand lists an input of type brand in listAddons. Pass the brand's id as that input in startOrchestratorRun, as described in Start runs:

{ "addonId": "…", "inputs": { …, "brand": "0193…" }, "maxCredits": 10, "idempotencyKey": "…" }

listBrands answers the brand IDs, the default first. Use null for a run without a brand. When you leave the input out, the run takes the brand the account saved in the Addon's settings, otherwise the account's default brand, otherwise none. An unknown brand ID answers 404.

The run keeps the brand as it was when it started: a later edit or deletion changes new runs only, and retries and redos reuse it. A brand never blocks a run; a logo that is gone from the media library is left out.

Read and manage brands​

OperationNeedsWhat it does
listBrandsbrands:readLists the account's brands, the default first.
getBrandbrands:readReads one brand with its whole profile.
updateBrandbrands:writeReplaces the profile with the whole one you send; a logo or icon you leave out is removed.
setDefaultBrandbrands:writeMakes the brand the account's default.
deleteBrandbrands:writeDeletes the brand and answers 204. Its analyses and media files stay.

Deleting the default brand leaves the account without a default until you choose another with setDefaultBrand, or approve the next brand, which becomes the default when there is none. A brand's logoUrl and iconUrl work like the analysis' links, and shopUrl is the address of its shop: null for a brand without a shop, or when the shop is gone. Making the default brand the default again changes nothing, and two changes of the account's brands at the same moment answer 409 with brands.changed_meanwhile: send the call again.

Next​