Contents

API reference / Playbooks

Create a playbook of your own

POST /api/v1/playbooks

create_playbook Write MCP tool

Copy a built-in or one of your own by passing from (its id), and change what you like; or give every field. Send only what differs from the playbook you copy: signal_weights, roles, windows and daily_brief_template merge key by key. A workspace keeps up to 12. Every value is checked and a wrong one is refused with the field named. The copy is not used until apply_playbook.

A full-access key (ss_sk_…), or an editor or owner signed in.

Request body

JSON, sent with Content-Type: application/json.

NameTypeDescription
from string The id of the playbook to copy (a built-in such as founders, or one of your own).
name string
1–60 characters
A name for the playbook.
persona string Which persona it belongs to (a copy keeps its original's).
One of: founders agencies product-marketers developer-relations gtm custom
subject_kind string What the subject is: own_brand, client_brands, target_accounts, portfolio or category. For every kind but target_accounts the subject is a project; target_accounts is the workspace's imported accounts (import_accounts), and get_brief reads the conversations found for them.
One of: own_brand client_brands target_accounts portfolio category
summary string
up to 300 characters
What 'ready' means for this playbook, in plain words.
signal_weights object How much each kind of post counts, 0 to 1 (0 = never ready): asking, comparing, switching, complaint, praise, bug_report, feature_request, question, news, promo, other. Send only what changes.
roles object How much a post counts by whom it is about, 0 to 1: subject, rival, category (the subject itself, one of its rivals, the category).
subject_only array of string Kinds of post that count only when the post is about the subject itself, not a rival or the category.
windows object How old a post may be, in days (1 to 14), per kind of post.
ready_threshold number
0–1
A post is ready when strength x its kind's weight x its role's weight reaches this.
answered string skip: leave out posts whose thread the brand already answered. keep: they count anyway.
One of: skip keep
authors string people: only posts by people. any: company accounts too. Bots and spam accounts are never ready.
One of: people any
group_by string none: one ranked list. project: one group per project (per client). topic: one group per rival or topic and kind of post, so what keeps coming up shows as a count.
One of: none project topic
min_group integer
1–20
A group is listed from this many ready posts (2 shows only what recurs).
per_group integer
1–10
Quotes shown per group.
one_per_author boolean
size integer
1–50
How many items (or groups) the brief shows.
daily_brief_template object The brief's wording: title, cadence (daily or weekly), intro and empty. The intro and empty lines may use {ready}, {considered}, {groups}, {days}, {name}.
next_actions array of string What a person can do on a ready post: check_thread, draft_reply, mark_done, follow_up, not_relevant, quote_export, send_to_slack, github_issue, outreach_draft, enroll_outbound. One that needs a connection (github, engine) stays out of the brief until the workspace has it (get_action_settings).
handoffs array of string Where the list can be carried on: email_digest, slack_alert, webhook, client_report, client_routing, report_export, answer_list, send_brief, viral_alert, insights, rival_card, github, outbound_engine.

Returns

{ data: Playbook }

Example

curl -X POST "https://sniffington.com/api/v1/playbooks" \
  -H "Authorization: Bearer $SCOUT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"from":"…","name":"Acme"}'