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

# Analyze cigar-band evidence

> Use band appearance to discriminate among plausible cigar candidates.

Use band analysis after fingerprinting when two or more candidates remain plausible. It compares the observed band palette and color roles with stored candidate fingerprints. It does not perform a general catalog search.

<ParamField header="x-boxpressd-key" type="string" required>
  Your developer application key with the `api.ai` entitlement.
</ParamField>

<ParamField header="Idempotency-Key" type="string" required>
  A unique key for this credit-gated operation.
</ParamField>

<ParamField body="fingerprint" type="object" required>
  The complete object returned by the fingerprint endpoint.
</ParamField>

<ParamField body="candidates" type="object[]" required>
  From 1 through 20 plausible candidates. Each candidate requires `cigarId` and can include `brand`, `name`, `score`, and prior evidence.
</ParamField>

<ParamField body="expandSameBrand" type="boolean">
  Search a bounded set of stored fingerprints from the supplied brand when none of the supplied candidates has a credible color match.
</ParamField>

```javascript theme={null}
const response = await fetch(
  "https://api.boxpressd.com/v1/ai/cigars/band/analyze",
  {
    method: "POST",
    headers: {
      "x-boxpressd-key": process.env.BOXPRESSD_DEVELOPER_API_KEY,
      "Idempotency-Key": crypto.randomUUID(),
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      fingerprint,
      candidates: [
        {
          cigarId: 101,
          brand: "Diesel",
          name: "Unlimited",
          score: 0.78,
        },
        {
          cigarId: 102,
          brand: "Diesel",
          name: "Wicked",
          score: 0.76,
        },
      ],
      expandSameBrand: true,
    }),
  },
);

const bandAnalysis = await response.json();
```

Fewer than two usable stored candidate fingerprints can return `reference_fingerprints_pending`. A strong conflict can return `candidateSetMatch: false` without inventing a replacement candidate.

Pass the complete response to Identify as `stageResults.bandAnalysis`. Visible printed cigar-name text remains stronger evidence when it conflicts with palette analysis.