Did it work?For AI agents & developers

Technical reference. Written for analysts and AI agents and kept in sync with the repository, so it uses internal terms. Raw Markdown: /pages/how-to-query.md.

How to query Better World (agents)

Product version: 0.2.15 (VERSION). Cite provenance.product_version / GET /v1/meta/snapshot (incl. claims_index_fingerprint) when quoting rankings. CI 46/46 at freeze (live 47/47 with outcomes_adversarial); tarball sha256 6deb191390f8c359dc611b4ab3fc8e6f0c527f89739725817603063f1a2a725d; 90 research QA passes at freeze / live disk 92 (Wave GS + post-cut GW/GY; Wave ES markers match disk); ADR 0007 remains Proposed; mixes_units_in_ranking: false.

Quick path

bash
# List / get
curl -s http://127.0.0.1:8787/v1/orgs | head
curl -s http://127.0.0.1:8787/v1/orgs/org_against_malaria_foundation

# Meta / audit snapshot (Wave CE/DD — cite product_version + data_snapshot_id + claims_index_fingerprint)
curl -s http://127.0.0.1:8787/v1/meta
curl -s http://127.0.0.1:8787/v1/meta/snapshot

# Phase 2 — recommend (preferred for "best charity for X")
# Prefer values_profile_id; response includes values_filtering + exclusions[]; RFMF may appear on orgs
curl -s 'http://127.0.0.1:8787/v1/recommend?values_profile_id=vp_lives_no_deworm&limit=8'
curl -s 'http://127.0.0.1:8787/v1/recommend?outcome=lives_saved'
curl -s 'http://127.0.0.1:8787/v1/recommend?outcome=wellbeing_wellbys&risk=low'
curl -s 'http://127.0.0.1:8787/v1/recommend?outcome=income&budget_usd=500'
curl -s 'http://127.0.0.1:8787/v1/recommend?outcome=lives_saved&tax=us_501c3_preferred&risk=low&budget_usd=25000'

# Compare / outcomes catalog
curl -s 'http://127.0.0.1:8787/v1/compare?ids=org_against_malaria_foundation,org_malaria_consortium'
curl -s http://127.0.0.1:8787/v1/outcomes

# Phase 1 search (heuristic; prefer /v1/recommend for ranking)
curl -s 'http://127.0.0.1:8787/v1/search?intent=best+charity+to+save+lives'
curl -s 'http://127.0.0.1:8787/v1/search?outcome=wellbeing_wellbys'

# Trust
curl -s http://127.0.0.1:8787/v1/trust/org_strongminds

# Modeled impact (NOT guaranteed)
curl -s 'http://127.0.0.1:8787/v1/impact-estimate?org_id=org_against_malaria_foundation&gift_usd=1000'

# Leaderboards (per family; ADR 0007 Proposed; mixes_units_in_ranking:false)
curl -s http://127.0.0.1:8787/v1/leaderboards
curl -s 'http://127.0.0.1:8787/v1/leaderboards?outcome=lives_saved'

# Tax summary (assert_personal_deductibility always false)
curl -s http://127.0.0.1:8787/v1/tax/org_against_malaria_foundation

# Review queue (read-only; no write/approve)
curl -s http://127.0.0.1:8787/v1/review/queue
curl -s 'http://127.0.0.1:8787/v1/review/queue?status=all'

# Claims index (Wave CR/DP/EF — index-only; never invent CE;
# Python list_claims/get_claim · TS listClaims/getClaim · MCP list_claims/get_claim)
curl -s http://127.0.0.1:8787/v1/claims
curl -s 'http://127.0.0.1:8787/v1/claims?org_id=org_against_malaria_foundation&verified=true'
curl -s http://127.0.0.1:8787/v1/claims/eval_gw_amf__0

# Giving intent (NO charge; charge/charges false; donate URL sanitized)
curl -s 'http://127.0.0.1:8787/v1/giving/intent?org_id=org_against_malaria_foundation&amount_usd=100&vehicle=direct_cash'

Client parity (API up)::

python
from better_world_client import BetterWorldClient
bw = BetterWorldClient.from_api("http://127.0.0.1:8787")
print(bw.list_claims(org_id="org_against_malaria_foundation", verified=True)["count"])
print(bw.get_claim("eval_gw_amf__0")["claim"]["claim_id"])
js
import { createClient } from "../../clients/typescript/src/index.js";
const bw = createClient();
const listed = await bw.listClaims({ org_id: "org_against_malaria_foundation", verified: true });
const one = await bw.getClaim("eval_gw_amf__0");

Without the server, import ranking directly:

bash
python3 -c "import sys; sys.path.insert(0,'scripts'); from rank import recommend; import json; print(json.dumps(recommend('lives_saved', limit=5), indent=2))"

Or read JSON under data/ — including data/ranking/leaderboards.json.

Decision tree

  1. User outcome = save lives → GET /v1/recommend?outcome=lives_saved → GiveWell Top Charities (Helen Keller, Malaria Consortium, New Incentives, AMF) and/or Top Charities Fund.
  2. User outcome = happiness / wellbeing → outcome=wellbeing_wellbys → StrongMinds / Friendship Bench (Top); Pure Earth / Taimaka (Promising — higher uncertainty).
  3. User wants cash / income benchmark → outcome=income → GiveDirectly (benchmark) plus deworming former-tops with caveats.
  4. Always cite URLs from citations[] / record sources; surface caveats[] and trust flags.
  5. Never invent CE numbers — only repeat verified_claims values from our data.
  6. Parallel boards → GET /v1/leaderboards (do not mix units; ADR 0007 Proposed; mixes_units_in_ranking: false).
  7. Tax language → GET /v1/tax/{id} first; assert_personal_deductibility always false.
  8. Ready to give → GET /v1/giving/intent (no charge); never invent donate URLs / crypto addresses.
  9. Cite catalog identity → GET /v1/meta or /v1/meta/snapshot (product_version, claims_index_fingerprint, adr_0007_status stays Proposed until Ho Hum Accept).
  10. Research / pending gates → public/pages/decision-desk.md + cause-research.md (92 packs with QA passes on live disk; 90 at 0.2.15 cut / prior 83 at 0.2.14; 78 at 0.2.13; not a ranking; ADR 0007 Proposed).
  11. Cite a flat claim → GET /v1/claims or GET /v1/claims/{id} (or Python/TS list_claims/get_claim · listClaims/getClaim · MCP list_claims/get_claim; index copy only; never invent CE).

Values-profile query params

Map schema/values_profile.schema.json fields onto /v1/recommend. Prefer binding a preset id:

Profile field Query param
(preset id) values_profile_id (vp_* from GET /v1/values-profiles)
outcome_preference outcome or outcome_preference
budget_usd budget_usd
risk risk
geography geography
require_geography require_geography
tax tax
red_lines red_lines (comma-separated)
non_cash.prefer_orgs_with_options non_cash=true

Example profile: data/examples/values_profile.example.json. Named presets (static catalog): data/values_profiles/ / public/demo/values_profiles.json — see docs/values-discernment.md. When a preset is bound, surface values_filtering / exclusions[]. RFMF on org payloads: unknown ≠ no room (api/FUNGIBILITY_INTEGRATION.md). Contract notes: OpenAPI api/openapi.yaml (Provenance, AuditSnapshot); leaderboards api/LEADERBOARD_INTEGRATION.md.

IDs matter

Use stable org_*, cause_*, int_*, eval_*, gv_*, vp_* IDs in agent tool calls and memory.