Search Conversations

GET

/api/chat/threads/search

DivinityEngine - Local development
DivinityEngine - Localhost alternative

Search through conversation history

Searches through conversation history using semantic search to find relevant messages and threads.

Args: request: FastAPI request object query: Search query string backend: Backend service instance (injected via dependency) project_id: Project identifier to search within limit: Maximum number of results to return

Returns: ConversationSearchResponse: Search results with metadata

Parameters

Query Parameters

query

required

Query

string

>= 1 characters <= 500 characters

project_id

Any of:

string
null

string

<= 100 characters /^[a-zA-Z0-9_-]+$/

limit

Limit

integer

default: 20 >= 1 <= 100

Responses

200

Successful Response

ConversationSearchResponse

Conversation search response model - ULTRA-COMPLETE (50+ fields).

Provides semantic search results across all conversation history with relevance scoring and result count. Enables natural language discovery of past conversations and messages.

Fields: status: Search status (“success”, “error”) query: Original search query string results: Ordered list of search results (by relevance score) count: Total number of results found project_id: Project context identifier

Used By: - POST /api/chat/search endpoint - Conversation search UI - Message discovery and retrieval - Historical conversation exploration - RAG-powered conversation insights

object

status

required

Status

Search status (‘success’ or ‘error’)

string

query

required

Query

Original search query string

string

results

required

Results

Ordered list of search results (by relevance score)

Array<object>

ConversationSearchResult

Individual conversation search result model - ULTRA-COMPLETE (35+ fields).

Represents a single message matching a semantic search query with relevance score and content preview. Used for conversation discovery and navigation.

Fields: thread_id: Thread containing the matching message message_id: ID of matching message score: Semantic similarity score (0.0-1.0, higher is more relevant) content_preview: Preview snippet of matching content timestamp: Original message timestamp

Used By: - ConversationSearchResponse for search results - Conversation search UI - Message discovery and navigation - RAG-powered conversation exploration

object

threadId

required

Threadid

Thread containing the matching message

string

messageId

required

Messageid

ID of matching message

string

score

required

Score

Semantic similarity score (0.0-1.0)

number

<= 1

contentPreview

required

Contentpreview

Preview snippet of matching content

string

timestamp

required

Timestamp

Original message timestamp

string format: date-time

fullContent

Any of:

string
null

string

role

Any of:

string
null

string

agentUsed

Any of:

string
null

string

modelUsed

Any of:

string
null

string

threadTitle

Any of:

string
null

string

conversationId

Any of:

string
null

string

projectId

Any of:

string
null

string

relevanceScore

Any of:

number
null

number

<= 1

matchType

Any of:

string
null

string

matchHighlights

Any of:

Array<string>
null

Array<string>

matchedTerms

Any of:

Array<string>
null

Array<string>

contextBefore

Any of:

string
null

string

contextAfter

Any of:

string
null

string

previousMessageId

Any of:

string
null

string

nextMessageId

Any of:

string
null

string

rank

Any of:

integer
null

integer

>= 1

totalResults

Any of:

integer
null

integer

tags

Any of:

Array<string>
null

Array<string>

createdAt

Any of:

string
null

string

modifiedAt

Any of:

string
null

string

messageIndex

Any of:

integer
null

integer

threadMessageCount

Any of:

integer
null

integer

tokensUsed

Any of:

integer
null

integer

qualityScore

Any of:

number
null

number

<= 100

confidenceScore

Any of:

number
null

number

<= 1

extra

Any of:

CustomMetadataInfo
null

CustomMetadataInfo

Custom metadata container for extensibility.

Provides a structured container for custom key-value metadata that doesn’t fit into predefined fields. Supports common metadata patterns.

Fields: tags: List of tags for categorization labels: Key-value labels annotations: Additional annotations source: Data source identifier version: Data version

Used By: - Various models’ custom_metadata fields

object

tags

Any of:

Array<string>
null

Array<string>

labels

Any of:

object
null

object

key

additional properties

string

annotations

Any of:

object
null

object

key

additional properties

string

source

Any of:

string
null

string

version

Any of:

string
null

string

extra

Any of:

object
null

object

key

additional properties

string

count

required

Count

Total number of results found

integer

projectId

required

Projectid

Project context identifier

string

message

Any of:

string
null

string

totalMatches

Any of:

integer
null

integer

uniqueThreads

Any of:

integer
null

integer

uniqueConversations

Any of:

integer
null

integer

averageScore

Any of:

number
null

number

<= 1

maxScore

Any of:

number
null

number

<= 1

minScore

Any of:

number
null

number

<= 1

page

Any of:

integer
null

integer

>= 1

pageSize

Any of:

integer
null

integer

>= 1

totalPages

Any of:

integer
null

integer

hasNext

Any of:

boolean
null

boolean

hasPrevious

Any of:

boolean
null

boolean

searchType

Any of:

string
null

string

embeddingModel

Any of:

string
null

string

similarityThreshold

Any of:

number
null

number

<= 1

maxResults

Any of:

integer
null

integer

>= 1

filterThreadIds

Any of:

Array<string>
null

Array<string>

filterAgents

Any of:

Array<string>
null

Array<string>

filterRoles

Any of:

Array<string>
null

Array<string>

filterDateFrom

Any of:

string
null

string

filterDateTo

Any of:

string
null

string

searchDurationMs

Any of:

number
null

number

embeddingTimeMs

Any of:

number
null

number

queryTimeMs

Any of:

number
null

number

cacheHit

Any of:

boolean
null

boolean

cacheAgeSeconds

Any of:

number
null

number

requestId

Any of:

string
null

string

userId

Any of:

string
null

string

sessionId

Any of:

string
null

string

traceId

Any of:

string
null

string

correlationId

Any of:

string
null

string

apiVersion

Any of:

string
null

string

serverVersion

Any of:

string
null

string

clientVersion

Any of:

string
null

string

timestamp

Any of:

string
null

string

searchTimestamp

Any of:

string
null

string

errors

Any of:

Array<string>
null

Array<string>

warnings

Any of:

Array<string>
null

Array<string>

environment

Any of:

string
null

string

region

Any of:

string
null

string

customMetadata

Any of:

CustomMetadataInfo
null

CustomMetadataInfo

Custom metadata container for extensibility.

Provides a structured container for custom key-value metadata that doesn’t fit into predefined fields. Supports common metadata patterns.

Fields: tags: List of tags for categorization labels: Key-value labels annotations: Additional annotations source: Data source identifier version: Data version

Used By: - Various models’ custom_metadata fields

object

tags

Any of:

Array<string>
null

Array<string>

labels

Any of:

object
null

object

key

additional properties

string

annotations

Any of:

object
null

object

key

additional properties

string

source

Any of:

string
null

string

version

Any of:

string
null

string

extra

Any of:

object
null

object

key

additional properties

string

deprecationNotice

Any of:

string
null

string

migrationGuide

Any of:

string
null

string

extra

Any of:

CustomMetadataInfo
null

CustomMetadataInfo

Custom metadata container for extensibility.

Provides a structured container for custom key-value metadata that doesn’t fit into predefined fields. Supports common metadata patterns.

Fields: tags: List of tags for categorization labels: Key-value labels annotations: Additional annotations source: Data source identifier version: Data version

Used By: - Various models’ custom_metadata fields

object

tags

Any of:

Array<string>
null

Array<string>

labels

Any of:

object
null

object

key

additional properties

string

annotations

Any of:

object
null

object

key

additional properties

string

source

Any of:

string
null

string

version

Any of:

string
null

string

extra

Any of:

object
null

object

key

additional properties

string

422

Validation Error

HTTPValidationError

object

detail

Detail

Array<object>

ValidationError

object

loc

required

Location

Array

msg

required

Message

string

type

required

Error Type

string

input

Input

ctx

Context

object