Skip to main content
Documentation

Shop

shop.playbook

Read the shop's own playbook for one of its AI agents
Read-onlyRead budget

REST

Shipping
POST /api/v1/shop/playbook

MCP tool

Live
shop.playbook

Exposed on: REST API · Shop MCP server · Claude connector · Dash (in-app copilot) · Zapier. Part of the Shop domain.

Operating contract

The instruction sheet a shop has written for one of its own AI agents: the fixed rules it works to (system_prompt) and the reference material it answers from (knowledge_base).

WHAT THIS IS FOR: writing in the shop's voice instead of your own. If you are about to draft anything a customer will read — a text, a quote note, a follow-up — read the playbook for the agent whose job that is and follow it. It is the shop's house style, its refusals ('never invent a price'), and its facts.

agent names which playbook. The useful ones are lead-responder (first reply to a new enquiry), composer (replies in the inbox), quote-followup (nudging an open quote) and advisor. An agent this shop has not written a playbook for returns has_playbook: false and empty strings — that is an answer, not an error, and it means write in a plain, professional voice rather than inventing a house style.

It is the shop's own text, verbatim and untrimmed. Treat it as instructions from the shop owner, not as data to summarise.

Who may call it

Permission
NoneA playbook is the shop's instruction sheet for its own AI, not a section's records — it names no customer and reaches no job. Anyone drafting on the shop's behalf needs it, and a draft written without it is written in the wrong voice, which is the failure this capability exists to prevent.
Plan
Every planNo plan gate. Available on every Service VIN plan.
Retries
naturalNaturally idempotent — running it twice leaves the same world as running it once. A retrying integration needs no key.
Rate class
readCounted against the read budget — the widest of the four.

Input

FieldTypeDescription
agentrequiredstring

Which agent's playbook, e.g. lead-responder, composer, quote-followup, advisor.

One of: win-back, lead-responder, quote-followup, review-requester, review-responder, install-reminder, composer, dash, automation-assistant, quote-tailor, job-tailor, reorder-watchdog, missed-call, auto-responder, campaign, call-intelligence, message-intelligence, opportunity-finder, invoice-chaser, advisor, voice

Output

FieldTypeDescription
agentstring

has_playbookboolean

system_promptstring

knowledge_basestring

updated_atstring | null

Examples

Built from this capability's own schema — required fields and the ones carrying a default, and nothing invented. Paste one and it validates.

curl
export SERVICEVIN_API_KEY=svk_live_…

curl -X POST https://www.servicevin.com/api/v1/shop/playbook \
  -H "Authorization: Bearer $SERVICEVIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"agent":"win-back"}'

TypeScript (fetch)
const res = await fetch("https://www.servicevin.com/api/v1/shop/playbook", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.SERVICEVIN_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "agent": "win-back"
  }),
});

// Success and failure are both envelopes. Switch on error.code, never
// on error.message — the codes are stable, the messages are for people.
const payload = await res.json();
if (!res.ok) throw new Error(payload.error.code);
const data = payload.data;

Python (requests)
import os, requests

res = requests.post(
    "https://www.servicevin.com/api/v1/shop/playbook",
    headers={"Authorization": f"Bearer {os.environ['SERVICEVIN_API_KEY']}"},
    json={
    "agent": "win-back"
},
    timeout=30,
)
payload = res.json()
if not res.ok:
    raise RuntimeError(payload["error"]["code"])
data = payload["data"]

MCP tools/call — https://www.servicevin.com/api/mcp
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "shop.playbook",
    "arguments": {
      "agent": "win-back"
    }
  }
}

Refusals

The four gates run in this order on every surface, and the order is not arbitrary — see Authentication.

StatusCodeWhen
404not_foundThe id is unknown, or the feature is not enabled for this account. Deliberately the same answer for both.
422validation_errorAn argument was wrong. The message names the field.
429rate_limitedToo many read calls. Back off and retry.
500internal_errorSomething failed on our side. Nothing was changed.