# Retrieval

Retrieval related APIs

## Alli Retrieval API

> The Retrieval API allows you to obtain the top N page information related to a question from documents uploaded to Alli. This API combines keyword search and semantic search capabilities to provide the most relevant document pages for your queries.<br>

```json
{"openapi":"3.1.0","info":{"title":"Alli API Documentation","version":"1.0.0"},"tags":[{"name":"retrieval","description":"Retrieval related APIs"}],"servers":[{"url":"https://backend.alli.ai","description":"US"}],"security":[{"ApiKeyAuth":[]},{"TokenAuth":[]},{"ProjectIdHeader":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"API-KEY","description":"Your API key for authentication"},"TokenAuth":{"type":"http","scheme":"bearer","description":"Your token for authentication"}},"parameters":{"AgentEmailHeader":{"name":"AGENT-EMAIL","in":"header","required":false,"schema":{"type":"string"},"description":"Optional: Email of the agent to use for this request"},"UserEmailHeader":{"name":"USER-EMAIL","in":"header","required":false,"schema":{"type":"string"},"description":"Optional: Email address to associate with the user"},"OwnUserIdHeader":{"name":"OWN-USER-ID","in":"header","required":false,"schema":{"type":"string"},"description":"Optional: User ID to identify or create a user"}}},"paths":{"/webapi/retrieval":{"post":{"tags":["retrieval"],"operationId":"retrievalPost","summary":"Alli Retrieval API","description":"The Retrieval API allows you to obtain the top N page information related to a question from documents uploaded to Alli. This API combines keyword search and semantic search capabilities to provide the most relevant document pages for your queries.\n","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"question":{"type":"string","description":"Question to search for in the document base","required":true},"maxDocumentClues":{"type":"integer","description":"Determines how many related pages to retrieve. The default value is 3.\n"},"bm25_score_weight":{"type":"number","format":"float","description":"This is the weight for keyword search. The higher this value, the more the keyword score is reflected. Values between 0-9 are appropriate, with a value of 0 meaning keyword search is not used. The default value is 9.\n"},"text_vector_score_weight":{"type":"number","format":"float","description":"This is the weight for semantic search on document content. The higher this value, the more it is reflected. Values between 0-9 are appropriate, with a value of 0 meaning semantic search on document content is not used. The default value is 1.\n"},"title_vector_score_weight":{"type":"number","format":"float","description":"This is the weight for semantic search on document titles. Similarly, values between 0-9 are appropriate, with a value of 0 meaning semantic search on document titles is not used. The default value is 0.\n"},"hashtags":{"type":"array","items":{"type":"string"},"description":"Filter results to include only documents with these hashtags"},"hashtags_operator":{"type":"string","enum":["and","or"],"description":"Logical operator for hashtags (default is \"or\")"},"exclude_hashtags":{"type":"array","items":{"type":"string"},"description":"Filter results to exclude documents with these hashtags"},"exclude_hashtags_operator":{"type":"string","enum":["and","or"],"description":"Logical operator for exclude_hashtags (default is \"or\")"},"targetFolders":{"type":"array","items":{"type":"string"},"description":"Names of folders to search within"},"folderIds":{"type":"array","items":{"type":"string"},"description":"IDs of folders to search within"},"knowledgeBaseIds":{"type":"array","items":{"type":"string"},"description":"IDs of specific knowledge bases to search within"},"use_keywords":{"type":"boolean","description":"Whether to extract and use keywords for search"},"use_clue_feedback":{"type":"boolean","description":"Whether to use feedback data to improve search results"}}}}}},"responses":{"200":{"description":"Successfully retrieved results","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"array","items":{"type":"object","properties":{"ranking":{"type":"integer","description":"Rank of the page related to the question"},"title":{"type":"string","description":"Title of the document related to the question"},"text":{"type":"string","description":"Content of the page related to the question"},"pageNo":{"type":"integer","description":"Page number"},"kb_id":{"type":"string","description":"ID of the knowledge base document"}}}}}}}}},"400":{"description":"Invalid parameters","content":{"application/json":{"schema":{"type":"object","properties":{"errors":{"type":"string"}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}}},"parameters":[{"$ref":"#/components/parameters/AgentEmailHeader"},{"$ref":"#/components/parameters/UserEmailHeader"},{"$ref":"#/components/parameters/OwnUserIdHeader"}]}}}}
```