---
title: "Call the updateBrandProfile MCP tool"
method: POST
path: "/api/v1/actions/updateBrandProfile"
tags: ["Actions"]
---

# Call the updateBrandProfile MCP tool

`POST /api/v1/actions/updateBrandProfile`

## Request

- Base URL: `https://app.reachium.io`
- URL: `https://app.reachium.io/api/v1/actions/updateBrandProfile`
- Auth: HTTP bearer

Add to, or (only when the user asked for a change) replace parts of, the workspace's brand profile: ICP, market, positioning, competitors, proof, story, offer, conversation (objections/FAQ/policy), lexicon, style exemplars, case studies, people, guardrails, content pillars, updates, links, tone. Two-step: the FIRST call (no confirm_token) writes nothing and returns a preview (per section: what will be added, what is skipped because it is already set, and old vs new for `replace` sections) plus a confirm_token. Write the full proposal out to the user, ask whether to upload it to Reachium, then call again with the SAME patch/replace/source plus confirm_token. Add-only by default: existing values are never overwritten unless their section is listed in `replace`. Read getPlaybook("copywriting", "brand-profile-fields") before filling anything in.

Called through the Actions bridge: the response is that tool's own result, wrapped as `{ data: <tool result> }` under HTTP 200. Billing, daily-cap, and confirm-step outcomes are embedded INSIDE `data`, never remapped to an HTTP status (see the templated `/api/v1/actions/{toolName}` operation above for the full protocol, and `x-mcp-actions` for this tool's machine-readable scope/cap/confirm_behavior fields). Authentication, request-shape, and optional idempotency-protocol failures still use their documented non-200 statuses.

## Headers

- `Idempotency-Key` string

## Request body

- object
  - `patch` object, required: Any subset of brand profile sections. Long text up to 2000 chars, short fields 500, lists trimmed to their caps.
    - `company_name` string
    - `website` string
    - `executive_summary` string
    - `icp` object
      - `target_buyers` object[]
        - `title` string, required
        - `description` string, required
      - `segments` object[]
        - `name` string, required
        - `description` string, required
      - `pain_points` string[]
      - `verbatim_phrases` string[]
      - `buying_triggers` string[]
      - `anti_icp` string
      - `sophistication` string
    - `market_research` object
      - `industry` string
      - `niche` string
      - `landscape` string
      - `geography` string
      - `languages` string[]
      - `alternatives` string[]
      - `trend_keywords` string[]
    - `positioning` object
      - `differentiation` string
      - `key_features` string[]
      - `category_stance` string
      - `why_switch` string
    - `competitors` object[]
      - `name` string, required
      - `url` string
      - `notes` string
      - `battlecard` string
    - `proof_assets` object[]
      - `label` string, required
      - `url` string, required
      - `category` string, required
      - `notes` string
    - `story` object
      - `origin` string
      - `mission` string
      - `founder_story` string
      - `beliefs` string[]
      - `notable_clients` object[]
        - `name` string, required
        - `can_name` boolean
      - `enemy` string
      - `why_now` string
    - `offer` object
      - `products` object[]
        - `name` string, required
        - `who_for` string
        - `description` string
        - `price_band` string
        - `guarantee` string
      - `promise` string
      - `sales_process` string
      - `qualification` object
        - `good_fit` string
        - `bad_fit` string
      - `cta_ladder` string[]
      - `pricing_disclosure` 'never' | 'range' | 'on_request'
    - `conversation` object
      - `objections` object[]
        - `objection` string, required
        - `response` string, required
      - `faq` object[]
        - `q` string, required
        - `a` string, required
      - `policy` object
        - `push_calendar_when` string
        - `never_discuss` string[]
        - `handoff_when` string
      - `qualification_questions` object[]
        - `question` string, required
        - `why` string, nullable
        - `required_before_booking` boolean, nullable
      - `prospect_types` object[]
        - `type` string, required
        - `how_to_handle` string, required
      - `escalation` object
        - `channel` string, nullable
        - `to` string, nullable
        - `when` string, nullable
    - `lexicon` object
      - `voice_description` string
      - `banned_words` string[]
      - `preferred_phrases` string[]
      - `product_spellings` string[]
      - `notes` string
      - `writing_rules` string[]
      - `signature` string
    - `style_exemplars` object[]
      - `text` string, required
      - `source` 'user' | 'linkedin_mined'
      - `post_url` string
      - `engagement` string
    - `case_studies` object[]
      - `client` string, required
      - `problem` string
      - `intervention` string
      - `result` string
      - `quote` string
      - `url` string
    - `people` object[]
      - `name` string, required
      - `role` string
      - `bio` string
      - `credentials` string[]: Bio credentials: degrees, certifications, former roles.
      - `linkedin_url` string
    - `guardrails` object
      - `compliance_notes` string
      - `forbidden_claims` string[]
      - `topics_to_avoid` string[]
      - `compliance_regimes` string[]
      - `require_human_review_for` string[]
    - `content_pillars` object[]
      - `name` string, required
      - `description` string
    - `updates` object[]
      - `item` string, required
      - `date` string
      - `relevance` string
    - `links` object
      - `calendar_url` string
      - `primary_cta_url` string
      - `resources` object[]
        - `url` string, required
        - `label` string
      - `newsletter_url` string
      - `community_url` string
      - `socials` object
        - `twitter` string
        - `youtube` string
        - `instagram` string
        - `tiktok` string
    - `tone_of_voice` 'Professional' | 'Conversational' | 'Authoritative' | 'Friendly' | 'Bold' | 'Playful' | 'Technical' | 'Inspirational' | 'Direct' | 'Empathetic'
    - `tagline` string, nullable
    - `category_name` string, nullable
    - `founded_year` integer, nullable
    - `headquarters` string, nullable
    - `headcount_band` '1-10' | '11-50' | '51-200' | '201-500' | '501-1000' | '1001+', nullable
    - `marketing_preferences` object, nullable
      - `aggressiveness` string, nullable
      - `dm_length` string, nullable
      - `cta_style` string, nullable
      - `personalization_depth` string, nullable
      - `emoji_policy` string, nullable
      - `hashtag_policy` string, nullable
      - `humor` string, nullable
      - `formality` string, nullable
      - `first_person` 'I' | 'we', nullable
      - `voice_owner` string, nullable
      - `use_lead_magnets` boolean, nullable
      - `never_do` string[], nullable
    - `content_prefs` object, nullable
      - `content_audience` string, nullable
      - `post_type_mix` object, nullable
        - `personal` integer, nullable
        - `lead_magnet` integer, nullable
        - `article` integer, nullable
        - `video` integer, nullable
        - `carousel` integer, nullable
      - `golden_posts` object[], nullable
        - `url` string, nullable
        - `post_id` string, nullable
        - `post_type` string, required
        - `why_it_works` string, nullable
        - `own` boolean, required
      - `cta_by_goal` object[], nullable
        - `goal` string, required
        - `cta` string, required
    - `exclusions` object, nullable
      - `domains` string[], nullable
      - `companies` string[], nullable
      - `titles` string[], nullable
      - `existing_customers_list_id` string, nullable
      - `partners` string[], nullable
  - `replace` string[]: Sections whose CURRENT value is replaced whole by the patch value. Only when the user explicitly asked to change or remove something. A list-section edit (one case study) means sending the whole edited list here.
  - `source` object: Where the facts came from: interview (the user said it, default), research (a URL you read), website, linkedin, doc. Recorded on the profile.
    - `kind` 'interview' | 'research' | 'website' | 'linkedin' | 'doc', required
    - `ref` string, required
  - `confirm_token` string: From the preview response. Re-send with the identical patch, replace and source to execute.

## Response `200`

The result of calling this tool.

- object
  - `data` unknown, required
  - `error` unknown, required

## Other responses

- `400`: The request body was not a JSON object (code invalid_request), or Idempotency-Key is malformed (code invalid_idempotency_key).
- `401`: Missing or invalid API key. Send `Authorization: Bearer rmcp_...` (code unauthorized).
- `403`: This tool is out of the key’s granted scope (code insufficient_scope).
- `409`: This Idempotency-Key has an unresolved in-flight or ambiguous result (code request_in_flight). Reconcile before using a new key.
- `422`: This Idempotency-Key was already used with a different request body (code idempotency_key_reuse).
- `429`: Rate limited: shared `mcp:ip:{ip}` (600/60s) or `mcp:key:{keyId}` (120/60s) bucket, the SAME buckets the MCP endpoint uses (code rate_limited).
- `500`: Unhandled server error (code internal_error).

## Changes

- **2026-10-20** `11682826692b`: 2 breaking, 1 warning, 32 info
  - added the new required request property `patch/story/notable_clients/items/name`
  - the `patch/story/notable_clients/items/` request property type changed from `string` to `object`
  - removed the request property `patch/story/key_numbers`
  - added the new optional request property `patch/category_name`
  - …31 more

[Operation history](https://skmtc.dev/reachium/apis/reachium-api/changes/api/v1/actions/updateBrandProfile/post.md)

---

[API](https://skmtc.dev/reachium/apis/reachium-api.md) · [All operations](https://skmtc.dev/reachium/apis/reachium-api/llms.txt) · [OpenAPI document](https://skmtc.dev/reachium/apis/reachium-api/revisions/11682826692b?raw)