Rawafid Developer Platform

Public read endpoints require no credential. Institutional keys are optional and should remain server-side.

curl -sS 'https://healthrenewal.org/api/v1'

curl -sS 'https://healthrenewal.org/api/v1/content?limit=5'

curl -sS 'https://healthrenewal.org/api/v1/search?q=autism&limit=5'

curl -sS 'https://healthrenewal.org/api/v1/evidence-discovery?q=autism&providers=europe_pmc,crossref,datacite&limit=5'

const response = await fetch('https://healthrenewal.org/api/v1/content?limit=5', {
  headers: { Accept: 'application/json' }
});
if (!response.ok) throw new Error(`Rawafid API: ${response.status}`);
const { data, pagination } = await response.json();

/api/v1 is the current stable major path and responses report API version 1.2.0. The public content API is restricted to published, indexable records whose publication time has arrived.

The contract is currently emitted as OpenAPI 3.1.0 with JSON Schema 2020-12. Retaining the 3.1 tooling line is a compatibility decision; it is not a claim that 3.1.0 is the newest OpenAPI specification.

No proprietary SDK is required. Standard HTTP, JSON and the OpenAPI document are the canonical integration surfaces.

Public reads are anonymous. A partner may optionally send X-API-Key or Authorization: Bearer …. Issued keys use the rawafid_live_* format, are displayed once, and are stored only as a SHA-256 digest.

Scopes are content:read, sources:read, search:read, changes:read and stats:read.

The current default partner allocation is 120 requests/minute and 25,000 requests/day, but allocations are configurable. Treat the returned X-RateLimit-* headers as authoritative. Quota exhaustion returns 429 with Retry-After.

curl -sS \
  -H 'X-API-Key: rawafid_live_REDACTED' \
  'https://healthrenewal.org/api/v1/content?limit=25'

Do not embed institutional keys in public browser code, mobile bundles, repositories, analytics, or URLs.

/evidence-discovery searches Europe PMC, Crossref and DataCite by default. Provider failures are isolated and exposed in typed provider status instead of collapsing all results.

Lens is explicit opt-in: add providers=lens to request it. The Lens credential remains server-side, Lens ID is preserved, and displays must retain the attribution Data Sourced from The Lens. The enforced shared allocation is 10 requests/minute and 20,000 requests/month with fail-closed quota enforcement.

Detailed Lens documentation → · Lens machine-readable manifest ↗

JSON responses carry ETag; eligible routes also emit Last-Modified. Send If-None-Match or If-Modified-Since to receive 304 Not Modified when appropriate.

API responses expose X-Request-Id for correlation. CORS supports GET, HEAD, OPTIONS and the documented request headers. API payload endpoints use X-Robots-Tag: noindex, nofollow; the human documentation pages remain indexable.

Errors use error.code, error.message, error.request_id and, when relevant, error.parameter. Common statuses are 400, 401, 403, 404, 429 and 503. A temporary upstream failure is not converted into a misleading successful empty result.

{
  "error": {
    "code": "invalid_parameter",
    "message": "...",
    "parameter": "q",
    "request_id": "..."
  },
  "meta": { "api_version": "1.2.0" }
}

The conservative default is link_and_citation_only unless an explicit licence grants broader reuse. API availability does not itself grant permission to republish full text, abstracts, images, files or upstream provider datasets.

Source detail can separate metadata rights from content rights and can preserve translation provenance: source/target language, method, tool/version, translator, reviewer, ORCID/ROR where verified, review status and content hash.

Feeds support validators and 304 responses. If the underlying catalog is unavailable, they fail safely with 503 and Retry-After rather than publishing a false empty feed.

For institutional access, interoperability review or a production issue, contact contact@healthrenewal.org. Include the endpoint, timestamp, HTTP status and X-Request-Id. Never send a full API key by email.