Search Mode API Documentation

1. Introduction

The Search Mode API is the core interface for querying the Capacity answer engine. It enables applications and integrations to submit natural-language questions and receive ranked, curated answers drawn from your organization's indexed knowledge base — including documents, videos, presentations, and other content sources.

This documentation covers the main answers endpoint, all supported query parameters, collection-scoped search, and best practices for building effective search experiences on top of the API.

2. Prerequisites

Active Capacity instance: Your organization must have a provisioned Capacity environment with an accessible answer engine base URL.

• Valid credentials: A valid user account with an active XAuth-Token is required for all authenticated requests.

• Indexed content: Content must be indexed in your Capacity instance before it can be retrieved through the API.

• Collection UUIDs (if filtering by collection): Use the GET /collection endpoint described in Section 6.

3. Overview

The QnA/Answers API enables comprehensive search across your knowledge base with advanced filtering options. It returns highly relevant and curated answers while supporting AI-powered summaries.

Base URL: https://ask.lucy.ai or customer specific 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:

Accessing Answers Endpoint (Request & response)

Request Payload

curl --location --request GET 'https://ask.lucy.ai/api/qna/answers?q={question/query}&source=lucy&selected_answers_limit=12&researchType=QnA&saveHistory=true&lucy-version=4&companyId={lucy_company_id}&synopsis=false' \
--header 'x-auth-token: {auth_token_returned_fron_start_API}'

Response

Answers API will return set of answers along with other properties in JSON Format

Here is the response screen shot. Capture the value of qnaToken:

View full size

Accessing Synopsis Endpoint (Request & response)

GET https://ask.lucy.ai/api/qna/synopsis

Request Payload

curl --location --request GET 'https://ask.lucy.ai/api/qna/synopsis?q={question/query}&source=lucy&selected_answers_limit=12&researchType=QnA&saveHistory=true&lucy-version=4&companyId={lucy_company_id}&synopsis=false&qnaToken={token_from_answers_api}' \
--header 'x-auth-token: {auth_token_returned_fron_start_API}'

Response

Synopsis API endpoint will return the same answers for the question/query along with a property called shortAnswer which contains the Synopsis

Here is the sample response:

View full size

Accessing Explore more questions Endpoint (Request & response)

POST https://ask.lucy.ai/api/qna/get-question-suggestions-to-explore

Request Payload

curl --location --request POST 'https://ask.lucy.ai/api/qna/get-question-suggestions-to-explore' \
--header 'x-auth-token: {auth_token_returned_fron_start_API}' \
--header 'Content-Type: application/json' \
--data-raw '{
"content": "{shortAnswer_from_synopsis_api}",
"numberOfQuestions": 3
}'

Response

Explore more questions Endpoint will return number of questions based on the request payload as JSON array of strings

Here is a sample response:

View full size

5. Answers API Reference

---

Response Fields

Query Parameters

Parameter Examples

q

q=market+research+trends
q=quarterly+financial+reports

selected_solr_companies

selected_solr_companies=5302,5001,4977,4978

selected_file_types

selected_file_types=PDF,DOCX

time_from / time_to

time_from=2024-01-01&time_to=2024-12-31

metaFilters

metaFilters=(meta.Language:("en"))

selected_brands / selected_locations

selected_brands=BrandA,BrandB&selected_locations=US,Europe

collectionUUID

GET /answers?q=market+analysis&collectionUUID=abc123-def456

6. Collections API

GET https://ask.lucy.ai/api/qna/collection — Retrieves all collections available to the authenticated user.

GET https://ask.lucy.ai/api/qna/collection

GET https://ask.lucy.ai/api/qna/collection/collectionsFilters — Returns simplified collection data for dropdowns or UI filters.

7. Filter Combinations and Best Practices

---

Collection-Focused Research

q=your+question
collectionUUID=your-collection-uuid
selected_answers_limit=25

Multi-Filter Collection Research

q=quarterly+reports
collectionUUID=2732f0a2-b6c7-4e1b-8ba4-79debff02447
selected_file_types=PDF
time_from=2024-01-01
time_to=2024-12-31
selected_answers_limit=30

General Best Practices

1. Invoke endpoint GET /collection to identify available collections in the instance.

2. Combine filters strategically (file type, date, source).

3. Combine metadata and taxonomy for semantic precision.

4. Use source filters for relevance and performance optimization.

8. Error Responses