# 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 |

{% hint style="info" %}
Example header:

```
x-api-key: YOUR_API_KEY
```

{% endhint %}

***

{% stepper %}
{% step %}

### Get a Relationship by ID

Retrieve a single relationship by its unique identifier.

GET /v1/relationships/{relationship\_id}

#### Path Parameters

<table><thead><tr><th width="155.37890625">Parameter</th><th>Type</th><th>Required</th><th>Description</th></tr></thead><tbody><tr><td>relationship_id</td><td>string</td><td>✅ Yes</td><td>Unique identifier of the relationship</td></tr></tbody></table>

#### 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

```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"
  }
}
```

{% endstep %}

{% step %}

### 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

```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
}
```

{% endstep %}
{% endstepper %}

***

## 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:

```json
{
  "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.

```json
{
  "detail": "Not found"
}
```

***

## Code Examples

### cURL

Get a relationship by ID:

```bash
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:

```bash
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:

```bash
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:

```python
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:

```python
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:

```python
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:

```javascript
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:

```javascript
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 });
```

***


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.system.com/system/api-docs/graph.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.