Skip to main content

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.

Context is read-only on /v1. Documents are authored through the MixShift plugin's brand setup rather than over the partner API, so your integration consumes the brand profile, it does not maintain it. See Set up a brand for how the content gets there.

Documents cap at 1 MB each, and corpus files at 10 MB.

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. Write access is opt-in and granted when the credential 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 derives itself (its own knowledge revisions, the advertising-change records) 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, and a few more), a time window, and a required plain-language interpretation: your own sentence explaining what it means for the brand.

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, and context_get_doc. Each checks its own scope, so a read-only credential can browse but cannot append. 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.

Still have questions?
Ask Shifty

Shifty is the MixShift docs assistant. Pick a question or open the chat for anything else.

Back to Knowledge Base