ONCE API Documentation

Search and Feature Retrieval API

This API provides concept search, NLP feature retrieval, phecode feature retrieval, and NLP dictionary export for external use.

URIs | Query Parameters | Sample Output | Authentication & Usage| Rate Limits

The base URI is the current deployment host. Main use cases include:

  • Search related CUI and PheCode candidates from a free-text query.
  • Retrieve matched articles for a query/CUI context.
  • Retrieve NLP feature tables for concept review and filtering.
  • Retrieve phecode feature tables for phenotyping workflows.
  • Export an NLP dictionary for downstream use.

URIs

Base URI: /

Sample URI Description Returned Object
/health Health check for service monitoring. Status object
/search?query=rheumatoid arthritis Retrieve related CUI and PheCode candidates. Search result object
/nlp/feature?query=rheumatoid arthritis Retrieve NLP feature rows. Array of table rows
/nlp/article?query=rheumatoid arthritis Retrieve matched articles (getArticleTable). Array of table rows
/phe/feature?query=rheumatoid arthritis Retrieve phecode feature rows. Array of table rows
/nlp/dictionary?query=rheumatoid arthritis Export CUI and term pairs for the NLP dictionary. Array of dictionary rows

Query Parameters

Parameter Required Description Valid Values Default
query Y Free-text query string used as the primary search input. Any string ""
selected_cui N Explicit CUI list in CSV format. When omitted, the service infers a CUI from query. CSV of CUI values ""
selected_phe N Explicit phecode list in CSV format for /phe/feature. CSV of PheCode values ""
exact N Use exact matching behavior for NLP feature and dictionary queries. true, false false
title_min, title_max N Filter range for title similarity scores. Numeric 0.5, 1
wi_min, wi_max N Filter range for word importance scores. Numeric 0.3, 1
phe_min, phe_max N Filter range for phecode-related similarity scores. Numeric 0.165, 1
titles N Optional CSV list of title filters for /nlp/feature. CSV string ""
dataset N Choose the filter setting for CUIs you would like to download: phenotype = Maximally relevant CUIs for use in phenotyping; study = Broadly relevant CUIs for clinical study; all = All CUIs from NLP Features tab. phenotype, study, all phenotype
terms N Controls whether to export preferred terms only or all terms. pt, all pt

Sample Output

GET /search?query=rheumatoid%20arthritis

{
  "query": "rheumatoid arthritis",
  "related_cui": ["C0003873"],
  "cui_term": ["Rheumatoid Arthritis"],
  "related_phecode": ["714.1"],
  "phe_term": ["Rheumatoid arthritis"]
}

GET /health

{
  "status": "ok"
}

GET /nlp/dictionary?query=rheumatoid%20arthritis&selected_cui=C0003873

[
  {
    "STR": "Rheumatoid Arthritis",
    "CUI": "C0003873"
  }
]

Authentication & Usage

All API endpoints require authentication using a Bearer token. Include your API key in the Authorization header with every request: 

Authorization: Bearer your-apikey

Example Request using curl:

curl -H "Authorization: Bearer your-apikey" "https://shiny.parse-health.org/once/api/search?query=rheumatoid%20arthritis"

👉 Don't have an API Key? Register an account and get your key at https://shiny.parse-health.org/once/ .

Rate Limits

To ensure fair usage and service stability, request rate limits are enforced by client IP address:

  • Limit: 20 requests / minute per IP address.
  • Exceeded Limit Response: HTTP 429 Too Many Requests.

If you hit the rate limit, please wait for the 1-minute window to reset before making further requests.