# Pre-flight: is there a record for this?

Pre-flight is one keyless GET that answers whether Rightshold holds a record for the thing you are about to rely on: a resource-scan receipt for a public artifact URL, or a KYA record for an agent named by handle, registration number or agent id. It is built to sit inside install scripts, CI steps and agent bootstraps: one call, no key, no body, and a well-formed miss answers 200 with found:false, so a script can branch on the answer without treating absence as an error. The answer is evidence, never a verdict: it names the record that is on file (for a receipt, the SHA-256 of the exact bytes scanned, the summary and the ledger sequence; for an agent, the KYA level and the registration facts) — or states that no record is on file, which is a fact about the record and not a finding about the artifact or the agent. A flagged scan is facts to read before installing, not a ban; no record at all is the state the verify-before-install rule treats as stop-and-surface: scan the artifact (POST /v1/resource-scans) or ask for the agent's registration, then read what comes back.

Pre-flight reads only records that already exist. It runs no scan, no probe and no check of its own, and it changes nothing: a receipt appears only through POST /v1/resource-scans, and a KYA record only through the public registration flow.

## The two lookups

Scan receipt for an artifact URL:

    curl -s "https://www.rightshold.com/v1/preflight?url=https://raw.githubusercontent.com/anthropics/skills/main/skills/docx/SKILL.md"

KYA record for an agent (handle, registration number or agent id):

    curl -s "https://www.rightshold.com/v1/preflight?agent=mews"

One call answers one lookup: send exactly one of url or agent. A call with neither, or with both, answers 422 naming the problem, as does a url that is not a public https URL.

## Reading the answer

- found:true with a scan_receipt — a receipt is on file: the artifact id, the receipt count, the version count (distinct SHA-256 hashes seen at the URL), and the latest receipt's hash, summary and ledger sequence, with the receipt's own URL for the full findings.
- found:true with a kya record — a public agent record is on file: the handle, the KYA level and its name, whether the agent's key is verified, and the registration number, status, classes and expiry when a registration is on file.
- found:false — no record is on file under that URL or name. The answer says so in those words and names the public flow that puts a record on file. Absence is a fact about the record, never a finding about the artifact or the agent.

## In an install script

```sh
# verify-before-install, pre-flight form: stop when no record is on file
resp=$(curl -s "https://www.rightshold.com/v1/preflight?url=$ARTIFACT_URL")
found=$(printf '%s' "$resp" | python3 -c 'import json,sys; print(json.load(sys.stdin)["found"])')
if [ "$found" != "True" ]; then
  echo "no scan receipt on file for $ARTIFACT_URL — scan it first:" >&2
  echo "POST https://www.rightshold.com/v1/resource-scans" >&2
  exit 1
fi
```

## In CI

```yaml
# CI step (any runner): fail the job when the agent has no KYA record on file
- run: |
    curl -s "https://www.rightshold.com/v1/preflight?agent=$AGENT_HANDLE" \
      | python3 -c 'import json,sys; d=json.load(sys.stdin); sys.exit(0 if d["found"] else 1)'
```

Machine form: https://www.rightshold.com/v1/preflight · The receipts themselves: https://www.rightshold.com/v1/resource-scans · The KYA records themselves: https://www.rightshold.com/v1/kya/{handle} · The rule this serves: verify before installing — a receipt or a KYA record on file first, and the findings read, before anything new is relied on.