Graph

Graph endpoints enable users to access relationships, findings, and source metadata

Relationships API

The Relationships endpoint allows you to retrieve system relationships between clinical concepts in the Clinical Graph (CG).

---

Base URL

https://cg-api-prod.system.com

Environment	URL
Production	https://cg-api-prod.system.com
Staging	https://cg-api-stage.system.com
Development	https://cg-api-dev.system.com
Local	http://localhost:80

---

Authentication

All requests require an API key passed in the request header.

Header	Value
x-api-key	Your API key

Example header:

x-api-key: YOUR_API_KEY

---

1

Get a Relationship by ID

Retrieve a single relationship by its unique identifier.

GET /v1/relationships/{relationship_id}

Path Parameters

Parameter	Type	Required	Description
relationship_id	string	✅ Yes	Unique identifier of the relationship

Responses

Status Code	Description
200	Relationship object returned successfully
404	Relationship not found
422	Validation error

Example Request

HTTP

GET /v1/relationships/rel_abc123 HTTP/1.1
Host: cg-api-prod.system.com
x-api-key: YOUR_API_KEY

Example Response (200)

JSON

{
  "relationship_id": "rel_abc123",
  "from_concept": {
    "cui": "C0020538",
    "preferred_name": "Hypertension",
    "system_category": "condition",
    "ccsr_body_systems": ["Circulatory system"],
    "ccsr_categories": ["CIR009"]
  },
  "to_concept": {
    "cui": "C0007787",
    "preferred_name": "Stroke",
    "system_category": "condition",
    "ccsr_body_systems": ["Nervous system"],
    "ccsr_categories": ["NVS010"]
  },
  "metadata": {
    "num_findings": 42,
    "num_studies": 18,
    "last_published_date": "2023-09-15T00:00:00Z",
    "highest_cited": 3200,
    "highest_sample_size": 50000,
    "num_experimental_trials": 5,
    "median_effect_size": 1.45,
    "num_significant_findings": 30,
    "last_updated": "2024-01-10T12:00:00Z"
  }
}

2

Get a List of Relationships

Retrieve a paginated list of relationships with optional filtering, searching, and field selection.

GET /v1/relationships

Query Parameters

Parameter	Type	Required	Default	Description
filter	string	No	—	Filter by field values. See Filtering
sort	string	No	—	Sort results by a field. See Sorting
search	string	No	—	Search within supported fields. See Searching
fields	string	No	—	Comma-separated list of fields to include in the response
include_total	boolean	No	false	Include total count of records in the response
offset	integer	No	0	Number of records to skip (minimum: 0)
limit	integer	No	10	Maximum number of records to return (minimum: 1)

Filtering

Filters follow the format field:value. Use || for OR conditions.

Supported filter fields:

Field	Description
relationship_id	Unique identifier of the relationship

Examples:

# Single filter
filter=relationship_id:rel_abc123

# OR filter (multiple relationship IDs)
filter=relationship_id:rel_abc123||rel_def456

Sorting

Sorts follow the format field:direction where direction is asc or desc.

⚠️ No sort fields are currently supported for this endpoint.

Searching

Searches follow the format field:value.

Supported search fields:

Field	Description
relationship_id	Unique identifier of the relationship

Example:

search=relationship_id:rel_abc

Field Selection

Use the fields parameter to return only specific fields in the response. Provide a comma-separated list of field names.

Example:

fields=relationship_id,from_concept,to_concept

Pagination

Use offset and limit to paginate through results.

Parameter	Description	Default	Minimum
offset	Number of records to skip	0	0
limit	Number of records to return	10	1
include_total	Include total record count	false	—

Example — Page 2 with 20 results per page:

offset=20&limit=20&include_total=true

Responses

Status Code	Description
200	List of relationships returned successfully
422	Validation error

Example Request

HTTP

GET /v1/relationships?limit=2&include_total=true HTTP/1.1
Host: cg-api-prod.system.com
x-api-key: YOUR_API_KEY

Example Response (200)

JSON

{
  "data": [
    {
      "relationship_id": "rel_abc123",
      "from_concept": {
        "cui": "C0020538",
        "preferred_name": "Hypertension",
        "system_category": "condition",
        "ccsr_body_systems": ["Circulatory system"],
        "ccsr_categories": ["CIR009"]
      },
      "to_concept": {
        "cui": "C0007787",
        "preferred_name": "Stroke",
        "system_category": "condition",
        "ccsr_body_systems": ["Nervous system"],
        "ccsr_categories": ["NVS010"]
      },
      "metadata": {
        "num_findings": 42,
        "num_studies": 18,
        "last_published_date": "2023-09-15T00:00:00Z",
        "highest_cited": 3200,
        "highest_sample_size": 50000,
        "num_experimental_trials": 5,
        "median_effect_size": 1.45,
        "num_significant_findings": 30,
        "last_updated": "2024-01-10T12:00:00Z"
      }
    },
    {
      "relationship_id": "rel_def456",
      "from_concept": {
        "cui": "C0011849",
        "preferred_name": "Diabetes Mellitus",
        "system_category": "condition",
        "ccsr_body_systems": ["Endocrine system"],
        "ccsr_categories": ["END010"]
      },
      "to_concept": {
        "cui": "C0020538",
        "preferred_name": "Hypertension",
        "system_category": "condition",
        "ccsr_body_systems": ["Circulatory system"],
        "ccsr_categories": ["CIR009"]
      },
      "metadata": {
        "num_findings": 25,
        "num_studies": 10,
        "last_published_date": "2022-11-01T00:00:00Z",
        "highest_cited": 1500,
        "highest_sample_size": 20000,
        "num_experimental_trials": 2,
        "median_effect_size": 1.20,
        "num_significant_findings": 18,
        "last_updated": "2024-02-05T08:00:00Z"
      }
    }
  ],
  "total": 2
}

---

Data Models

Relationship

The core object returned by the relationships endpoints.

Field	Type	Required	Description
relationship_id	string	✅ Yes	Unique identifier of the relationship
from_concept	Concept	✅ Yes	Source concept of the relationship
to_concept	Concept	✅ Yes	Target concept of the relationship
metadata	RelationshipMetadata	No	Metadata about the relationship

Concept

A clinical concept node in a relationship.

Field	Type	Required	Description
cui	string	No	UMLS Concept Unique Identifier (CUI)
preferred_name	string	No	System concept preferred name
system_category	string	No	System category of the concept
ccsr_body_systems	string[]	No	List of CCSR body systems associated with the concept
ccsr_categories	string[]	No	List of CCSR categories associated with the concept

RelationshipMetadata

Additional metadata providing evidence context for a relationship.

Field	Type	Required	Description
num_findings	integer	No	Number of findings on the relationship
num_studies	integer	No	Number of studies supporting the relationship
last_published_date	string (datetime)	No	Date of the most recent publication supporting the relationship
highest_cited	integer	No	Citation count of the highest cited study supporting the relationship
highest_sample_size	integer	No	Highest sample size of studies supporting the relationship
num_experimental_trials	integer	No	Number of experimental trials supporting the relationship
median_effect_size	number	No	Median effect size of findings on the relationship
num_significant_findings	integer	No	Number of statistically significant findings on the relationship
last_updated	string (datetime)	No	Date the relationship was last updated

ListResponse[Relationship]

The paginated list response wrapper returned by GET /v1/relationships.

Field	Type	Required	Description
data	Relationship[]	✅ Yes	Array of relationship objects
total	integer	No	Total number of matching records (included when include_total=true)

---

Error Handling

422 Validation Error

Returned when request parameters or body fail validation.

Response Schema:

{
  "detail": [
    {
      "loc": ["query", "limit"],
      "msg": "value is not a valid integer",
      "type": "type_error.integer"
    }
  ]
}

Field	Type	Description
loc	array	Location of the error (e.g., field name or path)
msg	string	Human-readable error message
type	string	Error type identifier

404 Not Found

Returned when the requested relationship_id does not exist.

{
  "detail": "Not found"
}

---

Code Examples

cURL

Get a relationship by ID:

curl -X GET "https://cg-api-prod.system.com/v1/relationships/rel_abc123" \
  -H "x-api-key: YOUR_API_KEY"

Get a list of relationships with pagination:

curl -X GET "https://cg-api-prod.system.com/v1/relationships?limit=10&offset=0&include_total=true" \
  -H "x-api-key: YOUR_API_KEY"

Filter by relationship ID:

curl -X GET "https://cg-api-prod.system.com/v1/relationships?filter=relationship_id:rel_abc123" \
  -H "x-api-key: YOUR_API_KEY"

Python (requests)

Get a relationship by ID:

import requests
API_KEY = "YOUR_API_KEY"
BASE_URL = "https://cg-api-prod.system.com"
headers = {
    "x-api-key": API_KEY
}
response = requests.get(
    f"{BASE_URL}/v1/relationships/rel_abc123",
    headers=headers
)
if response.status_code == 200:
    relationship = response.json()
    print(relationship)
else:
    print(f"Error {response.status_code}: {response.text}")

Get a paginated list of relationships:

import requests
API_KEY = "YOUR_API_KEY"
BASE_URL = "https://cg-api-prod.system.com"
headers = {
    "x-api-key": API_KEY
}
params = {
    "limit": 10,
    "offset": 0,
    "include_total": True
}
response = requests.get(
    f"{BASE_URL}/v1/relationships",
    headers=headers,
    params=params
)
if response.status_code == 200:
    data = response.json()
    print(f"Total records: {data.get('total')}")
    for rel in data["data"]:
        print(rel["relationship_id"])
else:
    print(f"Error {response.status_code}: {response.text}")

Filter by relationship ID:

import requests
API_KEY = "YOUR_API_KEY"
BASE_URL = "https://cg-api-prod.system.com"
headers = {
    "x-api-key": API_KEY
}
params = {
    "filter": "relationship_id:rel_abc123||rel_def456",
    "include_total": True
}
response = requests.get(
    f"{BASE_URL}/v1/relationships",
    headers=headers,
    params=params
)
data = response.json()
print(data)

JavaScript (fetch)

Get a relationship by ID:

const API_KEY = "YOUR_API_KEY";
const BASE_URL = "https://cg-api-prod.system.com";
async function getRelationship(relationshipId) {
  const response = await fetch(
    `${BASE_URL}/v1/relationships/${relationshipId}`,
    {
      method: "GET",
      headers: {
        "x-api-key": API_KEY,
      },
    }
  );
  if (!response.ok) {
    throw new Error(`HTTP error: ${response.status}`);
  }
  const relationship = await response.json();
  console.log(relationship);
  return relationship;
}
getRelationship("rel_abc123");

Get a list of relationships:

const API_KEY = "YOUR_API_KEY";
const BASE_URL = "https://cg-api-prod.system.com";
async function getRelationships(params = {}) {
  const queryString = new URLSearchParams({
    limit: 10,
    offset: 0,
    include_total: true,
    ...params,
  }).toString();
  const response = await fetch(
    `${BASE_URL}/v1/relationships?${queryString}`,
    {
      method: "GET",
      headers: {
        "x-api-key": API_KEY,
      },
    }
  );
  if (!response.ok) {
    throw new Error(`HTTP error: ${response.status}`);
  }
  const data = await response.json();
  console.log(`Total: ${data.total}`);
  console.log(data.data);
  return data;
}
getRelationships({ limit: 5 });

---