One Cue Golf measurement API

Controlled integration contract for authorized testing with synthetic measurements. Consumer coaching is not available. Muse integration remains under review.

Analyze a shot group

Send POST /api/v1/analyze to https://api.onecuegolf.com with these headers:

Authorization: Bearer <integration-key>
Content-Type: application/json
A descriptive User-Agent, such as YourIntegration/1.0

Use only the dedicated integration credential. Never send an instructor session, shared write secret, or key in a URL. The first integration supports one server-to-server key. It does not authenticate individual golfers or provide access to saved records.

The complete machine-readable contract is openapi.json. A synthetic request and its response demonstrate the supported shape. There are no query parameters, media uploads or AI opt-in fields.

{
  "handedness": "right",
  "intendedShape": "straight",
  "shots": [{ "club": "7 iron", "faceAngle": 4, "clubPath": 0 }]
}

Supply 1–200 shots from one club. Every shot needs a club identifier containing 1–40 letters, numbers, spaces, underscores or hyphens, starting with a letter or number. Club identifiers are trimmed before comparison. intendedShape is required and is straight, draw, fade or unspecified. Only explicitly right-handed measurements are supported.

All measurements are optional. Omitted values and JSON null mean unmeasured, never zero. Unknown request/shot fields are rejected. Do not include names, player identifiers, lesson/session identifiers, notes or media URLs.

Field	Unit and convention	Accepted range
faceAngle	Degrees relative to target, positive right	−90 to 90
clubPath	Degrees relative to target, positive right	−90 to 90
faceToPath	Degrees, faceAngle minus clubPath, positive open to path	−180 to 180
swingDirection	Degrees relative to target, positive right	−90 to 90
attackAngle	Degrees, negative downward	−90 to 90
lowPointInches	Inches, positive beyond the ball toward target	−100 to 100
smashFactor	Ball speed divided by club speed	0 to 2

Face-to-path is derived only if both source measurements exist and faceToPath is absent/null. The response labels derived evidence separately. If all three values are supplied, a discrepancy greater than 0.5 degrees is rejected. Bounds are input safeguards, not recommended swing targets.

Read the result

The deterministic result gives the measured pattern, sample count, evidence summaries, missing measurements, prerequisite checks and exactly one next action. That action may ask for more evidence. A matching intended draw or fade is not automatically a fault. Unmeasured fundamentals remain unobserved. One shot cannot establish consistency, and these measurements do not establish body motion or strike location.

The ai result is experimental and separate from deterministic. Every valid request attempts one Jev 1.13.0 classification when the provider key is configured. Jev receives the intended shape, numeric thresholds and normalized per-shot numeric measurements. Arbitrary club text is excluded. Jev does not write lesson prose or change the deterministic next action.

ai.status is ready when Jev selects the deterministic priority, review_required with different_priority when it selects another supported category, or insufficient_evidence when it cannot establish one pattern. An unavailable provider returns unavailable with not_configured or provider_error. Evaluation results include the judgment, model probabilities, confidence, token usage and elapsed time. Confidence is a model output, not measured golf accuracy. Jev rounds its probabilities, so their displayed total can differ slightly from one. The API preserves those values.

There is at most one TypeSafe call and no retry. The provider deadline is eight seconds. Serialized provider requests are limited to 60,000 bytes and provider responses to 32,768 bytes. Provider failure never removes or replaces the deterministic result.

For comparison requests, analyze each intentionally supplied group separately. Preserve the club, intention, sample counts and missing evidence for each group. Never imply that a difference establishes a cause or improved consistency from one shot.

Limits and errors

The first integration shares a service-wide allowance of 30 admitted authenticated POST attempts per fixed minute and 500 per UTC day. These limits persist across object restarts and key rotation. All admitted authenticated POST attempts count, including invalid input. Invalid keys do not consume this allowance. Platform protections may reject traffic before the handler and are separate from these application limits.

Errors use { "error": { "code": "...", "message": "..." } } without echoing submitted data or internal exceptions.

Cloudflare can reject traffic or close a connection before a handler response reaches the caller. In September 20, 2026 HTTP/1.1 tests, incomplete uploads disconnected after about 15 seconds without an HTTP response, including unauthenticated requests. This is not a verified live 408 response. The same authenticated stalled upload returned 408 JSON after ten seconds through the local Workers runtime. The default Python-urllib User-Agent received a Cloudflare 403; a descriptive integration User-Agent reached the handler. Clients must handle transport failures and non-JSON edge errors separately from the handler errors below. Do not assume that a failed connection means no quota allowance was consumed.

Status	Code	Action
400	invalid_query	Remove query parameters.
400	invalid_json	Send valid UTF-8 JSON.
400	invalid_measurements	Check the documented fields, units and cross-field rules.
401	unauthorized	Supply the currently authorized integration key.
404	not_found	Use the documented path.
405	method_not_allowed	Use POST. The Allow header is POST.
408	request_timeout	Send the complete body within ten seconds.
413	payload_too_large	Reduce the body to 65,536 bytes and supply a valid Content-Length if present.
415	unsupported_media_type	Use application/json and identity encoding.
429	rate_limited	Wait the positive number of seconds in Retry-After.
500	internal_error	Report the failure without sending private data.
503	unavailable	Retry later. No unverified quota allowance is granted.

Order matters: route, configuration, method, authentication, quota, query, media/encoding, size/body timeout, JSON, then measurements. An exhausted allowance therefore returns 429 before reporting bad input. A timed-out quota request may consume one allowance if its storage transaction completes later, but it never produces analysis without verified admission.

Data handling and deployment prerequisites

The handler does not persist measurements, keys, prompts or outputs. It never reads the bay or lesson database. One privately bound Durable Object holds a single four-number counter record. No request data or key digest enters that object. Application code does not log request content. TypeSafe receives normalized numeric measurements, intended shape, thresholds and static category definitions. It does not receive arbitrary club text, names, player or lesson identifiers, media, the caller's integration credential or raw HTTP headers. The Worker authenticates to TypeSafe with its own server-side provider credential.

Cloudflare processes network and security metadata. Worker logs and traces are disabled, and the verified account and zone have no Logpush export jobs. Operational metrics remain available. PostHog receives only API status, fixed error codes, timing, Jev availability or disagreement, model version and token counts. It receives no shot measurements, model judgments, golfer identities or credentials. TypeSafe states that customer data is not used to train its models. Its data-processing terms allow retention for as long as necessary to provide the service or meet legal obligations. One Cue Golf does not assume enterprise zero-data-retention terms. Read the privacy notice for provider handling and retention. These settings do not mean zero provider telemetry.

Revocation removes or replaces the deployed SHA-256 verifier. It takes effect after active deployment propagation, and previously admitted requests may finish. Alternative preview URLs and workers.dev access must remain disabled. Test the old key against the active route after rotation.

Alex's evaluation and verified Muse credential handling remain prerequisites for consumer access. This document is not approval to expose consumer coaching or accept platform terms.