Skip to main content
PATCH

Update Brand

Changes parts of a workspace’s brand brain. Send only what changes. It saves the same way Settings → Brand does in the app. What you change is kept as yours: the brand brain never changes it again. See Kept as yours.
The body must be JSON, sent with Content-Type: application/json. A form body or any other content type is refused with 415, and JSON that won’t parse with 400. The query string is not read, so workspace_id goes in the body too.

Request

integer
required
The ID of the workspace, from List workspaces
object
Who they are. Any of name, description, slogan, offer, audience, location, languages, industries and socials.
object
How they sound. Any of traits, formality, energy, humour, emoji, sentence_length, point_of_view, hashtags, cta_style, words_to_use, words_to_avoid, notes and examples.
object
How they look. Any of colors, fonts, photo_style and photo_avoid.
array
How to sound on each account: a list of { "account_id", "voice_note" }. Only the accounts you send change. Each must be a connected account of this workspace.
array
The competitors they watch: up to 10 { "name", "handles" }, where handles is a list of { "network", "handle" }. This replaces the whole list. On a paid plan a new handle is read at once. Its state is in watch on Get brand.
object
Any of wins, misses, repeat, avoid and trends.
object
Their own rules: never_say and always_include.
array of strings
Fields to clear, by path, such as ["voice.humour", "voice.formality"]. Each is cleared as if you sent it null, for a client that can’t send null. It takes any field you can set outside accounts; an account’s voice_note clears with null or "". Don’t also send a field you clear here.
Each field’s type and limits are in Fields.

How a save works

  • Inside a section, only the fields you send change. The rest stay as they are.
  • A list is replaced whole. To add one word, send the full list with it.
  • null clears a field. For a list, null and [] both clear it.
  • clear clears the fields it names, the same as null. A field both sent and named in clear refuses the save with 422, at its place in clear (such as clear.0). A path in clear that is no field you can clear comes back in meta.ignored, such as clear.voice.mood.
  • Text is trimmed, and blank text is null. Blank list items are dropped, and a repeat (in any case) is kept once. Hex colours are upper-cased. A handle loses its leading @.
  • A value the brand already has is no change, and isn’t checked. You can send back what you read.
  • One bad value refuses the whole save with 422, and nothing is saved.
  • Keys that are no field a person sets are not saved. That means read-only fields (identity.website, look.logo_url), the brand brain’s own fields (an account’s insight and numbers, an example’s post_id, views and url) and unknown keys. They come back in meta.ignored, with * for a place in a list, such as accounts.*.insight.

Response

data is the brand object after the save. meta says what the save did:
array of strings
The fields this save changed, as paths. An account’s field is named by its ID, such as accounts.136.voice_note. Empty when nothing changed.
array of strings
Keys you sent that are no field a person sets. Nothing was saved for them.
(The brand object is shortened here. The full answer is the same as Get brand.) A bad value is named at its place in the body:

Code Examples

Error Codes

Bad Request
The body is sent as JSON but isn’t valid JSON: The body is not valid JSON. Nothing is saved.
Unauthorized
Missing or invalid API token
Forbidden
The key does not have the brand:update permission, or the key’s person is not an owner or manager of the workspace: You do not have permission to edit workspace.
Unsupported Media Type
The body is not JSON: Send the body as JSON.
Unprocessable Entity
workspace_id is missing, not a number, or a workspace the key’s person is not in (Invalid workspace ID.). Or a value is bad: each is named at its place in the body, such as voice.formality or accounts.0.account_id, with its limit. A field both sent and cleared is named at its place in clear. Nothing is saved.