Skip to content

REST API

NeoRx ships a FastAPI service wrapping the pipeline, so a run can be started and polled over HTTP rather than held in a Python process.

neorx serve --port 8000

Interactive docs at http://localhost:8000/docs, the OpenAPI schema at /openapi.json, and ReDoc at /redoc.

Endpoints

Method Path Does
GET /health Liveness check
POST /run Start a full pipeline run; returns a job ID
GET /status/{job_id} Progress and status of a run
GET /report/{job_id} The HTML report for a finished run
POST /graph Build the disease graph only
POST /identify Identify causal targets only
POST /screen-target Screen candidates against one target

/run is asynchronous: it returns a job ID immediately and the work proceeds in the background. /graph, /identify and /screen-target are synchronous and block until done — which for /graph means minutes against eight live services.

>>> from fastapi.testclient import TestClient
>>> from neorx.core.api import app
>>> client = TestClient(app)
>>> response = client.get("/health")
>>> response.status_code, response.json()
(200, {'status': 'ok', 'service': 'NeoRx'})

A missing job is a 404 with a message, not an empty success:

>>> response = client.get("/status/not-a-real-job")
>>> response.status_code
404
>>> response.json()
{'detail': 'Job not-a-real-job not found.'}

Request models

Every endpoint takes a Pydantic model, so a malformed request is rejected with a 422 and a field-level explanation rather than failing somewhere inside the pipeline.

>>> from neorx import (RunRequest, GraphRequest, IdentifyRequest,
...                    ScreenTargetRequest, StatusResponse)
>>> list(RunRequest.model_fields)
['disease', 'top_n_targets', 'candidates_per_target', 'allow_mocks']
>>> list(IdentifyRequest.model_fields)
['disease', 'top_n', 'allow_mocks']
>>> list(ScreenTargetRequest.model_fields)
['target_uniprot_id', 'target_pdb_id', 'n_candidates', 'causal_confidence']
>>> list(StatusResponse.model_fields)
['job_id', 'status', 'progress_pct', 'current_step', 'error']

The bounds are enforced, not advisory:

>>> request = RunRequest(disease="HIV")
>>> request.top_n_targets, request.candidates_per_target, request.allow_mocks
(5, 1000, False)
>>> import pydantic
>>> try:
...     RunRequest(disease="HIV", top_n_targets=500)
... except pydantic.ValidationError as exc:
...     print("rejected:", "less_than_equal" in str(exc))
rejected: True
>>> try:
...     RunRequest(disease="")
... except pydantic.ValidationError as exc:
...     print("rejected:", "at least 1 character" in str(exc))
rejected: True

top_n_targets is capped at 50 and candidates_per_target at 50,000 — limits on a public endpoint rather than suggestions. Note that RunRequest.candidates_per_target defaults to 1000, where the CLI's --candidates defaults to 100.

allow_mocks is exposed on /run, /graph and /identify and defaults to False, the same as everywhere else. Enabling it over HTTP means the response can contain curated hand-written data; see the CLI note.

Using it

curl http://localhost:8000/health

curl -X POST http://localhost:8000/run \
  -H "Content-Type: application/json" \
  -d '{"disease": "HIV", "top_n_targets": 5}'

curl http://localhost:8000/status/<job_id>

curl -X POST http://localhost:8000/identify \
  -H "Content-Type: application/json" \
  -d '{"disease": "HIV", "top_n": 10}'

Job state

Jobs are held in the service process. With DATABASE_URL set they are also written to PostgreSQL, which is what the Docker Compose setup provides — see Install. Without it, restarting the service loses in-flight job state.

There is no authentication

The service has no auth, no rate limiting and no request quotas, and neorx serve binds 0.0.0.0 by default. Every endpoint can start minutes of work against third-party APIs on an unauthenticated request. Run it behind something, or bind it to localhost.

Reports

GET /report/{job_id} returns the HTML report for a completed job: the causal knowledge graph visualisation, the target reasoning, and the ranked candidate table. The same report is written to disk by run_pipeline(..., generate_report=True) and its path appears on PipelineResult.report_path.