RecallsSimilaritySearchResponse

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/deeprecall-io/json-schema/deeprecall-io-recalls-similarity-search-response-schema.json",
  "title": "RecallsSimilaritySearchResponse",
  "description": "Response from the /recalls/search endpoint.\n\nContains similar recalls ranked by relevance score.",
  "x-generated": "2026-11-05",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/deeprecall-io-openapi.json#/components/schemas/RecallsSimilaritySearchResponse",
  "properties": {
    "success": {
      "type": "boolean",
      "title": "Success",
      "description": "Whether the search was successful",
      "default": true
    },
    "matches": {
      "items": {
        "$ref": "#/$defs/SimilaritySearchMatch"
      },
      "type": "array",
      "title": "Matches",
      "description": "List of similar recalls, sorted by score (highest first)",
      "default": []
    },
    "total_matches": {
      "type": "integer",
      "title": "Total Matches",
      "description": "Number of matches returned"
    },
    "model_name": {
      "type": "string",
      "title": "Model Name",
      "description": "Fusion model used for scoring"
    },
    "processing_time_ms": {
      "type": "integer",
      "title": "Processing Time Ms",
      "description": "Search processing time in milliseconds"
    },
    "credits_used": {
      "type": "integer",
      "title": "Credits Used",
      "description": "API credits consumed by this search",
      "default": 1
    },
    "credits_remaining": {
      "type": "integer",
      "title": "Credits Remaining",
      "description": "Your remaining API credits"
    },
    "rate_limit": {
      "anyOf": [
        {
          "$ref": "#/$defs/RateLimitInfo"
        },
        {
          "type": "null"
        }
      ],
      "description": "Rate limit and usage information"
    },
    "data_sources": {
      "anyOf": [
        {
          "$ref": "#/$defs/DataSourceInfo"
        },
        {
          "type": "null"
        }
      ],
      "description": "Data source filtering information"
    },
    "meta": {
      "additionalProperties": true,
      "type": "object",
      "title": "Meta",
      "description": "Additional metadata"
    }
  },
  "type": "object",
  "required": [
    "total_matches",
    "model_name",
    "processing_time_ms",
    "credits_remaining"
  ],
  "$defs": {
    "DataSourceInfo": {
      "properties": {
        "available": {
          "items": {
            "type": "string"
          },
          "type": "array",
          "title": "Available",
          "description": "Data sources available to the user"
        },
        "requested": {
          "items": {
            "type": "string"
          },
          "type": "array",
          "title": "Requested",
          "description": "Data sources requested in this query"
        },
        "filtered": {
          "items": {
            "type": "string"
          },
          "type": "array",
          "title": "Filtered",
          "description": "Data sources actually used (authorized subset)"
        }
      },
      "type": "object",
      "required": [
        "available",
        "requested",
        "filtered"
      ],
      "title": "DataSourceInfo",
      "description": "Information about data sources"
    },
    "RateLimitInfo": {
      "properties": {
        "limits": {
          "additionalProperties": {
            "type": "integer"
          },
          "type": "object",
          "title": "Limits",
          "description": "Rate limits (per_minute, per_hour, per_day)"
        },
        "remaining_credits": {
          "type": "integer",
          "title": "Remaining Credits",
          "description": "Remaining API credits this month"
        },
        "monthly_quota": {
          "anyOf": [
            {
              "type": "integer"
            },
            {
              "type": "null"
            }
          ],
          "title": "Monthly Quota",
          "description": "Monthly request quota (null if unlimited)"
        },
        "monthly_usage": {
          "type": "integer",
          "title": "Monthly Usage",
          "description": "Requests used this month"
        }
      },
      "type": "object",
      "required": [
        "limits",
        "remaining_credits",
        "monthly_usage"
      ],
      "title": "RateLimitInfo",
      "description": "Rate limit information for the user"
    },
    "SimilaritySearchMatch": {
      "properties": {
        "content_hashed": {
          "type": "string",
          "title": "Content Hashed",
          "description": "Unique identifier (content hash) of the matched recall"
        },
        "score": {
          "type": "number",
          "maximum": 1.0,
          "minimum": 0.0,
          "title": "Score",
          "description": "Similarity score (0-1, higher is more similar)"
        },
        "data_source": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Data Source",
          "description": "Data source (e.g., safety_gate, us_cpsc)"
        },
        "source_case_id": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Source Case Id",
          "description": "Original case ID from source agency"
        },
        "alert_title": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Alert Title",
          "description": "Alert title/headline"
        },
        "product_name": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Product Name",
          "description": "Product name"
        },
        "product_brand": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Product Brand",
          "description": "Product brand"
        },
        "product_description": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Product Description",
          "description": "Product description"
        },
        "risk_severity": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Risk Severity",
          "description": "Risk severity level"
        },
        "hazard_description": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Hazard Description",
          "description": "Description of the hazard"
        },
        "images": {
          "anyOf": [
            {
              "items": {
                "type": "string"
              },
              "type": "array"
            },
            {
              "type": "null"
            }
          ],
          "title": "Images",
          "description": "Product image URLs"
        },
        "source_url": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Source Url",
          "description": "URL to original recall notice"
        }
      },
      "type": "object",
      "required": [
        "content_hashed",
        "score"
      ],
      "title": "SimilaritySearchMatch",
      "description": "A single match from similarity search.\n\nRepresents a recalled product that is similar to your query."
    }
  }
}