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 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. The full request and response contract is on mcp.mixshift.io/developers.

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.

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.

Use the /v1 data endpoints
Limits and guardrails
Set up a brand (how brand context gets authored)