API reference — Did it work? for developers

Three calls to start with

shell

curl -s https://api.diditwork.org/v1/meta
curl -s 'https://api.diditwork.org/v1/recommend?outcome=lives_saved&limit=3'
curl -s https://api.diditwork.org/v1/claims/eval_gw_amf__0

ServiceGET / · GET /health · GET /openapi.yaml · POST /mcp · GET /mcp
Meta and provenanceGET /v1/meta · GET /v1/meta/snapshot
OrganizationsGET /v1/orgs · GET /v1/orgs/{id}
SearchGET /v1/search
RecommendationsGET /v1/recommend · POST /v1/recommend
CompareGET /v1/compare
OutcomesGET /v1/outcomes · GET /v1/outcomes/{id}
LeaderboardsGET /v1/leaderboards · GET /v1/leaderboards/{id}
ClaimsGET /v1/claims · GET /v1/claims/{id}
Outcome ledgerGET /v1/ledger · GET /v1/ledger/{id}
Values profilesGET /v1/values-profiles · GET /v1/values-profiles/{id}
Impact estimates (modeled)GET /v1/impact-estimate
Portfolio (modeled)GET /v1/portfolio/allocate · POST /v1/portfolio/allocate
Giving intents (no charge)GET /v1/giving/intent · POST /v1/giving/intent
InterventionsGET /v1/interventions · GET /v1/interventions/{id}
EvaluationsGET /v1/evaluations/{id}
TrustGET /v1/trust/{org_id}
CausesGET /v1/causes · GET /v1/causes/{id}
Review queueGET /v1/review/queue · GET /v1/review/queue/{id}
Tax status (not advice)GET /v1/tax/{org_id}

Service

GET/

API landing (name, version and where to go next) · Open

GET/health

Health and trust of the API surface · Open

GET/openapi.yaml

This OpenAPI document (machine-readable contract) · Open

POST/mcp

MCP endpoint (Streamable HTTP, JSON-RPC 2.0, read-only tools)

Parameter	In	Required	Notes
`MCP-Protocol-Version`	header	no	One of: 2026-07-28, 2025-11-25, 2025-06-18, 2025-03-26, 2024-11-05
`Mcp-Method`	header	no	Required (and validated against the body) for protocol 2026-07-28.
`Mcp-Name`	header	no	tools/call tool name; required for protocol 2026-07-28 (base64 sentinel accepted).

GET/mcp

GET is not supported (POST-only Streamable HTTP endpoint; no SSE stream) · Open

Meta and provenance

GET/v1/meta

API version, build time, catalog counts, and discovery links · Open

GET/v1/meta/snapshot

Reproducibility / audit snapshot (data + code identity) · Open

Organizations

GET/v1/orgs

List organizations / programs / funds · Open

Parameter	In	Required	Notes
`entity_type`	query	no	One of: organization, program, fund, evaluator_vehicle
`recommendation_tier`	query	no
`cause_id`	query	no
`q`	query	no	Free-text search over name, tags, summary (max 256; path traversal refused)
`ids`	query	no	Comma-separated org ids (empty → empty list; unknown → missing; never invent)
`limit`	query	no	Max rows to return (1..500); oversized → 400

GET/v1/orgs/{id}

Get one org by stable id

Parameter	In	Required	Notes
`id`	path	yes	e.g. `org_against_malaria_foundation`

Search

GET/v1/search

Search by cause, outcome family, or donor intent phrase (heuristic) · Open

Parameter	In	Required	Notes
`q`	query	no	Free-text query. e.g. `malaria`
`cause`	query	no	e.g. `malaria`
`outcome`	query	no	lives_saved \| wellbeing_wellbys \| income (cross-unit tokens refused)
`intent`	query	no	Natural language hint, e.g.
`limit`	query	no	Max hits (default 25, capped at 50).

GET/v1/recommend

Conviction-ranked orgs for an outcome family · Open

Parameter	In	Required	Notes
`values_profile_id`	query	no	Load preset from data/values_profiles/{id}.json. e.g. `vp_lives_no_deworm`
`outcome`	query	no	lives_saved \| wellbeing_wellbys \| income (aliases accepted). e.g. `lives_saved`
`outcome_preference`	query	no	Alias for outcome (values-profile field name)
`budget_usd`	query	no	e.g. `1000`
`risk`	query	no	One of: low, medium, high
`geography`	query	no	e.g. `Kenya`
`require_geography`	query	no
`tax`	query	no	One of: us_501c3_preferred, us_deductible, any
`red_lines`	query	no	Comma-separated cause ids or tags to exclude e.g. `cause_deworming`
`non_cash`	query	no	Prefer orgs with non_cash_giving options
`limit`	query	no

Compare

GET/v1/compare

Side-by-side claims, tiers, and trust for two or more orgs · Open

Parameter	In	Required	Notes
`ids`	query	yes	e.g. `org_against_malaria_foundation,org_malaria_consortium`

Outcomes

GET/v1/outcomes

Outcome families (separate boards; no cross-unit mix) · Open

Parameter	In	Required	Notes
`outcome`	query	no	Optional family filter (lives_saved \| wellbeing_wellbys \| income; aliases accepted). e.g. `lives_saved`
`ids`	query	no	Optional comma-separated family ids. e.g. `lives_saved,income`

GET/v1/outcomes/{id}

Single outcome family by id

Parameter	In	Required	Notes
`id`	path	yes	Outcome-family id (allowlisted) e.g. `lives_saved`

Leaderboards

GET/v1/leaderboards

Per-outcome-family frozen leaderboards · Open

Parameter	In	Required	Notes
`outcome`	query	no	Optional family filter (lives_saved \| wellbeing_wellbys \| income; aliases accepted). e.g. `lives_saved`

GET/v1/leaderboards/{id}

Single per-outcome-family leaderboard by board id

Parameter	In	Required	Notes
`id`	path	yes	Outcome-family board id (allowlisted) e.g. `lives_saved`

Claims

GET/v1/claims

Read-only flat claims index · Open

Parameter	In	Required	Notes
`org_id`	query	no	e.g. `org_against_malaria_foundation`
`evaluation_id`	query	no	e.g. `eval_gw_amf`
`verified`	query	no	If true/false, filter on claim.verified e.g. `true`

GET/v1/claims/{id}

Get one claim by claim_id

Parameter	In	Required	Notes
`id`	path	yes	e.g. `eval_gw_amf__0`

Outcome ledger

GET/v1/ledger

Outcome ledger ("Did it work?") v0 — read-only, append-only, hash-chained · Open

Parameter	In	Required	Notes
`org_id`	query	no	e.g. `org_against_malaria_foundation`
`evaluator`	query	no	One of: givewell, hli, ace, who, ihme
`status`	query	no	One of: pending, confirmed, contradicted, unverifiable
`intervention_id`	query	no	e.g. `int_itn`
`record_kind`	query	no	One of: claim_snapshot, follow_up_result

GET/v1/ledger/{id}

One outcome-ledger record (+ its follow-up results)

Parameter	In	Required	Notes
`id`	path	yes	e.g. `ldg_eval_gw_amf__0`

Values profiles

GET/v1/values-profiles

Read-only values preset catalog · Open

GET/v1/values-profiles/{id}

Get one values preset by id

Parameter	In	Required	Notes
`id`	path	yes	e.g. `vp_lives_no_deworm`

Impact estimates (modeled)

GET/v1/impact-estimate

Modeled gift outcomes (not guaranteed) · Open

Parameter	In	Required	Notes
`org_id`	query	yes	e.g. `org_against_malaria_foundation`
`gift_usd`	query	yes	e.g. `1000`

Portfolio (modeled)

GET/v1/portfolio/allocate

Suggest a conviction-weighted portfolio + modeled impact · Open

Parameter	In	Required	Notes
`budget_usd`	query	yes	e.g. `10000`
`outcome`	query	yes	e.g. `lives_saved`
`top_n`	query	no
`method`	query	no
`red_lines`	query	no	Comma-separated cause ids/tags to exclude
`risk`	query	no
`geography`	query	no
`tax`	query	no
`include_funds`	query	no

POST/v1/portfolio/allocate

Same as GET with optional inline values_profile

Giving intents (no charge)

GET/v1/giving/intent

NO-CHARGE deep-link donate handoff · Open

Parameter	In	Required	Notes
`org_id`	query	yes	e.g. `org_against_malaria_foundation`
`amount_usd`	query	yes	e.g. `100`
`vehicle`	query	no	direct_cash \| daf \| stock \| crypto \| qcd (non-cash handoffs)
`values_profile_id`	query	no
`include_impact`	query	no
`intent_id`	query	no

POST/v1/giving/intent

Same as GET with JSON body

Interventions

GET/v1/interventions

Interventions catalog (live only) · Open

Parameter	In	Required	Notes
`cause_id`	query	no	e.g. `cause_malaria`
`ids`	query	no
`limit`	query	no

GET/v1/interventions/{id}

Get one live intervention by id

Parameter	In	Required	Notes
`id`	path	yes	e.g. `int_smc`

Evaluations

GET/v1/evaluations/{id}

Get one evaluation by id

Parameter	In	Required	Notes
`id`	path	yes	e.g. `eval_gw_amf`

Trust

GET/v1/trust/{org_id}

Trust flags for an org

Parameter	In	Required	Notes
`org_id`	path	yes	e.g. `org_against_malaria_foundation`

Causes

GET/v1/causes

Cause catalog (list) · Open

Parameter	In	Required	Notes
`phase`	query	no	live\|active\|future\|all (default all)
`ids`	query	no	Comma-separated cause ids (allowlist cause_[a-z0-9_]+)
`limit`	query	no	Optional positive slice; invalid/oversized ignored

GET/v1/causes/{id}

Cause detail by id

Parameter	In	Required	Notes
`id`	path	yes	e.g. `cause_malaria`

Review queue

GET/v1/review/queue

Human exception-review queue (read-only) · Open

Parameter	In	Required	Notes
`status`	query	no	open\|approved\|rejected\|all (default open when omitted; empty → 400)

GET/v1/review/queue/{id}

Single exception-review queue item (read-only)

Parameter	In	Required	Notes
`id`	path	yes	e.g. `exc_20261001_actra_donate`

Tax status (not advice)

GET/v1/tax/{org_id}

Sanitized trust/tax-status summary (not tax advice)

Parameter	In	Required	Notes
`org_id`	path	yes	e.g. `org_against_malaria_foundation`

More detail

Full request and response schemas are in the OpenAPI document. Worked examples: how to query the API and the agent playbook.