---
title: Verification — Scholar Sidekick
description: A copy-paste verification kit for Scholar Sidekick — independently verify deterministic output, provenance headers, edge-case behaviour, and the resolver chain. No signup needed.
doc_version: "1.0"
last_updated: "2026-05-04"
---

# Verification — Scholar Sidekick

> Copy-paste curl commands you can run against the live API to verify the determinism, provenance,
> and edge-case claims independently. No signup required.
> Last updated: 2026-05-04
> HTML version: https://scholar-sidekick.com/verification

The trust signals on [/engineering-principles](https://scholar-sidekick.com/engineering-principles)
and [/.well-known/sources.json](https://scholar-sidekick.com/.well-known/sources.json) are
self-declared. This page is the receipts.

Examples below use `10.1038/nphys1170` as a canonical DOI. Substitute any DOI you control. All
commands hit the public anonymous tier.

---

## 1. Reproducibility — same input, same output

Run the same request twice. The response body should be byte-identical, and the
`x-scholar-transform-version` header should match. Pin this value in your tests; if it changes,
treat it as a signal to re-baseline expected output rather than a regression.

```bash
# Run twice, diff the bodies — should be byte-identical.
A=$(curl -sS -X POST https://scholar-sidekick.com/api/format \
  -H "Content-Type: application/json" \
  -d '{"text":"10.1038/nphys1170","style":"vancouver","output":"text"}')
B=$(curl -sS -X POST https://scholar-sidekick.com/api/format \
  -H "Content-Type: application/json" \
  -d '{"text":"10.1038/nphys1170","style":"vancouver","output":"text"}')
diff <(printf '%s' "$A") <(printf '%s' "$B") && echo "OK: identical"
```

Expected: `OK: identical` and a non-empty Vancouver-style citation in both responses.

---

## 2. Single vs batch parity

The same identifier formatted alone or as part of a batch produces the same item-level output.
Batch processing must not silently differ from single processing.

```bash
# Single request
curl -sS -X POST https://scholar-sidekick.com/api/format \
  -H "Content-Type: application/json" \
  -d '{"text":"10.1038/nphys1170","style":"vancouver","output":"json"}' | jq .items[0].formatted

# Same DOI in a batch alongside another identifier
curl -sS -X POST https://scholar-sidekick.com/api/format \
  -H "Content-Type: application/json" \
  -d '{"lines":["10.1038/nphys1170","PMID:30049270"],"style":"vancouver","output":"json"}' | jq .items[0].formatted
```

Expected: the two `items[0].formatted` strings are identical for the DOI under test.

---

## 3. Provenance headers

Every successful response carries a fixed set of provenance headers. Use `curl -i` to print them
and confirm they exist with the documented values.

```bash
curl -i -X POST https://scholar-sidekick.com/api/format \
  -H "Content-Type: application/json" \
  -d '{"text":"10.1038/nphys1170","style":"vancouver","output":"text"}' \
  | grep -iE '^(x-request-id|x-scholar-cache|x-scholar-formatter|x-scholar-style-used|x-scholar-transform-version):'
```

Expected headers (always present on 2xx `/api/format`):

- `x-request-id` — UUID for request correlation
- `x-scholar-cache` — `hit:<key>`, `miss:<key>`, or `bypass:<reason>`
- `x-scholar-transform-version` — date-stamped tag for the active normalisation, formatting, and
  resolver chain

Conditional headers (present only when relevant): `x-scholar-formatter`,
`x-scholar-style-used`, `x-csl-warning`, `x-csl-alias`, `x-csl-dependent`,
`x-csl-fetch-style-id`.

---

## 4. Edge case behaviour

Failure modes follow the contract documented at
[/engineering-principles](https://scholar-sidekick.com/engineering-principles). Each curl below
should return the documented status code and envelope.

### Invalid identifier → 400

```bash
curl -sS -i -X POST https://scholar-sidekick.com/api/format \
  -H "Content-Type: application/json" \
  -d '{"text":"this-is-not-a-doi-or-anything","style":"vancouver"}' \
  | head -n 20
```

Expected: `HTTP/2 400` with body `{ ok: false, code: BAD_REQUEST, error: <message> }`.

### Validates but not found → 200 with empty items

```bash
# Well-formed DOI that doesn't resolve to any record.
curl -sS -X POST https://scholar-sidekick.com/api/format \
  -H "Content-Type: application/json" \
  -d '{"text":"10.9999/this-doi-does-not-exist","style":"vancouver","output":"json"}'
```

Expected: `HTTP/2 200`, no successful item resolved. Not-found results are cached briefly to
avoid hammering the upstream.

---

## 5. Resolver chain

The fallback order per identifier type is published at
[/.well-known/sources.json](https://scholar-sidekick.com/.well-known/sources.json) and validates
against [sources.schema.json](https://scholar-sidekick.com/.well-known/sources.schema.json).
Reordering or substituting resolvers is treated as a transform-version change.

```bash
# Inspect the live resolver chain manifest.
curl -sS https://scholar-sidekick.com/.well-known/sources.json | jq '.resolvers'

# Confirm transform_version field matches the response header.
curl -sS https://scholar-sidekick.com/.well-known/sources.json | jq -r .transform_version
curl -sSI -X POST https://scholar-sidekick.com/api/format \
  -H "Content-Type: application/json" \
  -d '{"text":"10.1038/nphys1170"}' | grep -i x-scholar-transform-version
```

Expected: the `transform_version` in `sources.json` matches the value in the
`x-scholar-transform-version` response header.

---

## 6. OpenAPI contract

The full API surface, schemas, and error semantics are published at the canonical discovery path:

```bash
# Fetch the OpenAPI 3.1 spec at the discovery path.
curl -sS https://scholar-sidekick.com/.well-known/openapi.yaml | head -n 40

# AI plugin manifest (points to the same OpenAPI spec).
curl -sS https://scholar-sidekick.com/.well-known/ai-plugin.json | jq .
```

---

## If something fails

Any verification check that produces unexpected output is a contract violation. File an issue with
the request ID (`x-request-id`) from the offending response, the exact input, and the observed
output. Reproducibility is promised; failure to keep that promise is a bug.

---

## Related

- [Engineering Principles](https://scholar-sidekick.com/engineering-principles)
  ([markdown](https://scholar-sidekick.com/engineering-principles.md)) — the determinism contract,
  edge-case rules, and provenance-header definitions
- [API Docs](https://scholar-sidekick.com/docs)
  ([markdown](https://scholar-sidekick.com/docs.md)) — endpoints, parameters, headers, examples
- [Data source manifest](https://scholar-sidekick.com/.well-known/sources.json)
- [OpenAPI spec](https://scholar-sidekick.com/.well-known/openapi.yaml)
- [JSON Schema for sources.json](https://scholar-sidekick.com/.well-known/sources.schema.json)

---

## Sitemap

See the full [sitemap](https://scholar-sidekick.com/sitemap.md) for all pages.