---
title: "Get guide recommendations for an issue"
method: POST
path: "/ai/recommendGuides"
tags: ["ai"]
---

# Get guide recommendations for an issue

`POST /ai/recommendGuides`

## Request

- Base URL: `https://public.stonly.com/api/v3`
- URL: `https://public.stonly.com/api/v3/ai/recommendGuides`
- Auth: HTTP basic

Analyzes an issue/subproblem and returns recommended guides with relevance scores. Uses the AI Agent recommendation pipeline including query expansion, semantic search, keyword search, re-ranking, and a minimum relevance score per guide.

## Request body

- GuideRecommendationRequest
  - `issues` GuideRecommendationInput, required: Input structure matching TicketProblemsAndFacts from v1 AI Agent Assist
    - `raisedIssues` RaisedIssue[], required: List of issues/subproblems to find recommendations for
      - `issue` string, required: The issue/subproblem text
      - `resolved` boolean: Whether the issue has been resolved
      - `resolutionSummary` string: Summary of how the issue was resolved (if resolved)
    - `priorUserActions` string[]: Steps the user has already taken
    - `errorMessages` string[]: Error messages encountered
    - `technicalDetails` string[]: Technical details relevant to the issues
  - `kbId` integer, required: Knowledge Base ID to search within
  - `tagFilter` string[]: Tag IDs to filter search results. Only applied if searchFiltersEnabled is true in AI agent configuration.
  - `includeDebug` boolean: Include timing and query debug information in the response

## Response `200`

Successful guide recommendation response

- GuideRecommendationResult
  - `results` GuideRecommendationResultItem[], required: Recommendation results for each issue
    - `issue` string, required: The issue text
    - `guides` RecommendedGuide[], required: Recommended guides from a single Assist Agent hybrid search that scored at or above the minimum relevance score. Empty when verdict is false
      - `guideId` string: Unique guide identifier
      - `guideType` 'GUIDE' | 'ARTICLE' | 'CHECKLIST': Type of the guide
      - `stepId` integer: ID of the most relevant step
      - `stepTitle` string: Title of the most relevant step
      - `title` string: Title of the guide
      - `type` 'keyword' | 'semantic': Search type that found this guide
      - `content` string: Relevant content snippet from the guide
      - `score` number, float: Relevance score used for ranking. Uses the Voyage reranker score when reranking succeeds; otherwise, uses the fused search score. Higher values indicate greater relevance.
    - `verdict` boolean, required: Whether at least one guide for the issue scored at or above the minimum relevance score
    - `explanation` string, required: Explanation of the verdict
  - `debug` GuideRecommendationDebug
    - `queryExpansionTime` integer: Time in milliseconds for query expansion
    - `searchTime` integer: Time in milliseconds for the searches of all issues
    - `issueCount` integer: Number of issues processed after query expansion

## Other responses

- `404`: Knowledge base not found or AI configuration not found
- `default`: Standard error response.

---

[API](https://skmtc.dev/stonly/apis/stonly-public-api.md) - [All operations](https://skmtc.dev/stonly/apis/stonly-public-api/llms.txt) - [OpenAPI document](https://skmtc.dev/stonly/apis/stonly-public-api/revisions/4ba5b03a634a?raw)