Research Mode API Documentation

1. Overview

Research Mode is an advanced research feature that enables AI-powered conversational research. Users can ask natural-language questions and receive comprehensive, AI-generated summaries backed by relevant content from your knowledge base. The system automatically:

• Analyzes the question

• Generates optimized search queries

• Retrieves relevant content

• Synthesizes multi-document summaries

• Streams results in real time using Server-Sent Events (SSE)

2. Introduction

Research Mode transforms traditional search into an intelligent research workflow by:

1. Understanding question context using AI

2. Generating optimized search queries

3. Retrieving multiple relevant answers

4. Producing a comprehensive AI-generated summary

5. Providing citations to original content

6. Streaming responses in real time (SSE)

This allows vendors to integrate conversational research directly into their applications.

3. Prerequisites

Research Mode Feature must be enabled for your company — this will be done by Answer Engine team

• Research Mode configuration must be completed — this will be done by Answer Engine team

• Valid authentication token required

Base URL for all API calls: https://ask.lucy.ui or Client facing Answer Engine base URL

4. Authentication

Capacity Answer Engine supports both Symmetric and Asymmetric JWT authentication mechanisms to allow third-party applications to securely integrate with its system. This document outlines the setup process for both methods, key generation, configuration, and usage of the API for authentication and other APIs

Prerequisites

• Admin or SuperAdmin access to the Capacity Answer Engine instance

• Ability to generate and securely store JWT secrets (Symmetric or Asymmetric)

• Company ID (cid) provided by the Capacity Answer Engine team

Locate Your Capacity Answer Engine Instance ID

1. Login to the Capacity Answer Engine instance.

2. Navigate to Settings.

3. Note the Instance ID from the URL.

JWT Key Configuration

Navigate to: Settings → Security → JWT Configuration → Add Secret Key

View full size

• Click Add Secret Key

• Provide your JWT secret

• Choose Symmetric or Asymmetric

• If Auto provisioning is required, the under Manage Security Features section, Auto Provisioning toggle needs to be enabled

• If users need to be added in Auth0, then the under Manage Security Features section, Provisioning adds users to Auth0 toggle needs to be enabled

• Required if users expect to access Answer Engine webui in future

Symmetric Key Setup (Recommended for Testing)

1. Navigate to Settings → Security

2. Click Add Secret Key

3. Generate a UUID or a 30+ character string as the secret and store it securely

4. Do NOT enable the Asymmetric toggle

5. Use this key to generate JWT tokens (e.g., via jwt.io)

6. JWT Key generation format with example:

Header:

{
"alg": "HS256",
"typ": "JWT"
}

Payload Data:

{
"mode": "api",
"firstname": "first_name",
"lastname": "last_name",
"email": "valid email id",
"iat": 1752074171, ---- time in Unix Timestamp (Seconds): Refer https://www.epochconvert.com/
"exp": 1752160571, ---- time in Unix Timestamp (Seconds): Refer https://www.epochconvert.com/
"cid": "CapacityAnswerEngine_instance_id"
}

Sign JWT : Secret :

Provide the generated UUID earlier in the section shown in below screen shot from jwt.io

View full size

7. Delete this key from Capacity Answer Engine after testing is complete

Asymmetric Key Setup (Recommended for Production)

Generate Key Pair

# Private Key
openssl genpkey -algorithm RSA -out private_key.pem -pkeyopt rsa_keygen_bits:2048
# Public Key
openssl rsa -pubout -in private_key.pem -out public_key.pem

1. Navigate to Settings → Security

2. Click Add Secret Key

3. Mark as Asymmetric

4. Paste only the content of public_key.pem (excluding headers/footers)

JWT Token Format

Header:

{
"alg": "RS256",
"cid": CapacityAnswerEngine_instance_id
}

Payload Data:

{
"mode": "api",
"firstname": "first_name",
"lastname": "last_name",
"email": "valid email id",
"iat": 1752074171, ---- time in Unix Timestamp (Seconds): Refer https://www.epochconvert.com/
"exp": 1752160571 ---- time in Unix Timestamp (Seconds): Refer https://www.epochconvert.com/
}

Sign JWT : Secret :

=> Use the private key to sign the JWT token.

=> The IAT and EXP timestamps must have a maximum difference of 60 seconds (1 minute). The IAT should contain the current timestamp, and the EXP should be set to 60 seconds after the IAT. If the difference exceeds 60 seconds, the request will fail.

       * cid is an integer, not a string

Authenticate in Capacity Answer Engine using JWT Token

Once the JWT token is generated, use the token as Bearer token in the Header for the below Capacity Answer Engine Authentication API

Request Payload

curl --location --request POST 'https://ask.lucy.ai/api/qna/start' \
--header 'Authorization: Bearer JWT_Token'

Postman request screenshot of Request and Response of Authentication (/start) API

View full size

Response

If successfully validated then the caller will simply receive the auth token as part of the response. The body itself will be a string object, that is the auth token.

The auth token will be uses in further API calls such answer API, synopsis API etc

If the validation fails then the API will throw following errors:

5. API Endpoints

---

Run Research Query (Streaming)

POST https://ask.lucy.ui/api/qna/research

Streams AI-generated results in real time (SSE). Accept: text/event-stream. Parameters are passed as query params in the URL.

Get Current Chat History

GET https://ask.lucy.ui/api/qna/research/chat-history/{chat-uuid}

- Returns messages for a specific chat. UUID passed as a path parameter.

Get All Chat Histories for Current User

GET https://ask.lucy.ui/api/qna/research/chat-history-session

- Returns all chat histories for the current user as defined by the X-Auth-Token header.

Get Research Mode Configuration

GET https://ask.lucy.ui/api/qna/ai-config/prompt-mode

- Admin required — available ETA July 3.

Update Research Mode Configuration

POST https://ask.lucy.ui/api/qna/ai-config/prompt-mode

- Admin required — available ETA July 3.

6. Request Format

---

Research Query Request

POST https://ask.lucy.ui/api/qna/research

- Parameters are passed as query params in the URL rather than a JSON request body.

Headers

Content-Type: application/json
Accept: text/event-stream
X-Auth-Token: <your-token>

Query Parameters

Example Request

POST https://ask.lucy.ui/api/qna/research?question=What+are+the+key+findings+from+our+Q4+sales+analysis&time_from=2024-10-01&time_to=2024-12-31&selected_file_types=pdf,docx&selected_collections=123,456&autoFilter=true

7. Response Format & Event Types

Research Mode returns Server-Sent Events (SSE). Each SSE block:

event: <type>
data: <payload>

Event Types

8. Chat History

GET https://ask.lucy.ui/api/qna/research/chat-history/{chat-uuid}

GET https://ask.lucy.ui/api/qna/research/chat-history/00000000-0000-0000-0000-000000000000

GET https://ask.lucy.ui/api/qna/research/chat-history-session

GET https://ask.lucy.ui/api/qna/research/chat-history-session

9. Usage Examples

---

Basic Research Query

curl -X POST "https://ask.lucy.ui/api/qna/research?question=What+are+the+main+features+of+our+new+product?"
-H "Content-Type: application/json"
-H "Accept: text/event-stream"
-H "X-Auth-Token: your-token"

Research With fileType Filter

curl -X POST "https://ask.lucy.ui/api/qna/research?question=What+were+the+sales+figures+for+Q4+2024&selected_file_types=pdf"
-H "Content-Type: application/json"
-H "Accept: text/event-stream"
-H "X-Auth-Token: your-token"

Research with multiple filters

curl -X POST "https://ask.lucy.ui/api/qna/research?question=how+answer+engine+generates+an+answer&time_from=2025-1&time_to=2025-11&selected_file_types=PDF,Keynote,PPT,PPTX&selected_collections=af895cb6-a536-4d75-909d-4605635b65b1&selected_solr_companies=4975,1987,5000&autoFilter=true"
-H "Content-Type: application/json"
-H "Accept: text/event-stream"
-H "X-Auth-Token: your-token"

10. Error Handling

11. Best Practices

Handle SSE chunks incrementally; reconnect on network drops

• Use clear and specific natural language questions

• Use date/file filters for targeted results

• Use autoFilter=true to let the system detect relevant filters automatically

• Display queries as they generate; stream summary chunks to the UI; show citations from final response

12. Security

Never expose tokens in client code.