Recommend the next action for an opportunity

Recommend the next action for an opportunity

Required scopes: opportunities:read, tasks:read

Computes a recommendation envelope from the application's current status and any open user_tasks rows. Returns { recommended_action_key, target_status, rationale, requires_approval, can_complete_via_api, cannot_complete_reason }. When the application is in a terminal status (Hired, Withdrawn, Offer Rejected, Disqualified), all action fields are null and cannot_complete_reason is TASK_TERMINAL. Other cannot_complete_reason values are NO_REGISTRY_ACTION and OWNED_BY_LATER_API_CHILD (see docs/api/tasks-api.md). Requires both opportunities:read and tasks:read because the recommendation reads from user_tasks on the application's behalf.

Example (curl):

curl https://api.yardstick.team/v1/opportunities/opp_def456/actions/next_action \
  -H 'Authorization: Bearer ys_sk_live_…'

Example (TypeScript):

await fetch(
  "https://api.yardstick.team/v1/opportunities/opp_def456/actions/next_action",
  { headers: { Authorization: `Bearer ${process.env.YS_API_KEY}` } },
).then((r) => r.json());