# EXTERNAL_API_CLIENTS

**Type:** Runtime Utility (dispatch notes)
**Authority:** OpenAlex docs; Crossref docs; SciELO thematic portals; AJOL advanced-search reference; CADTH Grey Matters tool; Godin et al. (2015) targeted-web-search protocol.
**Invocation:** Step 5 of SKILL.md when generating per-corpus queries.

---

## OpenAlex (Surface 1)

- **Role:** Broadest open-access index; primary English peer-reviewed fetch.
- **Query shape:** search `title`, `abstract`, `concepts`; filter by `type`, `publication_year`, `authorships.countries`, `host_venue.id`.
- **Language handling:** IGNORE `language` field for the Ledger tag. Use `language:!null` only as a dispatch filter.
- **Noise:** systematic English over-classification (Cespedes 2025); mitigated at Step 6.

## Crossref (Surface 1)

- **Role:** DOI-authoritative metadata; venue verification.
- **Query:** `query.bibliographic` + `filter=type:journal-article,from-pub-date:YYYY`.
- **Use:** venue-heuristic input for fidelity triple-check.

## SciELO (Surface 2a)

- **Query shape:** SciELO thematic portals + regional endpoints; query in native language (PT/ES) AND include English back-translation.
- **Per-query ledger:** translation provenance logged -- which language the synonym set came from and whether MT produced it.

## AJOL (Surface 2b)

- **Query shape:** advanced search by region/subject/language. Francophone West Africa: dispatch French synonyms alongside English. Lusophone southern Africa: include Portuguese.
- **Per-query ledger:** country-filter rationale required; blanket "Africa" queries are discouraged.

## Practitioner / Grey (Surface 3)

- **Protocol:** Godin et al. (2015) + CADTH Grey Matters.
- **Targets:** HTA agencies (CADTH, NICE, AHRQ, PBAC, IQWiG); regulator dockets (FDA dockets.regulations.gov, EMA, EPA, USDA, OSHA); professional-association guidance (named specialty societies, logged per query); field-report repositories.
- **NO hardcoded `site:` as a tier proxy.** Q1 Decision Point: permitted only when operator has named the site AND rationale is logged.
- **Budget:** over-budget surfaces write `every-skipped` with an `unreached-surface` reason.

## Non-Western / Indigenous Scholarship (Surface 4)

- **Gate:** CARE_GATE_PROTOCOL passes before dispatch.
- **Query shape:** named-canon author queries (Smith, Kovach, Chilisa, Connell, Berkes, Kimmerer); Indigenous-studies journals; publicly indexed tribal-college repositories.
- **Record-level CARE re-check** at Step 6.
- **Architectural-limit trigger:** community-controlled primary material not publicly indexed -- do NOT approximate; write `architectural_limit_disclosure`.

---

## Dispatch Parallelism

Dispatch to independent surfaces in parallel. Heuristic bounds:
- 2 corpora minimum when any trigger fires.
- 4 corpora when domain is high-stakes (mental health, agriculture, governance, child-rearing, ecology).
- Queue / rate-limit handling is the runtime's concern; a failed dispatch writes an `every-skipped` record with a `dispatch-failure` reason rather than a silent drop.

## Ledger Fields Per Query

`query_id`, `query_text`, `corpus`, `claim_id`, `claim_type`, `monoculture_triggers`, `routing_decision`, `rationale`, timestamp.

## Anti-Patterns

- Using `site:edu` / `site:gov` / `site:org` to approximate tier quality -- the THROWN Librarian defect.
- Running a blanket `language:en` filter on OpenAlex when M1 requires non-English routing.
- Silently retrying a failed SciELO dispatch without a `dispatch-failure` ledger entry.
- Dispatching Surface 4 without a completed CARE gate.
