API Reference · v1

EOS Developer API

Integrate EOS directly into your LIMS, data pipeline, or application. The API streams AI-generated scientific pathways over Server-Sent Events, with the same NOVA engine, citations, and Sentinel validation as the web app.

ULTRA plan required

Authentication

All requests authenticate with an API key passed in the X-Api-Key header. Generate and manage keys in My Studio. Keys are shown once — store them securely.

Header

X-Api-Key: eoskey_xxxxxxxxxxxxxxxxxxxx

Generate a pathway

POST /v1/stream — submit a query and receive a stream of SSE events as the pipeline progresses.

cURL

curl -N https://project-eos-production.up.railway.app/v1/stream \
  -H "X-Api-Key: eoskey_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "Remove PFAS from contaminated groundwater",
    "target_pollutant": "PFAS"
  }'

Request body

querystringrequiredThe scientific problem to solve.

target_pollutantstringoptionalFocus contaminant (e.g. PFAS, Microplastics, GHG).

Response — Server-Sent Events

Each event is a data: line with a JSON payload. The phase field tracks pipeline progress; the final event has phase: "complete".

Event stream

data: {"phase": "gatekeeper", "status": "PASS"}

data: {"phase": "archivist", "documents": 6, "source_type": "hybrid"}

data: {"phase": "alchemist", "pathway": "A", "status": "streaming"}

data: {"phase": "complete", "result": { ...pathways, citations, sentinel... }}

Reading the stream — Python

Python (httpx)

import httpx, json

with httpx.stream(
    "POST",
    "https://project-eos-production.up.railway.app/v1/stream",
    headers={"X-Api-Key": "eoskey_xxxxxxxxxxxx"},
    json={"query": "Degrade polystyrene microplastics", "target_pollutant": "Microplastics"},
    timeout=None,
) as r:
    for line in r.iter_lines():
        if line.startswith("data: "):
            event = json.loads(line[6:])
            print(event.get("phase"), event)
            if event.get("phase") == "complete":
                break

Errors

Errors are returned as a single complete event with a blocked: true flag, so your stream parser handles them uniformly.

Missing X-Api-Key headerNo API key supplied.

Invalid or revoked API keyKey not found or revoked in Studio.

ULTRA subscription required for API accessAccount is not on the ULTRA plan.

Rate limits

API requests share the platform's global rate limit (60 requests/minute per IP). ULTRA accounts have unlimited NOVA generations per day. For higher throughput or a dedicated SLA, contact us about Enterprise.

Ready to integrate?

Upgrade to ULTRA and generate your first API key in seconds.

View plans →Talk to us