Developers

API catalogue

Naming standard

Pattern 1 api-{name}-{function} e.g. api-round-create

Pattern 2 · with a qualifier api-{name}-{function}-{qualifier} e.g. api-newsletter-generate-banter

Lower case, words joined by hyphens
name is one singular noun: round, player, newsletter…
function is a verb from the approved list
qualifier narrows it: banter, whatsapp, ar…
All calls are POST with a JSON body and a Bearer token

create get list update verify read merge run generate approve send share render push receive check upload

Example · M-Pesa prompt

POST /api-payment-push-stk
Authorization: Bearer $VF_TOKEN

{
  "phone": "2547XXXXXXXX",
  "pass": "day",
  "amount": 150,
  "newsletter_id": "nl_[id]"
}

→ 202 { "status": "prompt_sent",
        "checkout_id": "[id]" }

The result arrives on api-payment-receive-callback; the pass starts only after M-Pesa confirms.

Rounds & scorecards

api-round-create	Start a round: club, tees, date, format, sponsor	rounds:write
api-scorecard-upload	Upload a scorecard photo for a round	rounds:write
api-scorecard-read	Read hole scores from the photo, with confidence per cell	rounds:write
api-round-verify	Confirm scores; fails if any row does not add up	rounds:write
api-round-list-field	All players and scores in a tournament field	rounds:read

Players

api-player-create	Add a player, with phone for consent	players:write
api-player-get	One player file with stats	players:read
api-player-merge	Merge duplicates such as "Geofrei" and "Geofrey"	players:admin

Analysis

api-analysis-run	Analyse a round: nines, hole types, differential	analysis:run
api-analysis-get-holes	Five-hole spotlight: 3 best and 2 worst, ties grouped	analysis:read

api-newsletter-generate	Write the full player newsletter with the chosen writer	newsletter:draft
api-newsletter-generate-roundup	Only the 75-word round-up	newsletter:draft
api-newsletter-generate-review	Only the detailed card review	newsletter:draft
api-newsletter-generate-banter	Only Smart Boy's 19th-hole banter	newsletter:draft
api-newsletter-approve	Editor approval — staff only, never by token	editor
api-newsletter-send-whatsapp	Send the approved newsletter link to the player	newsletter:send
api-newsletter-share-link	Create a shareable link that sits behind the paywall	newsletter:send

Media & AR

api-video-upload	Upload a player's shot video	media:upload
api-tracer-render	Draw the ball-flight tracer on a video	media:render
api-tracer-render-ar	Tracer plus sponsor logo pinned to the fairway and name strip	media:render

Payments & access

api-payment-push-stk	Send an M-Pesa prompt for a day, week, month or single pass	payments:write
api-payment-receive-callback	M-Pesa confirmation; starts the pass	system
api-access-check	Can this reader open this newsletter?	access:read

Sponsors, weather & analytics