Seeds, Research & Health API

Who should read this — Integrators calling the Newsfork engine core. Start from API overview for base URLs and authentication.

Overview

Engine core interfaces cover health checks, research (URL discovery), and seeds (contracts and orchestration). Health verifies system status; Research defines where to look; Seeds define how to retrieve content.

Health API

System status verification endpoints.

Base path: /health

• GET /health — Basic health check. Returns status, timestamp, version.
• GET /health/ready — Readiness. Whether ready to receive traffic.
• GET /health/live — Liveness. Process survival status.

The root GET / returns a list of API names, versions, and endpoints in JSON format.

Research API

The Research Engine handles “where to look”.

Base path: /api/v1/research

• GET /api/v1/research — Research list (country, category, date, limit, offset query).
• GET /api/v1/research/index — Research index (table of contents).
• GET /api/v1/research/:country/:category/:date — Specific Research details.
• POST /api/v1/research — Create new Research (ResearchCreateRequest).

Seeds API

The Seed Engine defines “how to retrieve”.

Base path: /api/v1/seeds

• GET /api/v1/seeds — Seed list (country, status, source_type, limit, offset query).
• GET /api/v1/seeds/:seedId — Retrieve a specific Seed.
• POST /api/v1/seeds — Create a new Seed (draft).
• PATCH /api/v1/seeds/:seedId — Modify Seed.
• POST /api/v1/seeds/promote — Promote Draft → active.
• POST /api/v1/seeds/orchestrate — Trigger Seed orchestration (R2 raw list → SEED_QUEUE). Request body: country, category, date, force (optional).

Authentication

Send API credentials in the Authorization header. See API overview and API Quickstart.

Next steps

• Data Management API — Datasets and metadata.
• Infrastructure API — Queue batch jobs.
• Research guide — URL discovery workflow.

Notes

• Implementation: src/routes/health.ts, src/routes/research.ts, src/routes/seeds.ts, src/routes/seed-orchestrator.ts