# StackMap public snapshot API v1

## Selective access for agents

Use the [Node.js query client](query_tools.mjs). For a known tool ID, `--tool`
fetches `lookups/<tool-id>.json` and then the complete evidence pack, validating
its identity, snapshot, byte length and SHA-256. It avoids downloading the
catalog-wide index. A missing lookup is reported as unresolved and unexamined;
it does not establish absence. Add `--legacy-index-fallback` only when you need
the legacy discovery index to distinguish an absent ID.
For discovery, [agent-index.json](agent-index.json) includes product identities,
categories and recorded function keys; `--query`, `--category` and `--function`
filter that index locally.
Function-key matches are leads, not claims of support. Inspect finding state and scope.

With a snapshot that includes the qualification index, `--query` also returns
`documentary_scope_matches` separately from ordinary metadata matches. For example,
`--query "approval tasks"` can find relevant wording in a recorded function's
qualification even when that wording is absent from the product description.
These matches retain the exact finding state, trust, qualification and evidence;
negative, unknown or conditional wording is a research lead, never a positive
feature result or recommendation. This index covers current exported function
qualifications, not arbitrary history, all plan notes or the world's software.
The client reports unavailable scope search on older snapshots separately from
an empty search. Named-tool lookup remains the direct route when the ID is known.

```sh
node query_tools.mjs https://stackmap.stuckinadream.xyz/ui/api/v1/ --tool zoho-crm
node query_tools.mjs https://stackmap.stuckinadream.xyz/ui/api/v1/ --tool zoho-crm --tool n8n
node query_tools.mjs https://stackmap.stuckinadream.xyz/ui/api/v1/ --category workflow_automation --function self_host --limit 3
```

### Exact-version research

The full named-tool pack carries exact source-scoped version observations when
available. For example, retrieve the OpenShot pack and select its recorded
`2.4.1` scope:

```sh
node query_tools.mjs https://stackmap.stuckinadream.xyz/ui/api/v1/ --tool openshot | jq '.packs[0].version_research.versions["2.4.1"]'
```

Version labels identify the scope recorded by their sources; they do not mean
current or latest version, a release range, or installed software. The function
`--view matrix` compares the current snapshot's function findings and is not
version-scoped. Each version row keeps its own state, including `unexamined`.
`version_research` is also separate from
`tool_contexts[].product_change_packet` and the `--view changes` product-change
lane. Check `packs[].version_research.status`: `no_public_version_observations`
means no public version rows are available for that tool, while
`unavailable_legacy` means the snapshot predates this projection. Neither status
means a feature or product is absent. When a version is present, inspect its
source excerpts, dates, and qualifications; no unversioned finding or
recommendation eligibility is inherited.

Search executes locally; this is a fixed public snapshot, not hosted server-side search.
Pack URLs and hashes are listed in both the exact-tool lookup and discovery index.
Clients report HTTP response bytes and request counts; those are not model tokens
or measured decision time. Lookups retain the same complete evidence packs.
Repeat `--tool` to retrieve one through ten complete named-tool packs without
constructing a function comparison matrix. Each selected lookup and pack must
bind to the same snapshot; duplicate IDs and more than ten IDs are rejected.
An ID confirmed absent through the explicit legacy fallback is listed in
`missing_tools`; it is unexamined, not incompatible. A default lookup 404 is
listed in `unresolved_lookup_ids` and does not claim absence.
Use `--view context` with one or more named tools to retrieve a compact selected
decision context without duplicating complete packs:

```sh
node query_tools.mjs https://stackmap.stuckinadream.xyz/ui/api/v1/ --tool zoho-crm --tool n8n --view context
```

Use `--view connections` with two through ten named tools for direct relationships
within that selection, retaining the full directed edge and its source evidence once:

```sh
node query_tools.mjs https://stackmap.stuckinadream.xyz/ui/api/v1/ --tool cal-com --tool google-calendar --view connections
```

`connection_review.pairs` distinguishes recorded relationships, no recorded direct
relationship, and unresolved endpoint lookups. Missing edges are research gaps,
not incompatibility. `connections` preserves direction, status, qualifiers and
missing evidence references; `outside_selection_edge_ids` names omitted incident
edges. It does not infer an indirect path, plan eligibility or runtime success.
Duplicate records must agree across packs. This filters output locally and uses
the same complete packs and network calls; it is not a measured agent-time saving.

Attach an explicit need to the same relationship artifact:

```sh
node query_tools.mjs https://stackmap.stuckinadream.xyz/ui/api/v1/ --tool quickbooks-online --tool zoho-crm --view connections --declared-requirement 'INV-1=Do not roll out unless invoices sync in both directions'
```

The declaration is user context, not source evidence or a compatibility verdict.
Inspect each directed record's supported modules and exclusions: two edges in
opposite directions do not establish bidirectional support for every operation.
Missing records and unresolved lookups remain unknown. Check current entitlement,
configuration and runtime separately before acting.

Named packs and `tool_contexts[].product_change_packet` also retain current
public product-change records, when present in the snapshot. For example, select
`--tool vector --view context` to inspect recorded version changes. Effective,
source-published, observed and recorded dates remain separate. Source links and
qualifications travel with each record. An empty `changes` array with
`coverage_complete: false` means no retained change in this snapshot, not proof
that no change occurred. Named selection does not establish relevance to a
customer requirement, configured exposure or successful migration.

Current product-change rows also carry `record_revision`, which describes
StackMap's record lineage, not a publisher correction or product release:
`stackmap_record_correction` includes `supersedes_event_id` only when the
predecessor is publicly referenceable; otherwise its classification is kept
with a withheld reference. `no_supersession_recorded` means no correction link
was recorded for that row. Legacy rows without lineage metadata are marked
`unknown`. Private or mixed rows do not expose revision lineage.

To carry an explicit requirement into that review, add up to sixteen unique
`--declared-requirement ID=TEXT` arguments with named tools and `--view context`:

```sh
node query_tools.mjs https://stackmap.stuckinadream.xyz/ui/api/v1/ --tool vector --view context --declared-requirement 'OBS-1=Keep existing GraphQL clients for Vector top and tap'
```

The client returns your declarations separately in `declared_context`, with
references to selected change packets and open review questions. Declarations
stay in the local client output; they are not sent in HTTP requests. This carries
review context without deciding that a change affects the requirement.

For a bounded review of newly recorded evidence, use an explicit UTC recording boundary:

```sh
node query_tools.mjs https://stackmap.stuckinadream.xyz/ui/api/v1/ --tool vector --view changes --recorded-since 2026-09-01T00:00:00Z --declared-requirement 'OBS-1=Keep existing GraphQL clients for Vector top and tap'
```

`change_windows` selects records strictly after that StackMap recording time and
through the snapshot's known-at time. Original rows, source URLs, qualifications
and distinct dates are preserved. Source publication before the window is labeled
separately, so newly discovered older release notes do not become new releases.
Unplaceable recording dates stay visible. Empty, unavailable and unresolved
results differ; none proves an absence of product changes. Declarations stay
local and do not establish relevance. The window uses the fixed snapshot, not
live monitoring; it retains current records, not a complete correction audit.
With declared requirements, `declared_context.change_window_review` summarizes
the selected window, its packet cutoff, excluded earlier records, unplaced dates
and unresolved tools. Review prompts refer only to returned records. An empty
window is not evidence that the software did not change; a missing lookup is not
evidence that a product is absent. Full source records remain in `change_windows`.
The compact view fetches the same hash-verified packs and does not reduce network
requests; it omits unrelated decision context from the client output.

### Carry your own consequence review between an agent and the human view

With declared requirements, a changes response includes an unauthored
`review_template`. Save `review_template.packet` as a local JSON file. Keep its
binding unchanged, enter a named human or agent author, and add dispositions for
the needs you reviewed. Each disposition supplies `requirement_id`, selected
`tool_ids`, `event_refs` (`tool_id` and `event_id`), `conditional_consequence`,
`exposure_conditions`, `next_action`, and `unknowns`. Conditions and unknowns are
nonempty arrays of text. Refer only to selected in-window events. Empty references
can describe unresolved evidence; they cannot establish that a need is unaffected.
Omitted requirements stay explicitly unreviewed.

```sh
node query_tools.mjs https://stackmap.stuckinadream.xyz/ui/api/v1/ --tool vector --view changes --recorded-since 2026-09-01T00:00:00Z --declared-requirement 'OBS-1=Keep existing GraphQL clients for Vector top and tap' > changes.json
node query_tools.mjs https://stackmap.stuckinadream.xyz/ui/api/v1/ --tool vector --view changes --recorded-since 2026-09-01T00:00:00Z --declared-requirement 'OBS-1=Keep existing GraphQL clients for Vector top and tap' --review-packet review.json > reviewed.json
```

The binding checks the exact snapshot, window, declared needs, selected tool IDs,
event references and pack descriptors. A later public snapshot needs a new review;
the client refuses to carry an old review forward silently. The single downloaded
client includes the shared validator and adds no requests for a review file.
`authored_review` is separate from retained source records. Validation checks its
binding and structure, not the correctness of its prose or real-world exposure.
Record corrections remain corrections; late discovery does not become a new
release; empty or unavailable evidence does not establish no impact.

In **Connect your agent → Review changes against your own needs**, import
`changes.json` and optionally `review.json`, or import `reviewed.json` directly.
You can write a partial review, inspect the referenced records, and download both
the authored packet and combined response. Imports stay in page memory with no
upload or browser persistence. Local JSON is not independently authenticated
against the public site. These authored needs and conclusions never enter the
public catalog or change recommendation eligibility.

### Worked change review: one upgrade, three different answers

Open [the Vector review example](change-review-example.json) for a retained,
authored review of three synthetic needs: keep GraphQL observability clients,
keep HTTP health probes, and retain OTLP ingestion compatibility. The source
notice supports a migration review for the first, an unchanged-endpoint publisher
claim for the second, and no ingestion conclusion for the third. Each disposition
keeps conditional actions, exposure questions, source links and separate clocks.
This example uses its explicitly dated retained snapshot; it is not recalculated
against each API release, an automatic relevance verdict, or a tested deployment.
Retrieve the actual selected evidence for your agent's own review:

```sh
node query_tools.mjs https://stackmap.stuckinadream.xyz/ui/api/v1/ --tool vector --view changes --recorded-since 2026-09-01T00:00:00Z --declared-requirement 'OBS-1=Keep existing GraphQL clients for Vector top and tap' --declared-requirement 'HEALTH-1=Keep HTTP health probes' --declared-requirement 'INGEST-1=Keep OTLP ingestion compatibility'
```

The client returns evidence and open questions. An agent or person must review
the conditional consequence; it must not interpret a missing ingestion claim as
compatibility or incompatibility. The example's synthetic needs are not a real
customer's configuration or proof of saved time.

Documentary cost models retain optional `eligibility_rules` with exact units,
scopes and source quotes. These are recorded rules, not an eligibility verdict.
A nonzero `eligibility_rules_withheld_count` means some rules could not be
publicly exposed; missing rules do not establish an unlimited or eligible plan.

This view includes `tool_contexts[].documentary_reviews` unchanged, including
candidate, contrary, accepted and unknown states. It includes every directed
catalog operation at `tool_contexts[].directed_operations[].edge`; its
`evidence_records` joins retained source records, while
`unresolved_evidence_refs` remains explicit. `pack_descriptors` retain each full
pack URL, SHA-256 and byte length. Context is selected decision context, not a
complete function inventory: inspect the default full `packs` for all findings,
evidence records and retained fields. Omitted context fields are unexamined here,
not unsupported. These are documentary records, not configured integrations or
runtime proof.
Your own agent performs broader reasoning, follows missing research and retains uncertainty.
Rebuild packs with `scripts/build_agent_packs.py` whenever the base API is regenerated.


Read-only static JSON files expose the same public catalog snapshot used by the Atlas. For full endpoint access, fetch `index.json`; it gives endpoint URLs, SHA-256 digests, schema, counts, source revision, export evaluation date and fixed public snapshot label. No API key is needed. No server-side search, mutation, streaming, live AI reasoning or historical query is implemented. Cross-origin browser access is not promised; CLI/server clients can fetch the public JSON. Same-origin pages can use fetch.

- `catalog.json`: tools and capability categories, including pricing unknowns and qualifications. Optional per-tool license_facts come from an explicitly supplied documentary sidecar, independently of pricing_model; its input hash and observation-time scope appear in license_facts_metadata. A no-charge license grant does not price hosting, support or operations. Raw recorded licenses remain available even without a sidecar.
- `functions.json`: vocabulary, definitions and assertion rows with source references, qualifications, recorded trust and active/superseded status. Current sub_capabilities and retained function_assertion_history rows are both included, with record_scope identifying their origin; history rows are always nonactive. Source-bound documentary reviews are separate from accepted assertions: a function candidate binds to one current accepted assertion, while a tool-level note keeps its function fields null. `documentary_entitlements` are separately typed, source-bound product statements; they do not establish free/core entitlement, a price or plan, runtime behavior, or trust. Neither documentary lane promotes trust, proves runtime behavior, or recommends a tool. This is retained assertion history only, not full journal access or historical query support. Multiple active observations can conflict. A missing row is unexamined, not unsupported. Recorded confidence summaries describe imported evidence coverage, not a score or guarantee.
- `integrations.json`: directed catalog relationships. Preserve source_tool_id, target_tool_id, direction, interaction_type, status and notes. An optional `record_revision` identifies a StackMap record wording correction and its recording time; it does not indicate a publisher or software change. The field is emitted only when the correction matches the edge's full immutable identity and its evidence remains public. An edge is not a runtime integration test and does not establish a reverse edge or universal interoperability.
- `evidence.json`: public evidence IDs, publisher URLs, capture dates and source notes. These describe retained evidence, not a new live validation.
- `decisions.json`: recorded workloads, qualified documentary cost models, and separately source-bound operational plan limits. A plan limit retains its unit, edition, billing scope, qualification, and source binding; it is not a base-license capacity constraint, deployment fact, runtime test, or complete-workload result. Optional example results are retained demonstrations with their own provenance, not newly computed answers against this API snapshot. Examples can use an older snapshot. None establishes full TCO or a verified recommendation.

`known_at` is a fixed public label. `export_evaluation_date` is the export evaluation date, not a feature-effective date or knowledge-time replay. `source_revision` may precede local data changes: its relationship to the input SHA-256 is stated, without pretending that revision alone proves the input bytes. Costs retain currency, period, dimensions, constraints and exclusions. Do not combine annual/monthly amounts or different scope units without explicit calculation.

## Compare products against several functions

Use one command to retrieve named candidates and build a complete function matrix:

```sh
node query_tools.mjs https://stackmap.stuckinadream.xyz/ui/api/v1/ \
  --tool n8n --tool wexflow --tool windmill --category workflow_automation \
  --functions visual_builder,webhooks,branching_logic,code_steps,scheduling,human_in_the_loop
```

This requests 18 cells: three tools by six recorded function keys. Each cell keeps
its accepted findings, dates, qualifications, source records and unresolved
references. Documentary candidate reviews remain separate and do not change the
accepted state. Missing, unknown and conflicting evidence stays visible.
Deployment, license, edition and recorded limits remain separate context.

The keys are catalog questions, not an automatic interpretation of your full
business requirement. For example, `code_steps` support alone does not establish
Python support in a particular edition. Your agent must inspect the returned
scope and research any missing qualification. This is an evidence matrix, not a
ranking, novelty verdict, equivalence claim or functional service test.

Use 1–10 named tools and 1–20 unique function keys. All selected packs must have
the same snapshot; changed or mismatched hashes fail the request. The output also
retains the complete selected packs by default. Add `--view matrix` to keep the
requested findings, source records, qualifications, unknown references and tool
contexts without repeating the full packs. Validated `pack_descriptors` retain
each complete pack’s relative URL, SHA-256 and byte length for deeper retrieval.
This changes output size only; the client still downloads and validates the same
packs. No model-token, reasoning-time or quality improvement is implied.

## Client-side queries

For named products, use `python example_client.py https://YOUR-HOST/ui/api/v1/ --tool zoho-crm --tool n8n`. It fetches each compact lookup and its hash-checked evidence pack, including source evidence, recorded costs, operational plan limits and incident directed edges. This is the default named-tool path and does not download the catalog-wide bulk endpoints. Use `--category`, `--function`, `--name` and `--integrations` to filter the selected packs. Use `--bulk` only when you explicitly need the legacy full-snapshot response shape or an older snapshot has no compact lookup. The script filters active rows and preserves all current states, including unknown and unsupported; it never silently turns documentary support into suitability.

Join assertions to tools by tool_id, and evidence_refs to records by evidence_id. Group active assertions by (tool_id,capability_slug,key); differing states mean conflicting observations. Evaluate every required function and its qualifications. Missing required facts stay unknown. For a stack decision, inspect each directional edge and each component independently; path reachability alone is insufficient.

The client identifies itself as StackMapSnapshotClient/1.0 and requests application/json. TLS certificate verification stays enabled. If Python reports a certificate verification error, configure the trusted CA certificates for that Python installation; do not disable TLS verification.

## Privacy and generation

Generated only from the allowlisted public UI snapshot, with optional public demonstration JSON. No bookmark database, raw history journal, credentials, capture logs, private/mixed evidence payloads, operator-local runtime executable paths or repository directory copies. Public documentation examples of generic filesystem paths remain source text, not execution receipts. Sensitive material in a projected field fails generation instead of dropping a potentially material qualification. Raw confidence observations are excluded; only coverage/count summaries are exported. Input SHA-256 and each endpoint SHA-256 support reproducibility. Regenerate after accepting and exporting new catalog data.

## Assess a brief with your agent

Download `review_brief.mjs` and run it with Node.js 20 or later:

```sh
node review_brief.mjs https://YOUR-HOST/ui/api/v1/ \
  'Assess Zoho CRM for 10 users; 300 sales mass emails per organization per day; $400/month for ordinary licenses.'
```

Change $400 to $200 and rerun. The client uses the same deterministic matching and bounded plan evaluator as the browser. It verifies all five downloaded dataset hashes and common snapshot identity before assessing. It never downloads executable code. The brief is processed locally and is not sent in the network requests. The output contains role findings, source records, integration direction, unresolved constraints and qualified plan checks. Ordinary-seat month-to-month Zoho CRM Standard and Professional are the current supported price/eligibility calculation; other tools retain unknown cost. These observations are not live prices or whole-stack TCO.

Generic “sales emails” does not establish mass-email scope. State the organization/day unit explicitly or inspect the unresolved email check. A candidate for each role does not establish a suitable or connected stack. The browser is not hosted AI; supply this output to your own agent for conversation and further research. No claim of superiority over another AI product follows from these examples.
