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:
- bash / zsh
- fish
- PowerShell
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)
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
set ANALYSIS_ID (jq -r '.id' analysis.json)
curl.exe --fail-with-body -X POST "$env:GHOSTPULL_URL/api/v1/brands/analyses" `
-H "x-api-key: $env:GHOSTPULL_API_KEY" -H "Content-Type: application/json" `
--data '{\"url\":\"yourshop.com\"}' --output analysis.json
$env:ANALYSIS_ID = (Get-Content analysis.json -Raw | ConvertFrom-Json).id
{ "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:
- bash / zsh
- fish
- PowerShell
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
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
curl.exe --fail-with-body "$env:GHOSTPULL_URL/api/v1/brands/analyses/$env:ANALYSIS_ID" `
-H "x-api-key: $env:GHOSTPULL_API_KEY" --output analysis.json
(Get-Content analysis.json -Raw | ConvertFrom-Json).status
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:
failure | Meaning |
|---|---|
not_public | The address does not name a public site: its name does not resolve, or it points to a private network. |
blocked | The shop refused the visit or keeps automated visitors out. |
not_found | The home page answered that it does not exist. |
not_html | The address is not a web page. |
unreachable | The 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:
- bash / zsh
- fish
- PowerShell
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)
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
set BRAND_ID (jq -r '.id' brand.json)
curl.exe --fail-with-body -X POST "$env:GHOSTPULL_URL/api/v1/brands/analyses/$env:ANALYSIS_ID/approve" `
-H "x-api-key: $env:GHOSTPULL_API_KEY" -H "Content-Type: application/json" `
--data '{}' --output brand.json
$env:BRAND_ID = (Get-Content brand.json -Raw | ConvertFrom-Json).id
To approve what the person changed, send the whole brand profile as
profile. This keeps the draft, changes the name, and sends it:
- bash / zsh
- fish
- PowerShell
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
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
$analysis = Get-Content analysis.json -Raw | ConvertFrom-Json
$analysis.draft.name = "Your Shop Ltd"
@{ profile = $analysis.draft } | ConvertTo-Json -Compress -Depth 10 | Set-Content -Encoding utf8NoBOM approve-request.json
curl.exe --fail-with-body -X POST "$env:GHOSTPULL_URL/api/v1/brands/analyses/$env:ANALYSIS_ID/approve" `
-H "x-api-key: $env: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
| Operation | Needs | What it does |
|---|---|---|
listBrands | brands:read | Lists the account's brands, the default first. |
getBrand | brands:read | Reads one brand with its whole profile. |
updateBrand | brands:write | Replaces the profile with the whole one you send; a logo or icon you leave out is removed. |
setDefaultBrand | brands:write | Makes the brand the account's default. |
deleteBrand | brands:write | Deletes 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.