# Work with brand memory Most reporting APIs can tell you *what* the numbers did. Brand memory is the part of the platform that knows *why*. It has two halves, and both are reachable with the same credential you already use for data: - **Brand context**: the durable profile of a brand. What it sells, how the account is structured, what counts as branded traffic, what normal looks like. - **The change log**: the running, attributed record of what actually happened to that brand. Launches, price tests, stockouts, promotions, strategy changes, and the advertising changes committed through MixShift. Your own tools can read both, and write to the change log. That is what lets an internal dashboard say "spend jumped because a promotional window opened on the 14th" instead of leaving a spike unexplained. ## Read brand context Two endpoints, both needing the `context:read` scope (included by default on new service credentials): - `GET /v1/context/docs` returns the manifest of every document held for a brand, with its type, revision, and content hash. Use the hash to skip re-fetching what you already have. - `GET /v1/context/doc` returns one document, selected by brand and type. Corpus documents also take a name. Brand context documents are **read-only on `/v1`**. Your team authors them through the MixShift plugin's brand setup, and your integration reads them. See [Set up a brand](/knowledge-base/plugin/how-to/set-up-a-brand) for how the content gets there. The one brand context change a builder makes is retiring or restoring a brand, described below. Documents cap at 1 MB each, and corpus files at 10 MB. ## Retire or restore a brand A brand your team no longer works on, such as a client that left, a duplicate, or a brand replaced by another, can be retired for everyone on the account and restored later. Retiring deletes nothing: the brand keeps its context documents, their revision history, and its change log, and reports and warehouse data are untouched. What changes is the brand's lifecycle state in the brand context listing. - **Change it** with `POST /api/context/lifecycle`, passing the brand's slug and `retire` or `restore`, plus an optional reason (`client_left`, `duplicate`, `superseded`, or `other`) and a short note. This write is not on `/v1`, and it needs `context:write` alongside `context:read`. On a service credential, `context:write` is opt-in, granted when it is minted; sign-ins already hold it: the plugin, a `/login?mode=direct` token, a Claude (claude.ai and Claude Desktop) connector, and MixShift added to ChatGPT as a custom app. Repeating the current state changes nothing, so a retry is safe. The change is recorded as the credential that made the call, never as a name in the request. - **Read it** from the `lifecycle` object every brand now carries in the brand context listing: `active` or `retired`, when that state began, who the change was recorded as, and where it came from. The listing also reports `retired_count`. - **Retired brands stay listed by default**, marked retired rather than dropped. `GET /api/context/manifest` and the `context_list_docs` MCP tool take `lifecycle=active` to leave them out. `GET /v1/context/docs` always lists every brand, so an integration that should skip retired brands filters on `lifecycle.state`. - **Each change lands on the change log** as a retired or restored event carrying its reason, note, and where it came from. The timeline endpoints cannot append either kind, so this route is the only way a brand's state changes. People on the MixShift plugin retire a brand by asking in chat; see [Set up a brand](/knowledge-base/plugin/how-to/set-up-a-brand). The full request and response contract is on [mcp.mixshift.io/developers](https://mcp.mixshift.io/developers#brand-lifecycle). ## Read the change log `GET /v1/timeline` needs `timeline:read` (also a default read scope). It returns the brand's events, and you can filter by brand, event family, kind, date window, and the stake facets described below. Results paginate with a cursor like the rest of `/v1`. One thing worth knowing: the change log also folds in a read-only summary of the advertising changes committed through MixShift, so a single read shows both what a human recorded and what the platform actually did to the account. ## Append to the change log `POST /v1/timeline/event` needs `timeline:write` **in addition to** `timeline:read`. On a service credential, write access is opt-in and granted when it is minted, never by default. An event carries a brand, a family, a kind, an optional timestamp and payload, and an idempotency key if you want safe retries. A few rules the service enforces so the log stays trustworthy: - **Attribution is not yours to set.** The service records which credential appended the event; anything you pass for author is ignored. - **Some kinds are reserved.** Events the platform writes itself (its own knowledge revisions, the advertising-change records, a brand being retired or restored) are rejected if a client tries to write them, so the log cannot be forged. - **Payloads cap at 32 KB.** Store the summary here and keep bulk artifacts in your own system. - **Dates are bounded.** You can backdate freely and forward-date a short way, or up to a year ahead for a scheduled stake such as a promotion you already have on the calendar. ## Record a stake A **stake** is the specific kind of event that says "this is a thing that changes how the numbers should be read." It carries a category (launch, promotional window, stockout, price test, media spike, brand migration, portfolio decision, content change, strategy change, off-Amazon media, assortment change, and a few more), a time window, and a required plain-language **interpretation**: your own sentence explaining what it means for the brand. The category list is deliberately not the whole vocabulary. Anything that does not fit takes the catch-all category with a short label naming what it actually is, and every stake can carry your own freeform tags, which you can then filter on when you read the change log back. Nothing has to be mis-filed to be recorded. Stakes can then be confirmed by someone else: `POST /v1/timeline/event/[id]/corroborate` marks a stake as corroborated (or disputed). Verification state is set by that endpoint only, never accepted when the event is created, so agreement has to be earned rather than asserted. This is the mechanism that turns an anomaly into an explanation. A spend spike sitting next to a corroborated promotional window is a story; the same spike alone is a support ticket. ## From AI tools The same capabilities exist as MCP tools, so an assistant can browse the change log and record events conversationally: `timeline_list`, `timeline_add_event`, `timeline_corroborate`, `context_list_docs`, `context_get_doc`, and `context_set_brand_lifecycle`, which retires or restores a brand with the same arguments and checks as the REST route. Each checks its own scope, so a read-only credential can browse but cannot append or retire. A Claude (claude.ai and Claude Desktop) connector and MixShift added to ChatGPT as a custom app hold the brand context and timeline scopes, reads and writes, as does a token from `mcp.mixshift.io/login?mode=direct` (the Cursor and Codex setup); a service credential holds the reads by default and needs the writes granted when it is minted. A connector or app added before September 27 keeps the access it was first set up with until it is added again, so until then these tools return an insufficient-scope result there. See [Connect AI tools over MCP](/knowledge-base/builder-platform/how-to/connect-ai-tools-over-mcp). ## Current limitation worth planning around Events carry a sensitivity marking, but reads are not filtered by it yet: today any credential with `timeline:read` sees every event on your tenant. Treat the change log as shared within your organization and keep anything you would not share out of event payloads. ## Related - [Use the /v1 data endpoints](/knowledge-base/builder-platform/how-to/use-the-v1-endpoints) - [Limits and guardrails](/knowledge-base/builder-platform/reference/limits-and-guardrails) - [Set up a brand](/knowledge-base/plugin/how-to/set-up-a-brand) (how brand context gets authored)