Skip to main content
Playbook instructions are the versioned guidance for your storefront — a Markdown body the Merchandising Agent consumes when it composes products for buyers. Each save creates a new immutable version; exactly one version is active at a time, and only the active version influences compositions. You author a new version, review it, then activate it to swap the storefront’s active pointer.

​
What belongs here

Use operating instructions for product packaging, naming, selection, and explanation. Each related fact has one writable home: New versions that repeat facts owned by another field are rejected. Older immutable versions remain readable and return ownershipIssues when a conflict is detected. A flagged older version cannot be reactivated; create a cleaned-up version instead. If a flagged version is already active, the conflicting lines are omitted from the Merchandising Agent’s runtime copy while the immutable saved version remains visible for cleanup. Structured Playbook pricing, Buyer Discounts, Buyer Instructions, Media Kit, and Business Rules remain authoritative. Versions are numbered per storefront. The first version is 1, and numbers are monotone and never reused. Activating a version does not delete older ones — they stay in history so you can re-read or re-activate a prior version. All examples use the storefront base URL:
Authenticate every request with Authorization: Bearer $SCOPE3_API_KEY.

​
Buyers do not see your rules

Your operating instructions are confidential to you. They steer how the Merchandising Agent composes, but they are never sent to a buyer or a buyer’s agent, and everything the agent does send a buyer is written in market terms rather than by quoting your rulebook. That splits the explanation of why a proposal looks the way it does into two audiences: So a rule that keeps video out of a proposal reaches the buyer as “video is not part of this proposal”, never as your rule text. The same separation covers component and product ids, signal-vendor names, and setup vocabulary: they are yours, and they stay on your side of the conversation.

​
Telling buyers why a brief was declined

When a brief matches none of your inventory, whether the buyer hears why is your call — it is a negotiation decision, not a platform default. “Your budget is below what we can sell this inventory for” invites a better bid; sometimes you want that, sometimes you would rather say nothing. By default your storefront says nothing: the buyer is told that no products matched and how to broaden the brief. Authorize a fuller answer by writing the rule here, in your own terms — for example:
Your Merchandising Agent then writes the decline in your voice, within what you authorized. Three limits are mechanical: a decline that quotes your rulebook, names a component or signal id, or runs long is replaced with the neutral answer, and the attempt is flagged to us. Beyond those, the agent is instructed to keep signal sources and setup vocabulary out of anything a buyer reads. Say nothing about what buyers should hear and nothing is disclosed. To see which of the two a buyer would get, run the brief through Murph — a brief test reports the decline the buyer would receive, the candid internal reason, and whether the wording came from your rules or the neutral fallback.

​
Task reference

List versions

GET /operating-instructions — every version, newest first

Create version

POST /operating-instructions — author a new version

Get active version

GET /operating-instructions/active — the version in force now

Get a version

GET /operating-instructions/{version} — one version by number

Activate version

POST /operating-instructions/{version}/activate — swap the active pointer