Priolix Developer Guide

Short integration guide for developers calling Priolix HTTP APIs.

Base URL

• Production: https://priolix.com
• Local dev: http://127.0.0.1:4999

Interactive docs: GET /docs (OpenAPI/Swagger UI).

Authentication

Priolix uses bearer tokens. Supply your API key in the Authorization header:

Authorization: Bearer hw_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

• Keys are issued per-integration and hashed at rest.
• The raw key is shown exactly once when created — store it immediately.
• Deactivated keys (set active=0 in data/api_keys.db) return 401.

See docs/API_ENDPOINT_CLASSIFICATION.md for which endpoints require a key.

Requesting a Key

Ask your Priolix contact to mint one (admin-only operation). Self-serve key creation will arrive with the paid developer tier.

Rotating a Key

Request a new key, update your integration, then ask an admin to deactivate the old one.

Quotas

Two quota buckets are enforced per key and per anonymous IP:

• Per-minute (rpm_limit)
• Per-day (daily_limit)

Default plans:

Plan	RPM	Daily
Anonymous	30	500
Free key	120	5,000
Admin key	1,200	100,000

Quota exhaustion returns:

HTTP/1.1 429 Too Many Requests
Content-Type: application/json

{"detail": "Quota exceeded (minute): 120/120"}

Example Calls

Evidence search results

curl -H "Authorization: Bearer $PRIOLIX_KEY" \
  "https://priolix.com/api/sources?vertical=magnesium&min_score=60&page=1"

Drug-supplement interaction check

curl -H "Authorization: Bearer $PRIOLIX_KEY" \
  "https://priolix.com/api/interactions/check?supplement=st-johns-wort&drug=sertraline"

Product evidence card

curl -H "Authorization: Bearer $PRIOLIX_KEY" \
  "https://priolix.com/api/products/<dsld_id>"

Bulk CSV export (requires key)

curl -H "Authorization: Bearer $PRIOLIX_KEY" \
  "https://priolix.com/api/export/csv?vertical=omega-3" -o omega3.csv

Describe your key

curl -H "Authorization: Bearer $PRIOLIX_KEY" \
  "https://priolix.com/api/keys/me"

Error Model

Status	Meaning
200	Success
401	Missing / invalid / deactivated API key
403	Non-admin key on admin route
404	Entity not found
422	Invalid request body/query parameters
429	Quota exceeded
5xx	Server error — retry with backoff

Stable APIs (v1)

Versioned endpoints under /v1/ carry a stability guarantee: breaking changes will not be introduced within a version. New fields may be added (clients should ignore unknown fields). Breaking changes ship as /v2 endpoints.

GET /v1/evidence/search

Search the Priolix biomedical evidence corpus. Returns ranked, citation-grounded sources with quality scores and PMIDs. Requires API key.

Parameters:

Param	Type	Required	Default	Description
q	string	✅	—	Search query (1-500 chars)
top_k	int	—	15	Number of results (1-50)
min_quality_tier	string	—	""	Minimum tier: A, B, C, D
source_class	string	—	""	Filter: pubmed_article, clinical_trial, guideline, etc.
vertical	string	—	""	Filter by vertical (e.g. magnesium-sleep)

Example:

curl "https://priolix.com/v1/evidence/search?q=magnesium+sleep&top_k=5" \
  -H "Authorization: Bearer hw_YOUR_KEY_HERE"

Response:

{
  "query": "magnesium sleep",
  "retrieval_version": "2026.04.27-rerank-router",
  "index_version": "mtime-1776680275",
  "results": [
    {
      "source_id": "38703902",
      "pmid": "38703902",
      "doi": "10.1016/j.jad.2024.05.002",
      "title": "Association between magnesium deficiency score and sleep quality...",
      "abstract_or_summary": "BACKGROUND: The association between magnesium status...",
      "quality_score": 49.0,
      "quality_tier": "C",
      "evidence_level": "other",
      "source_class": "pubmed_article",
      "rank_score": 641.55,
      "rank_reasons": ["bm25", "semantic", "rrf_primary"],
      "year": 2024,
      "vertical": "magnesium-sleep",
      "sample_size": "20585",
      "population": "older adults"
    }
  ],
  "total_returned": 5,
  "latency_ms": 320,
  "reranker_used": false
}

Quality tiers:

Tier	Label	Meaning
A	Strong	Meta-analyses, systematic reviews, high-quality RCTs
B	Moderate	Well-designed RCTs, large observational studies
C	Limited	Smaller studies, cross-sectional, case-control
D	Preliminary	Case reports, expert opinion, in-vitro only

Reranker: The cross-encoder reranker (BAAI/bge-reranker-v2-m3) activates automatically for queries with 10+ words, short queries with typo signals, or medium queries with drug-interaction patterns. The reranker_used field indicates whether it ran. Reranked queries have higher precision but ~0.5s additional latency.

Python quickstart:

import requests

API_KEY = "hw_YOUR_KEY_HERE"
BASE = "https://priolix.com"

def search_evidence(query, top_k=15, min_tier=""):
    params = {"q": query, "top_k": top_k}
    if min_tier:
        params["min_quality_tier"] = min_tier
    r = requests.get(
        f"{BASE}/v1/evidence/search",
        params=params,
        headers={"Authorization": f"Bearer {API_KEY}"},
    )
    r.raise_for_status()
    return r.json()

results = search_evidence("magnesium sleep", top_k=5, min_tier="B")
for hit in results["results"]:
    print(f"[{hit['quality_tier']}] {hit['title'][:80]}  (PMID: {hit['pmid']})")

Stability

• /v1 schemas are stable — breaking changes will not be introduced.
• Unversioned endpoints documented above are considered stable for the current API generation.
• Breaking changes will move under a new versioned namespace; see docs/HEALTH_EVIDENCE_INFRASTRUCTURE_BACKLOG.md P1-2.
• The retrieval_version field in responses identifies the retrieval pipeline version.

Responsible Use

• Do not cache answers to imply medical advice — always link back to the citations.
• Never strip PMIDs/DOIs from responses.
• Respect the consumer-facing medical disclaimer at /disclaimer.
• Report security issues via .well-known/security.txt.

API Endpoint Classification

This is the canonical list of Priolix HTTP endpoints and their auth posture. When adding a new route, place it under the appropriate class and pick the matching FastAPI dependency from jobs/web/platform_auth.py.

Classes

• Public HTML/SEO — Anonymous, no auth, not metered as an API. These are consumer web pages and SEO assets.
• Public limited API — Anonymous allowed but rate-limited by IP via optional_api_key. Authenticated callers get per-key limits instead.
• Authenticated platform API — require_api_key. 401 when unauthenticated. Metered per key.
• Admin-only — require_admin_key. Admin bearer or one-shot X-Admin-Bootstrap header.

Matrix

Public HTML / SEO

• /, /supplements/*, /products/{dsld_id}, /interactions/*, /conditions/*, /articles/*
• /search, /chat, /blood-test*, /wearables* (user-facing flows)
• /robots.txt, /sitemap*.xml, /privacy, /terms, /disclaimer, /editorial-policy
• /api/health, /api/pipeline/status, /api/stats (non-sensitive platform status)

Public Limited API (optional_api_key)

• /api/sources, /api/interventions, /api/gaps, /api/trending
• /api/products, /api/products/{dsld_id}, /api/market/{supplement_slug}, /api/brands
• /api/interactions, /api/interactions/check, /api/drugs/suggest
• /api/label-image/stats
• /api/feedback, /api/chat/feedback (write, also protected by slowapi)

Authenticated Platform API (require_api_key)

• /v1/evidence/search — search evidence corpus, returns ranked hits with quality tiers (stable v1)
• /api/export/csv, /api/export/bibtex — bulk exports
• /api/label-image/{dsld_id} (POST) — writes disk and DB
• /api/keys/me — describe current caller
• /api/ask, /api/ask/stream — LLM generation (currently slowapi-limited; move to API keys for billing)

Admin-only (require_admin_key)

• /api/keys (POST) — key provisioning
• /api/webhooks (GET, POST) — webhook management
• /api/feedback/stats — aggregated user behavior

Default Quotas

Configurable via env vars, persisted in data/api_keys.db:

• Anonymous — PRIOLIX_ANON_RPM (default 30/min), PRIOLIX_ANON_DAILY (default 500/day), keyed by IP.
• Free key — PRIOLIX_FREE_RPM (default 120/min), PRIOLIX_FREE_DAILY (default 5000/day).
• Admin key — PRIOLIX_ADMIN_RPM (default 1200/min), PRIOLIX_ADMIN_DAILY (default 100000/day). Admin keys are not quota-enforced by the dependency; they still record usage.

Per-key overrides (rpm_limit, daily_limit) take precedence over the plan defaults.

Rules for New Endpoints

1. Pick the minimum class that still meets the product requirement.
2. Add ctx: CallContext = Depends(<dep>) to the route signature.
3. If the endpoint does anything expensive (LLM, external API, disk write), require an API key.
4. Anything admin-sensitive (PII aggregates, mutation of platform config, key/webhook management) must be require_admin_key.
5. Update this file in the same PR that adds the route.

Bootstrap

First-time admin key creation:

export PRIOLIX_ADMIN_BOOTSTRAP_KEY=$(openssl rand -hex 32)
curl -X POST https://priolix.com/api/keys \
  -H "X-Admin-Bootstrap: $PRIOLIX_ADMIN_BOOTSTRAP_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "root-admin", "is_admin": true}'

Then unset the env var and use the returned bearer token for subsequent admin operations. Bootstrap is locked out once any admin key exists.