Brain Food

Push something your own system knows about — this week's specials, a sale, a new location — and DW's agents pick it up: a pinned, dated post goes into Hype's queue ahead of whatever was already planned, and the same material becomes something Quill and Press may draw on too, if it genuinely fits what they're already writing.

This exists because DW can't see what changes in YOUR system. A rotating specials roster, a timetable, a clearance list — none of that lives here, so none of it can be detected. It has to be pushed.

Why a push, not a pull #

DW never polls your site or scrapes a page to build this. Two reasons:

1. We'd get it wrong the moment your page changes. A scraper reading prices off markup breaks silently on the first redesign and posts a wrong number with total confidence.
2. You already computed the answer. If your system has a "this week's roster" view, that view is the one true source — sending it here is one call, not a second implementation of your own business logic.

Endpoint #

POST https://api.discoverworthy.com/graphql

Standard GraphQL over HTTP — same endpoint as the rest of the DiscoverWorthy public API. Content-Type: application/json, body { "query": "...", "variables": {...} }.

Authentication #

Your site's secret key (dwsk_…), the same one every write mutation on this API uses. Get one via the Rigg MCP tool dw_get_or_create_business_api_key (mints if absent, returns the existing key otherwise), or in the developer portal at https://api.discoverworthy.com → your site → Generate. It is a server-side credential — never put it in a browser or a mobile app.

curl -H "Authorization: Bearer dwsk_..." -H "Content-Type: application/json" \
  https://api.discoverworthy.com/graphql -d '{"query": "..."}'

1. See what you can push #

query {
  site {
    brainFoodBlocks {
      id
      label
      description
      listShaped
      mergeFields { key label required type example }
    }
  }
}

This is the SAME catalog pushBrainFood validates against — it will never list something the mutation then refuses, and it will never accept a field this query didn't mention.

2. Push something #

mutation Push($input: BrainFoodInput!) {
  pushBrainFood(input: $input) {
    ok
    error
    occasionId
    created
    itemsAccepted
  }
}

Identity — read this before your first push. externalSource is who you are ("your-system-name"); externalId is YOUR id for this specific push, not ours. Push the same externalId again to correct something (the payload updates in place, no second post is made). Push a new externalId for a new thing — next week's roster, a different sale. That is the whole retry story: if a request times out, resend it with the same id and you get the same occasion back, not a duplicate.

{
  "input": {
    "type": "sale_promotion",
    "externalSource": "my-system",
    "externalId": "eofy-2026",
    "validUntil": "2026-06-30",
    "landingUrl": "https://example.com/sale",
    "facts": { "offer": "20% off storewide", "endDate": "2026-06-30" }
  }
}

validUntil matters for anything time-bound: past this date the material may not seed a new post, and a post already scheduled from it will not publish — the queue never ships something you've since taken down.

landingUrl is where the post should send people, in a comment under the post (never guessed — DW doesn't invent per-product URLs; state the page you want).

3. A list-shaped push #

roster carries a list of items, not just fields. Each item can carry a price, a "was" price, and a badge — all drawn straight onto the slides. Nothing here is ever restated in words by a model: a wrong figure would be a rendering bug, not a prompt problem, which is the whole point of drawing it instead of writing it.

{
  "input": {
    "type": "roster",
    "externalSource": "my-system",
    "externalId": "homepage-roster-2026-W35",
    "validUntil": "2026-08-31",
    "landingUrl": "https://example.com/specials",
    "facts": { "title": "This week's specials" },
    "items": [
      {
        "sku": "ABC-123",
        "name": "Cordless drill 18V",
        "imageUrl": "https://example.com/img/drill.jpg",
        "badgeLabel": "SPECIAL",
        "priceCents": 12900,
        "wasPriceCents": 18900,
        "currency": "AUD"
      }
    ]
  }
}

The block library #

Generated from the live catalog — every type listed here is pushable today.

business_birthday — Business birthday #

Mark another year in business on your founding date.

were_hiring — We're hiring #

Announce an open role.

review_received — Review received #

Share a great review or testimonial.

customer_count_milestone — Customer milestone #

Celebrate a round-number customer count.

award_won — Award won #

Announce an award win or finalist spot.

supplier_spotlight — Brand spotlight #

Feature one of the brands you stock, install or work with.

press_mention — Press mention #

Share a feature or mention in the press.

partnership — Partnership announcement #

Announce a new partnership or supplier relationship.

nth_order_milestone — Order / volume milestone #

Celebrate your Nth order, project, or delivery.

product_launch — Product / service launch #

Announce something new on the shelf.

back_in_stock — Back in stock #

A popular product is available again.

sale_promotion — Sale / promotion #

Announce a sale — launch post plus a last-chance reminder.

new_location — New location / move #

Announce a move, new premises, or reopening.

holiday_hours — Holiday trading hours #

Tell customers your hours over a holiday period.

new_equipment — New equipment / capability #

Show off a new truck, machine, or capability.

public_holiday — Public holiday / industry day #

Mark holidays and industry days that fit your business.

commercial_moment — Trading moment #

Ride the buying peaks — Father's Day, Black Friday, EOFY, Christmas cut-offs.

year_in_review — Year in review / EOFY #

A look back at the year — calendar or financial.

event — Event #

An event you're hosting, attending, or speaking at — announce, remind, recap.

community_event — What’s on #

Events you publish on your own website — announced, then reminded about the day before.

sponsorship — Sponsorship / community #

Community involvement, sponsorships, and charity support.

roster — Roster #

A short list of things to put in front of people this week — specials, new arrivals, what’s on.

List-shaped — send items, not just facts. See "A list-shaped push" below.

What you will never be able to push #

Types that name a real person or a client are excluded outright, always — not a setting, not a scope you can request. They're gated on a consent bit held against that person, which an outside system has no standing to assert on their behalf. brainFoodBlocks will simply never list them.

Result shape #

{
  "ok": true,
  "occasionId": "3f9c...",
  "created": true,
  "knowledgeItemId": "9a1b...",
  "itemsAccepted": 8
}

A rejected push comes back { "ok": false, "error": "..." } rather than a GraphQL error — an integration finding out which field was wrong is worth more than a stack trace. knowledgeItemId is set when the material was also shared with Quill and Press; it can be null even on a successful push (that share is fail-open — your post still goes out if it fails).

Full schema: point any GraphQL client (or an LLM) at https://api.discoverworthy.com/graphql — it is fully introspectable. This doc: https://app.discoverworthy.com/docs/api/brain-food · https://app.discoverworthy.com/docs/api/brain-food.md.