Skip to main content
POST
/
v1
/
knowledge
/
similar
Search similar patterns
curl --request POST \
  --url https://api.example.com/v1/knowledge/similar \
  --header 'Content-Type: application/json' \
  --data '
{
  "title": "<string>",
  "description": "<string>"
}
'

​
Overview

Performs a semantic similarity search across the knowledge base to find patterns that match a given incident title and description. Use this to check whether a new or ongoing incident resembles a known failure pattern before triggering a full investigation. Required role: admin or member

​
Request body

​
title
string
required
A short title describing the incident or failure you are searching for. This is used as the primary search signal.
​
description
string
required
A detailed description of the symptoms, affected services, and observed behavior. More detail produces more accurate similarity results.

​
Response

Returns 200 OK with a ranked list of similar patterns, ordered by similarity score descending. 
{
  "similar": [
    {
      "patternId": "pat_01HX9VTPQR3KF8MZWBYD5N6JCE",
      "title": "Connection pool exhaustion under payment processor load spike",
      "similarity": 0.91,
      "confidence": 0.94,
      "status": "stable",
      "occurrences": 12
    },
    {
      "patternId": "pat_01HX9VTPQR3KF8MZWBYD5N6JCF",
      "title": "Third-party API timeout cascade causing queue backlog",
      "similarity": 0.74,
      "confidence": 0.81,
      "status": "stable",
      "occurrences": 6
    },
    {
      "patternId": "pat_01HX9VTPQR3KF8MZWBYD5N6JCG",
      "title": "Database connection leak after unclean service restart",
      "similarity": 0.58,
      "confidence": 0.61,
      "status": "emerging",
      "occurrences": 3
    }
  ]
}
FieldTypeDescription
patternIdstringUnique identifier for the matching pattern
titlestringHuman-readable summary of the failure pattern
similaritynumberSimilarity score between 0 and 1. Higher values indicate a closer match
confidencenumberPattern confidence score between 0 and 1, based on confirmed historical occurrences
statusstringPattern maturity: emerging or stable
occurrencesintegerNumber of past incidents where this pattern was confirmed
Results with similarity above 0.85 are strong matches and suggest a known pattern is likely to apply. Results between 0.6 and 0.85 are worth reviewing but may require further investigation. Results below 0.6 are returned for completeness but are unlikely to be directly applicable.

​
Error responses

StatusError codeDescription
400validation_errortitle or description is missing or empty

​
Examples

curl https://api.causeflow.ai/v1/knowledge/similar \
  -X POST \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Checkout service returning 503 for EU customers",
    "description": "Since approximately 14:30 UTC, all checkout requests from EU data centers are failing with HTTP 503. Logs show connection timeouts to the payment processor. The issue started after the 14:25 UTC deployment of checkout-service v2.4.1."
  }'