Goals
Endpoints
Every goal route at a glance, grouped by what it does.
All routes require Authorization and X-Workspace-Id headers.
Lifecycle
| Method | Path | Purpose |
|---|---|---|
| POST | /v1/goals | Create a goal |
| GET | /v1/goals | List goals |
| GET | /v1/goals/{goal_id} | Inspect one goal |
| PATCH | /v1/goals/{goal_id} | Edit a goal |
| DELETE | /v1/goals/{goal_id} | Delete a goal |
| GET | /v1/goals/profile-preview | Preview the profile before creating |
| GET | /v1/goals/price | Price a goal before creating |
| GET | /v1/goals/similar | Find similar signals & events |
| POST | /v1/goals/{goal_id}/publish-segment | Publish the goal's segment |
Runs
| Method | Path | Purpose |
|---|---|---|
| POST | /v1/goals/{goal_id}/run | Re-run discovery |
| GET | /v1/goals/runs/{run_id} | Inspect a run (stages & funnel) |
| POST | /v1/goals/{goal_id}/train | Start a tournament |
| POST | /v1/goals/{goal_id}/serve | Produce a forecast now |
| GET | /v1/goals/{goal_id}/timeline | The audit timeline |
| GET | /v1/goals/{goal_id}/activity | The activity feed |
Tournament
| Method | Path | Purpose |
|---|---|---|
| GET | /v1/goals/{goal_id}/tournament | Read the leaderboard |
| POST | /v1/goals/{goal_id}/tournament/champion | Select a champion manually |
| POST | /v1/goals/{goal_id}/tournament/cancel | Cancel the tournament |
| POST | /v1/goals/{goal_id}/tournament/entries/{preset_id}/cancel | Cancel one entry |
| POST | /v1/goals/{goal_id}/tournament/training/cancel | Cancel the champion's training |
| GET | /v1/goals/model-lineup | The model lineup (candidate catalog) |
Forecast
| Method | Path | Purpose |
|---|---|---|
| GET | /v1/goals/{goal_id}/forecast | Get the forecast & track record |
| POST | /v1/goals/{goal_id}/forecast/rerun | Force a fresh forecast |
| GET | /v1/goals/{goal_id}/drivers-now | Drivers now — current pressure |
| GET | /v1/goals/{goal_id}/shock-analogues | Shock analogues |
Graph
| Method | Path | Purpose |
|---|---|---|
| GET | /v1/goals/{goal_id}/graph | The relationship graph |
| GET | /v1/goals/{goal_id}/paths | Multi-hop paths |
| GET | /v1/goals/edges/{edge_id} | Edge detail (full evidence) |
Scenarios
| Method | Path | Purpose |
|---|---|---|
| POST | /v1/goals/{goal_id}/scenarios | Run a scenario |
| GET | /v1/goals/{goal_id}/scenarios | List saved scenarios |
| POST | /v1/goals/{goal_id}/scenarios/parse | Parse natural language into a spec |
| POST | /v1/goals/{goal_id}/scenarios/{scenario_id}/explain | Explain a scenario |
| POST | /v1/goals/{goal_id}/scenarios/sensitivity | Run sensitivity analysis |
| GET | /v1/goals/{goal_id}/scenarios/sensitivity | Latest sensitivity result |
| DELETE | /v1/goals/scenarios/{scenario_id} | Delete a scenario |
Analyst
| Method | Path | Purpose |
|---|---|---|
| POST | /v1/goals/{goal_id}/analyst/stream | Ask a question (streamed) |
| GET | /v1/goals/{goal_id}/analyst/sessions | List sessions |
| GET | /v1/goals/{goal_id}/analyst/sessions/{session_id} | Get one session |
| DELETE | /v1/goals/{goal_id}/analyst/sessions/{session_id} | Delete a session |
Fleet
Fleet goals are created through the same POST /v1/goals with
goal_kind: "fleet" — see Fleet goals.
| Method | Path | Purpose |
|---|---|---|
| GET | /v1/goals/fleet/preview | Preview membership & cost before creating |
| GET | /v1/goals/{goal_id}/fleet/leaderboard | The ranked board for a run |
| GET | /v1/goals/{goal_id}/fleet/member | One member's history (?key=) |
| GET | /v1/goals/{goal_id}/fleet/runs | List scoring runs |
| POST | /v1/goals/{goal_id}/fleet/run | Score the fleet now |
| GET | /v1/goals/{goal_id}/fleet/bakeoff | The model bake-off result |
| GET | /v1/goals/{goal_id}/fleet/receipts | Receipts — verified outcomes |
| GET | /v1/goals/{goal_id}/fleet/drivers | Companion goal & shared covariates |
| POST | /v1/goals/{goal_id}/fleet/scenarios | Shock a driver, re-rank |
| GET | /v1/goals/{goal_id}/fleet/scenarios | List fleet scenarios |
| GET | /v1/goals/{goal_id}/fleet/scenarios/{scenario_id} | One scenario's result |
Alerts
| Method | Path | Purpose |
|---|---|---|
| GET | /v1/goals/{goal_id}/alerts | List alerts |
| POST | /v1/goals/{goal_id}/alerts | Create an alert |
| PUT | /v1/goals/{goal_id}/alerts/{alert_id} | Update an alert |
| DELETE | /v1/goals/{goal_id}/alerts/{alert_id} | Delete an alert |
| POST | /v1/goals/{goal_id}/alerts/preview | Preview a condition |