Boring Marketingdocs

Report Outcome Event

Record an outcome event for the learning loop — accepted, rejected, completed, or observed at 7/30/90 days.

POSThttps://api.boringmarketing.com/track/outcomes/report

Records a single outcome event for a recommendation. This is the write side of the learning loop — the read side is GET /brands/{brand_id}/outcomes.

Events are persisted as artifacts and feed the leverage scoring calibration over time. Supported lifecycle: accepted → completed → observed_7d → observed_30d → observed_90d, plus rejected for queue items you declined.

This endpoint is feature-flagged. Returns 503 if OE_OUTCOME_LINKAGE_ENABLED is not set in the environment.

Request body

brand_idstringrequired

The brand UUID.

event_typestringrequired

One of: accepted, rejected, completed, observed_7d, observed_30d, observed_90d.

recommendation_idstring

The opportunity UUID that this event relates to. Strongly recommended for any event other than generic brand-level logs.

brief_idstring

The brief UUID, if this event relates to a generated brief.

rejection_reasonstring

Required when event_type is rejected. Free-text reason.

metricsobject

Arbitrary metrics captured with the event. Useful on observed_* events to store rank/citation deltas from GET /track/brands/{id}/changes. As of PR #112, the metrics object is persisted into the outcome event's delta field — no longer silently dropped — so anything you store here will round-trip on read.

notesstring

Free-text notes (e.g. published URL, author, internal reference).

Response

{
  "outcome_event_id": "outcome-uuid",
  "artifact_id": "artifact-uuid",
  "status": "recorded"
}

Example — publish event

curl -X POST \
  -H "X-API-Key: $BM_API_KEY" \
  -H "Content-Type: application/json" \
  https://api.boringmarketing.com/track/outcomes/report \
  -d '{
    "brand_id": "'$BRAND_ID'",
    "recommendation_id": "opp-uuid",
    "brief_id": "brief-uuid",
    "event_type": "completed",
    "notes": "Published at https://yourdomain.com/article"
  }'

Example — 7-day observation with deltas

curl -X POST \
  -H "X-API-Key: $BM_API_KEY" \
  -H "Content-Type: application/json" \
  https://api.boringmarketing.com/track/outcomes/report \
  -d '{
    "brand_id": "'$BRAND_ID'",
    "recommendation_id": "opp-uuid",
    "event_type": "observed_7d",
    "metrics": {
      "rank_delta": 8,
      "citation_delta": 2,
      "from_snapshot": "snap-1",
      "to_snapshot": "snap-2"
    }
  }'

For consistency, pair every completed event with an immediate POST /track/brands/{id}/snapshot so later diffs have a clean baseline. See the Tracking Outcomes guide for the full pattern.