Skip to Content
APIEndpointsUpdate brand profile

Update brand profile

Updates the brand’s identity and descriptions: name, industry, aliases, short and detailed descriptions, brand strengths and main market. These are the same fields the Identity and Descriptions tabs of the Brand Profile page edit, and they land in the same place.

This is a PATCH, not a PUT. Send only the fields you want to change: omit a field to leave it alone, or pass null to clear it. There is no whole-document replace on this API, because one that silently cleared the fields you did not send would be a data-loss bug wearing the right verb.

Requires the write:brand_profile scope, and the workspace must be enabled for API writes.

PATCH /v1/brands/{brand_id}/profile

Authorization

HeaderTypeRequired
AuthorizationBearer asky_sk_…required
Idempotency-Keystringrequired

Path parameters

ParameterTypeRequiredDescription
brand_iduuidrequiredFrom List brands

Query parameters

None.

Any parameter you pass returns 400 invalid_request naming the offending key, rather than being ignored silently.

Body

application/json. At least one field is required — an empty body returns 400 invalid_request rather than reporting success for a call that changed nothing.

FieldTypeRequiredDescription
namestring, 1–100 charsoptionalMay also rename the workspace. See Notes
industrystring | null, up to 200 charsoptionalUsed for positioning and competitor benchmarks
positioning_statementstring | null, up to 2000 charsoptionalThe brand’s intended positioning. null clears it
main_marketstring | null, ISO country codeoptionalThe primary market. It is always one of markets_served
markets_servedstring[] | null, ISO country codesoptionalEvery market the brand sells in. Replaces the list
market_languagesobject | nulloptionalLanguages per market, keyed by country, such as {"CH": ["de-CH", "fr-CH"]}. Replaces the whole map
short_descriptionstring | null, up to 1000 charsoptionalConcise summary
descriptionstring | null, up to 5000 charsoptionalDetailed description
aliasesstring[] | null, max 50optionalOther names the brand is referenced by. Replaces the list, except Korean spellings Asky added (see Notes). null or [] clears the rest
remove_aliasesstring[], 1 to 50optionalAliases to remove, matched ignoring case and extra spaces, applied after aliases. The way to remove a Korean spelling Asky added
key_featuresstring[] | null, max 50optionalBrand strengths, up to 200 characters each. The legacy key is retained. null or [] clears them; omit to preserve existing entries. Product capabilities belong on products.

Every limit matches what the Brand Profile page enforces, so a value written here is one the page can save back.

Request

curl --request PATCH \ --url 'https://api.askylabs.com/v1/brands/242546de-4cee-4a7d-952e-f6aa60c63ef8/profile' \ --header 'Authorization: Bearer <api-key>' \ --header 'Idempotency-Key: <unique-per-attempt>' \ --header 'Content-Type: application/json' \ --data '{"industry":"B2B SaaS - AI Search Optimization Platforms"}'

Response

{ "data": { "profile": { "name": "Asky", "aliases": ["Asky Labs"], "korean_spellings": [], "industry": "B2B SaaS - AI Search Optimization Platforms", "short_description": "AI search visibility monitoring.", "description": "Asky tracks how brands appear across AI search engines…", "main_market": "Europe", "key_features": ["Implementation support from an AI search specialist team"] } }, "request_id": "req_7d21b0af59c34e18b6ac" }

Response fields

The complete profile after the change, so you can put it straight into a cache without a follow-up read. The shape matches the corresponding fields of Get brand profile.

FieldTypeDescription
data.profile.namestringrequired
data.profile.aliasesstring[]required. [] when none
data.profile.korean_spellingsstring[]required. The aliases that are Korean spellings of the name. [] when none
data.profile.positioning_statementstringrequired. Empty when not set
data.profile.markets_servedstring[]required. Primary first
data.profile.marketsobject[]required. { country, languages, primary } per market
data.profile.key_featuresstring[]required. [] when none
data.workspace_renamedbooleanpresent only when name changed. false when the workspace has several brands and was deliberately left alone
request_idstringrequired. Also returned as the x-request-id header

Errors

StatusCodeWhen
400invalid_requestAn unknown field, a value over its limit, or a body with no fields
401invalid_tokenThe key is missing, malformed, or does not exist
403plan_requiredThis workspace is not enabled for API writes
403insufficient_scopeThe key lacks write:brand_profile, or is brand-restricted and attempted a rename. The message distinguishes them
404not_foundThe brand does not exist, or this key is not allowed to reach it. The two are deliberately indistinguishable
409conflictThe brand has no analysed profile yet, so there is nothing to update
429rate_limitedOver 60 requests per minute. See the Retry-After header

Notes

primary_audience is retired. Who the brand serves now lives in its audiences: list and edit them with the audiences endpoints. Sending primary_audience here returns 400 invalid_request as an unknown field, and the profile no longer returns it.

Renaming the brand may also rename its workspace, on exactly the same rule the app uses: only when the workspace holds a single active brand, and the workspace becomes "{name} Workspace". A workspace with several brands is left alone, because renaming a shared workspace after one of its brands would be wrong. data.workspace_renamed reports which happened, read back from the database rather than assumed.

Because that reaches an entity above the brand, a key restricted to specific brands may not do it: renaming would let a credential deliberately narrowed to one brand change the workspace it lives in. Such a key gets 403 insufficient_scope with a message naming that reason, and every other field still updates normally. A key with access to all brands behaves exactly like the app.

The workspace rename runs after the brand rename and is reported separately as data.workspace_renamed. false is the normal answer for a multi-brand workspace and needs no action. The brand rename itself always succeeds or the call fails, so a 200 means the brand was renamed either way.

Markets and their languages. A nonempty market list always has one primary: the current primary stays when it is still listed, otherwise main_market or the first market takes over. Languages of a market you remove are dropped. market_languages replaces every chosen language at once: a market left out of it goes back to its usual languages. Markets describe where the brand sells: they do not start tracking prompts there or change the language articles are written in.

null clears, omission preserves. {"description": null} empties the detailed description; leaving description out entirely keeps whatever is there. For aliases and key_features, both null and [] clear the list, except the Korean spellings below.

Korean spellings Asky added stay until you remove them. Asky may add up to three Korean spellings of the brand name to its aliases, so mentions written in Korean count; the profile lists them in korean_spellings. Replacing aliases keeps them even when the new list leaves them out, because a list read before Asky added one would otherwise remove it unseen. Name a spelling in remove_aliases to remove it; Asky does not add it again. Sending it back in aliases later makes it your own alias.

Not editable here: domains, sitemaps, documentation sources, social profiles, connected social accounts and writing styles. Each either asserts ownership of something outside Asky, schedules crawl work, or holds credentials — none are text edits, so none sit behind this scope. Manage them in the app.

Changing the profile does not re-run anything. Prompt suggestions and alignment read the profile when they next run; updating it does not trigger a refresh, matching the app.

Idempotency-Key is required. Send a unique value per attempt and reuse it when retrying that attempt: a retry replays the original response instead of executing again. See Idempotency.

Last updated on