Answer Engine (Lucy) Answers API Documentation
QnA/Answers API Documentation
Overview
The QnA/Answers API enables comprehensive search across your knowledge base with advanced filtering options such as collections, file types, sources, metadata, and time ranges.
It returns highly relevant and curated answers to user questions while supporting AI-powered summaries.
Collections API
1. Get All Collections for an Instance
Endpoint:
GET https://ask.lucy.ai/api/qna/collection
Description: Retrieves all collections available in the user’s home instance to the authenticated user.
Authentication: Required
Response includes:
- Collection UUID
- Title and description
- Creation and update timestamps
Example Request
GET https://ask.lucy.ai/api/qna/collection Example Response
[
{
"id": 1597,
"title": "Saved Answers",
"description": null,
"userId": 1467,
"companyId": 82,
"createdAt": "2025-06-30T14:59:30.889122",
"updatedAt": "2025-06-30T14:59:30.889122",
"isContentUpdated": false,
"summary": null,
"collectionUUID": "2732f0a2-b6c7-4e1b-8ba4-79debff02447",
"deleted": false,
"followedByMe": false,
"priorityCollection": false
}
]2. Get Collections Filter
Endpoint:
GET https://ask.lucy.ai/api/qna/collection/collectionsFilters
Description: Returns simplified collection data for dropdowns or UI filters.
Authentication: Required
Example Response
[
{
"id": 2290,
"title": "2023 Retail Trends",
"description": "This collection brings together key insights, research reports, and strategic perspectives on the major retail trends that shaped 2023 . From evolving consumer behaviors and in-store experiences to the rise of AI, personalization, and omnichannel strategies. It's designed to help teams quickly reference the year’s most impactful developments, whether for strategic planning, competitive benchmarking, or informing future campaigns.\n\nUse this collection to ask targeted questions like \"What drove consumer loyalty in 2023?\" or \"How did leading retailers adapt to economic pressures?\" and get answers from just the content that’s relevant to 2023's retail landscape.",
"userId": 79140,
"companyId": 82,
"createdAt": "2025-07-16T13:40:34.589536",
"updatedAt": "2025-07-16T14:12:18.96994",
"isContentUpdated": false,
"summary": null,
"collectionUUID": "af895cb6-a536-4d75-909d-4605635b65b1",
"deleted": false
},
{
"id": 2289,
"title": "Gen Z Soda Trends",
"description": "This collection contains the latest Gen Z trends relating to soda consumption. ",
"userId": 79140,
"companyId": 82,
"createdAt": "2025-07-16T13:31:14.656364",
"updatedAt": "2025-07-16T13:32:08.779948",
"isContentUpdated": false,
"summary": null,
"collectionUUID": "4c80a5a2-b97e-4e4f-8204-f39b2cfa1a73",
"deleted": false
}
]Answers/QnA API
Base URL: https://ask.lucy.ai/api/qna/answers
Main Answers Endpoint
Endpoint:
GET https://ask.lucy.ai/api/qna/answersDescription: The main endpoint for querying answers. Supports advanced filters for collections, sources, file types, metadata, and more.
Authentication: Required
Response Includes
answers: List of answer objectsshortAnswer: AI-generated synopsis (if enabled)verifiedAnswers: Cached/verified resultsaggregatedConcepts: Extracted key concepts
Example Request
1 GET https://ask.lucy.ai/api/qna/answers?q=how%20lucy%20generates%20an%20answer&source=lucy&selected_answers_limit=12&resultsize=small&debugmode=true&t=1763369962&researchType=QnA&sub_companies=&selectedLanguage=en&view=answer&isdocview=false&saveHistory=true&lucy-version=4&companyId=82&synopsis=false&tempQuestionId=45838dbd-1a83-315f-1f9e-507de3bd55da&workdayToggle=false&skiptraining=false&mode=regular&researchTypeMode=0Example Response
{
"answers": [
{
"AnswerID": "118034592_18",
"MD5": "",
"Title": "Lucys an answer engine, and so you can ask her a natural language question and she brings back,... <keyword> Lucys an answer engine, and so you can ask her a natural language question and she brings back, you know, kind of that, that answer. </keyword> ",
"Text": "<lucy-player video=\"1ba0609387\" time=\"135\" auGeneratedFrom=\"transcript\"></lucy-player>",
"Confidence": 0.0,
"ExpertRating": 0.0,
"TrainingCount": 2,
"Company": "003ux",
"Source": "[ObjectStoreURL]/l2-003ux/PepsiCoHRWebinar.mp4?bsaccount=1f441773-53bb-478e-9969-f71d3eaf6791&bsid=eyJzaXRlIjoiZXF1YWxzM2FpLnNoYXJlcG9pbnQuY29tLDliZTQzNzcyLTU3MmItNDU0OC1hOGJkLWY2MGEyYTZmMzkxMyxkMTYyZWFkYi1jNjg0LTQ1NzQtYmU2Mi1hNWFlMzExNmJkZjEiLCJkcml2ZSI6ImIhY2pma215dFhTRVdvdmZZS0ttODVFOXZxWXRHRXhuUkZ2bUtscmpFV3ZmR1JlNkxBM1l5aFJwNndaaUNaZFhhcSIsImZpbGUiOiIwMTY1Q1oyQzc0NERBUldLTzNYWkJaTVBGVldVVVg2QzZPIn0=",
"Cite": "HR Docs and Policy",
"Answer_Concepts": "none",
"Answer_Taxonomy": "none",
"Answer_Keywords": "none",
"Filter3": "18of523",
"author_name": "",
"FileName": "PepsiCoHRWebinar.mp4",
"currentPageNumber": 18,
"totalpageCount": 523,
"Description": "",
"Language": "",
"Topic": "",
"assetDetailsUrl": "",
"section": "",
"V2Passage": "",
"isGPS": false,
"isThirdPartySource": false,
"shouldShowSourceNameInChat": false,
"answer_locations": "",
"answer_brands": "",
"answer_persons": "Lucy",
"combinedData": "So we we dont use the word search engine.. \nLucys an answer engine, and so you can ask her a natural language question and she brings back, you know, kind of that, that answer.. \nHow do where And again with opportunity of those kinds of things.. \nWhats also really cool as we step into this is were enabling that inside of chat or other places.. \nSo if youre using Teams or Slack where you can actually ask those same questions and teams or Slack and get an answer, so.. \n",
"userSelectedDate": null,
"TagData": null,
"Taxonomies": [],
"CustomTaxonomies": [],
"Concepts": [],
"Entities": [],
"DiscoveryConcepts": [],
"DiscoveryTaxonomies": [],
"DiscoveryKeywords": [],
"DiscoveryEntities": [],
"CompanyandSource": [],
"documentDate": "2022-07-21T18:45:35Z",
"createdDate": "2023-10-24T05:49:20Z",
"updatedDate": "2022-08-04T20:17:54Z",
"categories": "",
"Passage": "Lucys an answer engine, and so you can ask her a natural language question and she brings back,... <keyword> Lucys an answer engine, and so you can ask her a natural language question and she brings back, you know, kind of that, that answer. </keyword> ",
"meta": {
"site_id": "eyJzaXRlIjoiZXF1YWxzM2FpLnNoYXJlcG9pbnQuY29tLDliZTQzNzcyLTU3MmItNDU0OC1hOGJkLWY2MGEyYTZmMzkxMyxkMTYyZWFkYi1jNjg0LTQ1NzQtYmU2Mi1hNWFlMzExNmJkZjEifQ==",
"site_name": "Lucy Demo content",
"site_url": "https://equals3ai.sharepoint.com/sites/LucyDemo",
"parent_id": "eyJzaXRlIjoiZXF1YWxzM2FpLnNoYXJlcG9pbnQuY29tLDliZTQzNzcyLTU3MmItNDU0OC1hOGJkLWY2MGEyYTZmMzkxMyxkMTYyZWFkYi1jNjg0LTQ1NzQtYmU2Mi1hNWFlMzExNmJkZjEiLCJkcml2ZSI6ImIhY2pma215dFhTRVdvdmZZS0ttODVFOXZxWXRHRXhuUkZ2bUtscmpFV3ZmR1JlNkxBM1l5aFJwNndaaUNaZFhhcSIsImZpbGUiOiIwMTY1Q1oyQzdIWTJCVklHQ0dGUkNZWURMR1RMWU9LRFlZIn0=",
"parent_name": "HR Docs",
"parent_url": "https://equals3ai.sharepoint.com/sites/LucyDemo/Shared%20Documents/Demo%20Files/HR%20Docs",
"SourceFileName": "PepsiCoHRWebinar.mp4",
"modifier": "SharePoint App",
"Language": "en",
"project_id": 118034285,
"file_id": 118034592,
"enrich": "categories_unavailable",
"video_date_update": "success",
"verified": true,
"upVoteCount": 2,
"downVoteCount": 0,
"remainingVoteCount": 2
},
"relevancyScore": null,
"answerDate": "Created Date",
"upVote": 2,
"downVote": 0,
"embeddings": null,
"weightageByDate": 0.0,
"collectionDetails": null,
"verified": false,
"sourceMeta": "{}",
"isVerified": true
}
],
"Concepts": [],
"Taxonomies": [
{
"MetaData": "science->social science->history",
"total_count": 1
},
{
"MetaData": "society->work->unemployment",
"total_count": 1
},
{
"MetaData": "technology and computing",
"total_count": 1
},
{
"MetaData": "none",
"total_count": 1
}
],
"CustomTaxonomies": [],
"organizations": [
{
"text": "Equals 3, LLC",
"count": 9
},
{
"text": "Equals 3",
"count": 4
},
{
"text": "IBM",
"count": 4
},
{
"text": "IDC",
"count": 4
},
{
"text": "Lucy",
"count": 4
}
],
"locations": [
{
"text": "U.S.",
"count": 8
},
{
"text": "Minneapolis",
"count": 4
},
{
"text": "US",
"count": 4
},
{
"text": "KM",
"count": 3
},
{
"text": "New York",
"count": 3
}
],
"persons": [],
"tags": [],
"agencies": [],
"proximoBrands": [],
"docViewData": [
{
"answer_id": "117193296_7",
"FileName": "Lucyisananswerengine.mov",
"InternalFileName": "Lucyisananswerengine.mov",
"author_name": "",
"modifier_name": "SharePoint App",
"Cite": "SharePoint - Misc",
"Source": "[ObjectStoreURL]/l2-003tu/Lucyisananswerengine.mov?bsaccount=1f441773-53bb-478e-9969-f71d3eaf6791&bsid=eyJzaXRlIjoiZXF1YWxzM2FpLnNoYXJlcG9pbnQuY29tLDliZTQzNzcyLTU3MmItNDU0OC1hOGJkLWY2MGEyYTZmMzkxMyxkMTYyZWFkYi1jNjg0LTQ1NzQtYmU2Mi1hNWFlMzExNmJkZjEiLCJkcml2ZSI6ImIhY2pma215dFhTRVdvdmZZS0ttODVFOXZxWXRHRXhuUkZ2bUtscmpFV3ZmR1JlNkxBM1l5aFJwNndaaUNaZFhhcSIsImZpbGUiOiIwMTY1Q1oyQzZBQUNBM1lHN1pBQkJZWkozRVdFWUdWS1hKIn0=",
"Passage": "",
"Company": "003tu",
"Filter3": "7of32",
"Pages": 0,
"documentDate": "2019-02-28T20:21:25Z",
"updatedDate": "2020-02-02T01:47:35Z",
"Confidence": 0.06529566586017609,
"Entities": []
}
],
"autoSearchFiles": [],
"docViewCount": 1,
"questionId": 1265830,
"qnaToken": "bb16b0b8-dae2-4ed3-8a89-6f9af2314602"
}Query Parameters Reference
Core Parameters
q (Required)
Search query text. URL-encoded. Maximum 1000 characters.
Examples:
q=market+research+trends q=quarterly+financial+reports
collectionUUID (Optional, High Importance)
Restricts search to a specific collection.
Obtain from GET /collection as mentioned above
Example:
1 GET /answers?q=market+analysis&collectionUUID=abc123-def456Synopsis and Display
- synopsis:
"true"or"false"(default"true")
Controls AI-generated summaries. - synopsisView: Optional display mode.
- lucy-version: Default
"4". Enables advanced caching.
Source and Company Filters
selected_solr_companies (High Importance)
Comma-separated Source IDs.
Example:
1 selected_solr_companies=5302,5001,4977,4978File Type Filters
selected_file_types (High Importance)
Comma-separated list: PDF, DOCX, PPTX, XLSX, Image, Video, Audio, Other.
Example:
1 selected_file_types=PDF,DOCXDate Range Filters
time_from / time_to (Medium Importance)
Filters by document creation or modification dates.
Format: YYYY-MM-DD or ISO8601
Example:
1 time_from=2024-01-01&time_to=2024-12-31Metadata Language Filters
metaFilters: Additional metadata-based filtering.
Example
1 metaFilters=(meta.Language:("en"))Brand and Location Filters
- selected_brands: Comma-separated list of brand names.
- selected_locations: Comma-separated list of geographic locations.
Example:
1 selected_brands=BrandA,BrandB& 2 selected_locations=US,Europe 3 selected_brands=IDC&selected_locations=California
Answer Limit and Display
selected_answers_limit (Medium Importance)
Limits number of results. Default: 10.
Example: selected_answers_limit=10
isdocview: "true" or "false". For UI view preference.
Advanced Parameters (Low Importance)
- saveHistory: Controls history saving.
- selectedLanguage: Language code (e.g.,
en). - source: Origin identifier (e.g.,
lucy).
Filter Combinations and Best Practices
Collection-Focused Research
1 q=your+question 2 collectionUUID=your-collection-uuid 3 selected_answers_limit=25 4
Multi-Filter Collection Research
1 q=quarterly+reports 2 collectionUUID=2732f0a2-b6c7-4e1b-8ba4-79debff02447 3 selected_file_types=PDF 4 time_from=2024-01-01 5 time_to=2024-12-31 6 selected_solr_companies=123,456 7 selected_answers_limit=30 8
Time-Bound Collection Research
1 q=market+insights 2 collectionUUID=2732f0a2-b6c7-4e1b-8ba4-79debff02447 3 time_from=2024-06-01 4 selected_file_types=PDF,PPTX 5
Source-Specific Collection Research
1 q=your+question 2 collectionUUID=2732f0a2-b6c7-4e1b-8ba4-79debff02447 3 selected_solr_companies=123,456 4 selected_file_types=DOCX,PDF 5
Metadata-Enhanced Collection Research
1 q=your+question 2 collectionUUID=2732f0a2-b6c7-4e1b-8ba4-79debff02447 3 meta_query=concept1,concept2 4 selected_taxonomy=taxonomy1 5
Brand and Location Filtering
1 q=your+question 2 collectionUUID=2732f0a2-b6c7-4e1b-8ba4-79debff02447 3 selected_brands=BrandA,BrandB 4 selected_locations=US,Europe 5 time_from=2024-01-01 6 time_to=2024-12-31 7
General Best Practices
- Invoke endpoint
GET /collectionto identify available collections in the instance. - Combine filters strategically (file type, date, source).
- Combine metadata and taxonomy for semantic precision.
- Use source filters for relevance and performance optimization.
Error Responses
- 400 Bad Request: Missing
qor invalid parameters - 401 Unauthorized: Missing or invalid authentication
- 403 Forbidden: Insufficient permissions
- 404 Not Found: Invalid UUID or endpoint
- 500 Internal Server Error: Server-side error