AI Coach

AI Search Coach is normally driven from the dashboard, but the same primitives are available over the API. Useful if you want to embed the recommendations in your own admin UI or trigger analyses from a job runner.

# Endpoints

# Run an analysis

POST /v1/indexes/{name}/coach/analyze

Body:

{ "days": 7 }

Synchronously runs the analysis (typically 5–15 seconds) and returns the recommendations it created. Each call counts against your plan's monthly AI Coach quota.

Response:

{
  "data": {
    "period_start": "2026-05-16T00:00:00Z",
    "period_end":   "2026-05-23T00:00:00Z",
    "events_analyzed": 1247,
    "recommendations_saved": 14
  }
}

# List pending recommendations

GET /v1/indexes/{name}/coach/recommendations

{
  "data": [
    {
      "id": 91,
      "type": "missing_synonym",
      "title": "\"placute frana\" → \"pastile frana\"",
      "description": "47 searches in the last week...",
      "confidence": "high",
      "search_count": 47,
      "status": "pending",
      "payload": { "user_term": "placute frana", "your_term": "pastile frana", "kind": "multi_way" }
    }
  ]
}

Recommendation types: missing_synonym, catalog_gap, ranking_opportunity, top_performer.

# Apply a recommendation

POST /v1/coach/recommendations/{id}/apply

Applies the change (creates the Synonym or Ranking Rule, pushes the synonym set to the engine) and marks the recommendation as applied.

# Dismiss

POST /v1/coach/recommendations/{id}/dismiss

Marks as dismissed and prevents the same term from being re-suggested for 30 days.

# Errors