Goatlab Tools LogoGoatlab Tools API Docs

Extract citations (v2)

Splits the answer into statements and returns, for each one, every source citation that backs it.

It accepts exactly the same request body and query parameters as POST /v1/citations, and runs the same three-tier matching strategy (exact → case-insensitive → fuzzy) with the same fuzzyThreshold, model, matcher toggles and splitting options. Only the shape of the response differs.

Statements: A statement is one chunk of the answer as produced by answer_splitting (sentences by default). Statements are returned in answer order, with their start and end position in the original answer. Only statements backed by at least one citation are returned; statements no source backs are left out, so the response can be empty. Text the splitter excludes (for example headings and tables with answer_splitting=statements) is not a statement and never appears.

Citations per statement: Where v1 keeps only the single best source for each chunk, v2 lists every source that passes: a source is cited if it matches literally (exact or case-insensitive), or otherwise if its fuzzy similarity is at least fuzzyThreshold. Each source appears at most once per statement, with its strongest match.

Citations are ordered strongest first: by tier (exact > case-insensitive > fuzzy), then by fuzzy_score, then by the length of the matched text. Each citation has the same fields as in v1, so a literal match can cover only part of its statement.

Cost: Since every source is checked for every statement, embeddings are computed whenever at least one source has no literal match for a statement, which is nearly always when several sources are sent.

Overlapping statements: With answer_splitting=recursive and a non-zero answer_recursive_overlap, consecutive statements share text, and they are returned as they are.

POST
/v2/citations

Authorization

ApiTokenAuth
x-api-key<token>

API Key with role based permission

In: header

Scope:

Query Parameters

fuzzyThreshold?number

Similarity threshold for fuzzy matching (0-1). Higher values require closer semantic matches. Default is 0.35.

Default0.35
Range0 <= value <= 1
model?string

Embedding model used for the fuzzy (semantic) matching tier.

  • titan: Amazon Titan Text Embeddings V2 (default)
  • cohere: Cohere's embedding V4
Default"titan"
Value in"titan" | "cohere"
exact_matching?boolean

Whether the exact matching tier runs. Enabled by default. Disabling it does not widen or narrow what is found when caseless_matching is on — caseless matching finds everything exact matching finds — but citations that were verbatim are then reported as exact_case_insensitive.

Defaulttrue
caseless_matching?boolean

Whether the case-insensitive matching tier runs. Disabled by default, because it matches everything the exact tier matches and only adds case variants, at roughly ten times the cost. Enable it when the answer may differ from the sources only by casing.

With both tiers disabled every chunk falls through to fuzzy matching, which means an embedding call per answer chunk and per source.

Defaultfalse
answer_splitting?string

Text splitting strategy used to chunk the answer.

  • sentences: sentence-based splitting (default)
  • recursive: LangChain recursive character splitting following markdown structure (headings, paragraphs, lists)
  • statements: markdown-aware splitting into citable statements (answer only, see below)
Default"sentences"
Value in"sentences" | "recursive" | "statements"
sources_splitting?string

Text splitting strategy used to chunk the source contents.

  • sentences: sentence-based splitting (default)
  • recursive: LangChain recursive character splitting following markdown structure (headings, paragraphs, lists)

statements is not accepted here — sources are documents and are never split into statements.

Default"sentences"
Value in"sentences" | "recursive"
answer_recursive_chunk_size?integer

Maximum chunk size in characters when answer_splitting is recursive. Ignored for the other strategies. Default is 500.

Default500
Range1 <= value <= 5000
sources_recursive_chunk_size?integer

Maximum chunk size in characters when sources_splitting is recursive. Ignored for the other strategies. Default is 500.

Default500
Range1 <= value <= 5000
answer_recursive_overlap?number

Overlap between consecutive answer chunks when answer_splitting is recursive, as a ratio of the chunk size (0 inclusive to 1 exclusive). Ignored for the other strategies. Default is 0.1 (10% of the chunk size).

Default0.1
Range0 <= value < 1
sources_recursive_overlap?number

Overlap between consecutive source chunks when sources_splitting is recursive, as a ratio of the chunk size (0 inclusive to 1 exclusive). Ignored for the other strategies. Default is 0.1 (10% of the chunk size).

Default0.1
Range0 <= value < 1

Request Body

application/json

The answer text and list of sources to match against it

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/json

application/json

application/json

curl -X POST "https://tools.dev.files.haufe.io/v2/citations" \  -H "Content-Type: application/json" \  -d '{    "answer": "Paris is the capital of France. The Eiffel Tower is one of the most visited monuments in the world. It attracts millions of visitors every year.",    "sources": [      {        "source_id": "src-1",        "content": "Paris is the capital of France.",        "metadata": {          "type": "NUVIO_PERSONAL",          "spaceId": "space-1",          "fileId": "file-1",          "chunkId": "chunk-1"        }      },      {        "source_id": "src-2",        "content": "the eiffel tower is one of the most visited monuments in the world.",        "metadata": {          "type": "NUVIO_SPACE",          "spaceId": "space-2",          "fileId": "file-2",          "chunkId": "chunk-2"        }      },      {        "source_id": "src-3",        "content": "Millions of tourists visit the tower annually",        "metadata": {          "type": "IDESK",          "spaceId": "space-3",          "fileId": "file-3",          "chunkId": "chunk-3"        }      }    ]  }'
{
  "statements": [
    {
      "start": 0,
      "end": 31,
      "citations": [
        {
          "start": 0,
          "end": 31,
          "source_start": 0,
          "source_end": 31,
          "text": "Paris is the capital of France.",
          "source_text": "Paris is the capital of France.",
          "source_id": "src-1",
          "match_type": "exact",
          "fuzzy_score": null
        }
      ]
    },
    {
      "start": 32,
      "end": 99,
      "citations": [
        {
          "start": 32,
          "end": 99,
          "source_start": 0,
          "source_end": 67,
          "text": "The Eiffel Tower is one of the most visited monuments in the world.",
          "source_text": "the eiffel tower is one of the most visited monuments in the world.",
          "source_id": "src-2",
          "match_type": "exact_case_insensitive",
          "fuzzy_score": null
        },
        {
          "start": 32,
          "end": 99,
          "source_start": 0,
          "source_end": 45,
          "text": "The Eiffel Tower is one of the most visited monuments in the world.",
          "source_text": "Millions of tourists visit the tower annually",
          "source_id": "src-3",
          "match_type": "fuzzy",
          "fuzzy_score": 0.61
        }
      ]
    },
    {
      "start": 100,
      "end": 144,
      "citations": [
        {
          "start": 100,
          "end": 144,
          "source_start": 0,
          "source_end": 45,
          "text": "It attracts millions of visitors every year.",
          "source_text": "Millions of tourists visit the tower annually",
          "source_id": "src-3",
          "match_type": "fuzzy",
          "fuzzy_score": 0.82
        }
      ]
    }
  ]
}

{
  "message": "Validation error: answer is required"
}

{
  "message": "Invalid API Key"
}
{
  "message": "Internal Server Error"
}