> ## Documentation Index
> Fetch the complete documentation index at: https://docs.postsyncer.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Update Brand

> Change parts of a workspace's brand brain

## 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](https://docs.postsyncer.com/api-reference/brand/overview.md#kept-as-yours).

> [!NOTE]
>
> 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

**workspace\_id** `integer` *required*

The ID of the workspace, from [List workspaces](https://docs.postsyncer.com/api-reference/workspaces/list.md)

**identity** `object`

Who they are. Any of `name`, `description`, `slogan`, `offer`, `audience`, `location`, `languages`, `industries` and `socials`.

**voice** `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`.

**look** `object`

How they look. Any of `colors`, `fonts`, `photo_style` and `photo_avoid`.

**accounts** `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.

**competitors** `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](https://docs.postsyncer.com/api-reference/brand/overview.md#competitor-handles).

**learnings** `object`

Any of `wins`, `misses`, `repeat`, `avoid` and `trends`.

**rules** `object`

Their own rules: `never_say` and `always_include`.

**clear** `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](https://docs.postsyncer.com/api-reference/brand/overview.md#fields).

```json theme={null}
{
  "workspace_id": 12,
  "voice": {
    "formality": 3,
    "words_to_avoid": ["artisanal", "game-changer"]
  },
  "accounts": [
    { "account_id": 136, "voice_note": "Photos first. One short line." }
  ],
  "rules": {
    "always_include": ["A link to the shop"]
  }
}
```

### 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](https://docs.postsyncer.com/api-reference/brand/overview.md#the-brand-object) after the save. `meta` says what the save did:

**meta.changed** `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.

**meta.ignored** `array of strings`

Keys you sent that are no field a person sets. Nothing was saved for them.

```json theme={null}
{
  "data": {
    "workspace_id": 12,
    "version": 3,
    "status": "ready",
    "built_at": "2026-11-18T14:02:11+00:00",
    "voice": {
      "traits": ["Warm", "Plain-spoken"],
      "formality": 3,
      "words_to_avoid": ["artisanal", "game-changer"]
    },
    "accounts": [
      {
        "account_id": 136,
        "network": "instagram",
        "name": "Halden Coffee",
        "username": "haldencoffee",
        "voice_note": "Photos first. One short line.",
        "insight": "Reels of the roaster get about twice the usual views.",
        "numbers": null
      }
    ],
    "rules": {
      "never_say": ["cheap"],
      "always_include": ["A link to the shop"]
    },
    "edited": [
      "identity.description",
      "identity.location",
      "look.colors",
      "rules.never_say",
      "voice.emoji",
      "voice.formality",
      "voice.words_to_avoid",
      "rules.always_include",
      "accounts.136.voice_note"
    ]
  },
  "meta": {
    "changed": ["voice.formality", "voice.words_to_avoid", "accounts.136.voice_note", "rules.always_include"],
    "ignored": []
  }
}
```

(The brand object is shortened here. The full answer is the same as [Get brand](https://docs.postsyncer.com/api-reference/brand/get.md).)

A bad value is named at its place in the body:

```json theme={null}
{
  "message": "Formality is 1 to 5. (and 2 more errors)",
  "errors": {
    "voice.formality": ["Formality is 1 to 5."],
    "voice.emoji": ["Emoji is none, few or many."],
    "look.colors.0.hex": ["A colour is a hex code like #1E3A2F."]
  }
}
```

### Code Examples

```bash cURL theme={null}
curl -X PATCH "https://postsyncer.com/api/v1/brand" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "workspace_id": 12,
    "voice": {
      "formality": 3,
      "words_to_avoid": ["artisanal", "game-changer"]
    },
    "rules": {
      "always_include": ["A link to the shop"]
    }
  }'
```

```javascript Node.js theme={null}
const axios = require('axios');

const updateBrand = async () => {
  try {
    const response = await axios.patch('https://postsyncer.com/api/v1/brand', {
      workspace_id: 12,
      voice: {
        formality: 3,
        words_to_avoid: ['artisanal', 'game-changer']
      },
      rules: {
        always_include: ['A link to the shop']
      }
    }, {
      headers: {
        'Authorization': 'Bearer YOUR_API_TOKEN',
        'Content-Type': 'application/json'
      }
    });

    console.log('Changed:', response.data.meta.changed);
  } catch (error) {
    console.error('Error saving the brand:', error.response?.data || error.message);
  }
};

updateBrand();
```

```php PHP theme={null}
<?php

$data = [
    'workspace_id' => 12,
    'voice' => [
        'formality' => 3,
        'words_to_avoid' => ['artisanal', 'game-changer']
    ],
    'rules' => [
        'always_include' => ['A link to the shop']
    ]
];

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://postsyncer.com/api/v1/brand');
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'PATCH');
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: Bearer YOUR_API_TOKEN',
    'Content-Type: application/json'
]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

if ($httpCode === 200) {
    $result = json_decode($response, true);
    echo "Changed: " . implode(', ', $result['meta']['changed']);
} else {
    echo "Error: " . $response;
}
?>
```

```python Python theme={null}
import requests

data = {
    'workspace_id': 12,
    'voice': {
        'formality': 3,
        'words_to_avoid': ['artisanal', 'game-changer']
    },
    'rules': {
        'always_include': ['A link to the shop']
    }
}

headers = {
    'Authorization': 'Bearer YOUR_API_TOKEN'
}

# json= sends the body as JSON, with Content-Type: application/json.
response = requests.patch(
    'https://postsyncer.com/api/v1/brand',
    json=data,
    headers=headers
)

if response.status_code == 200:
    print('Changed:', response.json()['meta']['changed'])
else:
    print(f"Error: {response.status_code}")
    print(response.text)
```

### Error Codes

**400** `Bad Request`

The body is sent as JSON but isn't valid JSON: `The body is not valid JSON.` Nothing is saved.

**401** `Unauthorized`

Missing or invalid API token

**403** `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.`

**415** `Unsupported Media Type`

The body is not JSON: `Send the body as JSON.`

**422** `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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.