> ## Documentation Index
> Fetch the complete documentation index at: https://docs.factagora.com/llms.txt
> Use this file to discover all available pages before exploring further.

# DeepStamp Detect

> Score content against every stored fingerprint using the watermark and the causal structure.

Detection scores candidate content against every stored fingerprint, using both the hidden watermark and the causal structure of the text. It catches reuse even when every word has been changed.

<Note>
  **DeepStamp is the product name; the API paths still say `fingerprint`.** Endpoints are `/api/v1/fingerprint/embed` and `/api/v1/fingerprint/detect`, and responses return `fingerprint_id`. There is no `/api/v1/deepstamp/*` endpoint.
</Note>

## POST /api/v1/fingerprint/detect

### Request Body

Provide exactly one of `content`, `url`, or `fingerprint_id`. Content and URL queries are extracted on the fly and are never stored.

<ParamField body="content" type="string">
  Raw text to scan, typically the article you want to check. Maximum 50,000 characters.
</ParamField>

<ParamField body="url" type="string">
  URL of the document to scan.
</ParamField>

<ParamField body="fingerprint_id" type="string">
  An already-embedded fingerprint id (`fp_*`) to re-score against the registry. This reuses the stored snapshot instead of re-extracting, which makes it the cheapest option for scheduled monitoring.
</ParamField>

<ParamField body="top_k" type="number" default="5">
  Number of matches to return. Range: 1–50.
</ParamField>

<ParamField body="min_score" type="number" default="0.3">
  Minimum combined score for a candidate to be reported. Candidates with no shared signal at all are always excluded, whatever this value is. `match_found` is true only when at least one match clears both gates.
</ParamField>

<ParamField body="candidate_limit" type="number" default="1000">
  Upper bound on how many stored fingerprints are scanned, newest first. Range: 1–5000.
</ParamField>

<ParamField body="weights" type="object">
  Custom scoring weights. `entity`, `time`, and `causal` must sum to 1.0. When omitted, content-type defaults apply: news `0.5 / 0.2 / 0.3`, legal `0.3 / 0.1 / 0.6`, report `0.4 / 0.3 / 0.3`, internal `0.5 / 0.2 / 0.3`.
</ParamField>

<ParamField body="filters" type="object">
  Restrict which stored fingerprints are considered.

  <Expandable title="Filter fields">
    <ParamField body="author_id" type="string">Only this author's fingerprints</ParamField>
    <ParamField body="date_from" type="string">Inclusive lower bound on `embed_timestamp` (`YYYY-MM-DD`)</ParamField>
    <ParamField body="date_to" type="string">Inclusive upper bound on `embed_timestamp` (`YYYY-MM-DD`)</ParamField>
    <ParamField body="content_type" type="string">Only one content type</ParamField>
  </Expandable>
</ParamField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://api.factagora.com/api/v1/fingerprint/detect" \
    -H "Authorization: Bearer fa_your_api_key" \
    -H "Content-Type: application/json" \
    -d '{
      "content": "ECB hiked rates 25bp Thursday due to stubborn inflation.",
      "top_k": 5,
      "min_score": 0.3
    }'
  ```
</RequestExample>

### Response

<ResponseField name="match_found" type="boolean">
  True when at least one candidate cleared `min_score`.
</ResponseField>

<ResponseField name="confidence_score" type="number">
  The top match's combined score, or `0` when nothing matched.
</ResponseField>

<ResponseField name="query_fingerprint_id" type="string">
  The query's fingerprint id. For `content` and `url` queries this is minted during on-the-fly extraction and is not persisted.
</ResponseField>

<ResponseField name="matches" type="array">
  Top-K candidates, ranked by combined score descending.

  <Expandable title="Match fields">
    <ResponseField name="fingerprint_id" type="string">Matched fingerprint id</ResponseField>
    <ResponseField name="content_type" type="string">Content type recorded at embed time</ResponseField>
    <ResponseField name="metadata" type="object">Metadata stored at embed time, may be null</ResponseField>
    <ResponseField name="embed_timestamp" type="string">When the candidate was fingerprinted</ResponseField>
    <ResponseField name="score" type="number">Weighted combined score</ResponseField>
    <ResponseField name="similarity_breakdown" type="object">Per-signal scores: `entity_match`, `timeseries_match`, `causal_pattern_match`</ResponseField>
    <ResponseField name="overlap" type="object">The shared entities, time anchors, and `from|rel|to` triples behind the score</ResponseField>
    <ResponseField name="watermark_match" type="boolean">True when the input carries a watermark correlating 85% or higher with this candidate. This is near-certain provenance evidence</ResponseField>
    <ResponseField name="watermark_correlation" type="number">Bit-level correlation, null when no watermark was detected</ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="meta" type="object">
  <Expandable title="Meta fields">
    <ResponseField name="scanned" type="number">How many stored fingerprints were scored after filters</ResponseField>
    <ResponseField name="executionTimeMs" type="number">Response time in milliseconds</ResponseField>
    <ResponseField name="weights" type="object">The weights actually applied to this request</ResponseField>
    <ResponseField name="watermark_detected" type="boolean">True when a watermark was found in the input and matched a stored fingerprint</ResponseField>
  </Expandable>
</ResponseField>

<ResponseExample>
  ```json 200 theme={null}
  {
    "match_found": true,
    "confidence_score": 0.87,
    "query_fingerprint_id": "fp_tmpQueryId01",
    "matches": [
      {
        "fingerprint_id": "fp_l1p8OPCwGhvu",
        "content_type": "news",
        "metadata": { "author_id": "editor_jane", "source_id": "article_12345" },
        "embed_timestamp": "2024-06-15T08:01:23.456Z",
        "score": 0.87,
        "similarity_breakdown": {
          "entity_match": 0.92,
          "timeseries_match": 1.0,
          "causal_pattern_match": 0.78
        },
        "overlap": {
          "entities": ["european central bank", "interest rate", "goldman sachs"],
          "timeseries": ["2024-06-15"],
          "relations": ["european central bank|raises|interest rate"]
        },
        "watermark_match": false,
        "watermark_correlation": null
      }
    ],
    "meta": {
      "scanned": 156,
      "executionTimeMs": 342,
      "weights": { "entity": 0.5, "time": 0.2, "causal": 0.3 },
      "watermark_detected": false
    }
  }
  ```
</ResponseExample>

Embedding is covered in [DeepStamp Embed](/api-reference/fingerprint-embed).