CIPHER Visualization Tool API

About this API

This service publishes the CIPHER visualization tool registry and phenotype link discovery data. Tool metadata is maintained in data/tools.csv; API metadata is configured in config.yaml, and phenotype records are loaded from data/uqid.csv.

Base URL:
Production: https://shiny.parse-health.org/va/api/

The phenotype dataset contains UQIDs, phenotype IDs and names, with one tool ID per row. The phenotype endpoint aggregates tool rows sharing a UQID and phenotype ID into related-tool names and URLs.

Endpoints

Method and path	Description	Parameters
`GET /tools`	Returns API version, update time, and all configured tools.	None
`GET /tools/{tool_id}`	Returns the tool's link template and supported phenotypes.	Tool ID
`GET /phenotypes`	Returns per-tool counts, one phenotype record, or the full record list.	Optional `uqid`

Phenotype query parameter

Parameter	Required	Description	Behavior
`uqid`	No	Unique phenotype identifier.	Omit or leave empty to return UQID counts grouped by tool. A specific UQID returns only its phenotype record, without the metadata wrapper. Use `all` to return the complete phenotype list. An unknown UQID returns `[]`.

Every phenotype record includes uqid, name, id, and related_tools. Related tools are returned as objects containing name and tool_url.

Request examples

List all registered tools

Try the tools endpoint

Get one tool's supported phenotypes

{
  "link_template": "https://shiny.parse-health.org/va/kesernetwork-linkage/?uqid={uqid}",
  "supported_phenotypes": [
    {
      "uqid": "42afa80ac70748b5b949729d63d94c47",
      "id": "PheCode:008",
      "name": "Intestinal infection",
      "tool": "keser"
    },
    ...
  ]
}

Try this endpoint

Get UQID counts by tool (default)

{
  "name": "Phenotype Network Explorer",
  "uqid_counts": [
    { "tool_name": "KESER", "uqid_count": 1850 },
    { "tool_name": "GeoPheno", "uqid_count": 1859 }
  ]
}

Try the UQID count endpoint

Find one phenotype by UQID

Try this endpoint

{
  "uqid": "42afa80ac70748b5b949729d63d94c47",
  "name": "Intestinal infection",
  "id": "PheCode:008",
  "related_tools": [
    {
      "name": "KESER",
      "tool_url": "https://shiny.parse-health.org/va/kesernetwork-linkage/?uqid=42afa80ac70748b5b949729d63d94c47"
    },
    {
      "name": "GeoPheno",
      "tool_url": "https://shiny.parse-health.org/va/geopheno/?phenotype=42afa80ac70748b5b949729d63d94c47"
    }
  ]
}

Get the complete phenotype list

Try this endpoint

This returns a JSON array of phenotype records directly, without the metadata wrapper. The complete response contains all current records from data/uqid.csv.

Rate limits

Requests to /api/* are limited per client IP using a token bucket: a burst of up to 20 requests, replenished at 20 requests per minute.

When the limit is exceeded, the API responds with HTTP 429 Too Many Requests, a Retry-After header, and X-RateLimit-Limit / X-RateLimit-Remaining headers. The homepage and stylesheet are not counted against the API limit.

Rate-limit state is stored in the shared Redis service, so API instances attached to the same Redis share quotas. If Redis is unavailable, API requests return HTTP 503 rather than bypassing rate limits. If deployed behind a proxy, set its IP in TRUSTED_PROXY_IPS and configure it to overwrite X-Forwarded-For.