Search case evidence

Add MCP server to your AI tool

Allow AI tools and LLMs to interact with the API documentation portal through MCP.

MCP server URL


        
          
            https://docs.usehearsay.com/mcp

Standard setup for AI tools providing an mcp.json file

{
  "integrations MCP server": {
    "url": "https://docs.usehearsay.com/mcp"
  }
}

POST /ai/cases/{caseId}/search

Access token

Runs a semantic search over the case evidence and returns the best matches (messages or conversation chunks) with score, snippet and, when asked, the surrounding messages, filtered by source, dates, participants, conversations, topics or relevance. On a case shared with opposing counsel, callers on the other side see only evidence released to them, and conversation chunks are left out. Requires commenter access or above to the case and an active plan (403 otherwise).

Path parameters

caseId string Required

Id of the case

application/json

Body Required

query string Required
filters object
Hide filters attributes Show filters attributes object
- sources array[string]
  
  Values are device_message, linkedin, reddit, discord, email, or ai_chat.
- dateRange object
  Hide dateRange attributes Show dateRange attributes object
  
  start string(date-time)
  
  end string(date-time)
- participants array[string]
- conversationIds array[string]
- topics array[string]
- legalRelevance array[string]
granularity string

Values are messages, chunks, or mixed. Default value is messages.
topK number

Minimum value is 1, maximum value is 100. Default value is 50.
rerank boolean

Default value is true.
expandContext object
Hide expandContext attributes Show expandContext attributes object
- before number
  
  Default value is 0.
- after number
  
  Default value is 0.

Responses

200 application/json
Hide response attributes Show response attributes object
- data object Required
  
  Hide data attributes Show data attributes object
  
  items array[object] Required
  
  Hide items attributes Show items attributes object
  
  kind string Required
  
  Values are message or chunk.
  
  id string Required
  
  Primary id of the item — DeviceMessage._id when kind=message, AiConversationChunk._id when kind=chunk
  
  messageId string Required
  
  Back-compat alias for id — Phase 1 clients used this
  
  source string Required
  
  Values are device_message, linkedin, reddit, discord, email, or ai_chat.
  
  conversationId string Required
  
  sender string
  
  timestamp string(date-time)
  
  score number Required
  
  snippet string Required
  
  topics array[string]
  
  Topic tags — only present when kind=chunk
  
  expandedContext object
  
  Hide expandedContext attributes Show expandedContext attributes object
  
  before array[object] Required
  
  Hide before attributes Show before attributes object
  
  messageId string Required
  
  text string Required
  
  timestamp string(date-time) Required
  
  after array[object] Required
  
  Hide after attributes Show after attributes object
  
  messageId string Required
  
  text string Required
  
  timestamp string(date-time) Required
  
  candidateCount number Required
  
  vectorSearchTopN number Required
  
  rerankApplied boolean Required
  
  queryEmbeddingModel string | null
- statusCode number Required
- timestamp string(date-time) Required

POST /ai/cases/{caseId}/search

curl \
 --request POST 'http://api.example.com/ai/cases/{caseId}/search' \
 --header "Authorization: Bearer $ACCESS_TOKEN" \
 --header "Content-Type: application/json" \
 --data '{
  "query": "string",
  "filters": {
    "sources": [
      "device_message"
    ],
    "dateRange": {
      "start": "2026-05-04T09:42:00Z",
      "end": "2026-05-04T09:42:00Z"
    },
    "participants": [
      "string"
    ],
    "conversationIds": [
      "string"
    ],
    "topics": [
      "string"
    ],
    "legalRelevance": [
      "string"
    ]
  },
  "granularity": "messages",
  "topK": 50,
  "rerank": true,
  "expandContext": {
    "before": 0,
    "after": 0
  }
}'

Request examples

{
  "query": "string",
  "filters": {
    "sources": [
      "device_message"
    ],
    "dateRange": {
      "start": "2026-05-04T09:42:00Z",
      "end": "2026-05-04T09:42:00Z"
    },
    "participants": [
      "string"
    ],
    "conversationIds": [
      "string"
    ],
    "topics": [
      "string"
    ],
    "legalRelevance": [
      "string"
    ]
  },
  "granularity": "messages",
  "topK": 50,
  "rerank": true,
  "expandContext": {
    "before": 0,
    "after": 0
  }
}

Response examples (200)

{
  "data": {
    "items": [
      {
        "kind": "message",
        "id": "65a1b2c3d4e5f6a7b8c9d0f1",
        "messageId": "65a1b2c3d4e5f6a7b8c9d0f1",
        "source": "device_message",
        "conversationId": "65a1b2c3d4e5f6a7b8c9d0f0",
        "sender": "+15555550123",
        "timestamp": "2026-01-15T10:15:00.000Z",
        "score": 0.83,
        "snippet": "I will not be at the pickup tomorrow.",
        "topics": [
          "custody",
          "scheduling"
        ],
        "expandedContext": {
          "before": [
            {
              "messageId": "65a1b2c3d4e5f6a7b8c9d0f2",
              "text": "See you at the exchange on Friday.",
              "timestamp": "2026-01-15T10:15:00.000Z"
            }
          ],
          "after": [
            {
              "messageId": "65a1b2c3d4e5f6a7b8c9d0f2",
              "text": "See you at the exchange on Friday.",
              "timestamp": "2026-01-15T10:15:00.000Z"
            }
          ]
        }
      }
    ],
    "candidateCount": 50,
    "vectorSearchTopN": 50,
    "rerankApplied": true,
    "queryEmbeddingModel": "cohere.embed-english-v3"
  },
  "statusCode": 200,
  "timestamp": "2026-01-15T10:15:00.000Z"
}