# Custom Integration API

## Overview

{% hint style="info" %}

* This feature is available with the **Paradime Enterprise pack**. 
* Your API keys ***must*** have the [Custom Integrations Admin capability](/app-help/developers/generate-api-keys.md)**.**
  {% endhint %}

The Customer Integration API empowers users to seamlessly extend Paradime's [lineage](/app-help/documentation/data-catalog/lineage.md) and [catalog](/app-help/documentation/data-catalog.md) capabilities with external applications. This powerful interface enables you to:

* Create custom integrations tailored to your specific needs
* Ingest and manage nodes from various data sources and applications
* Upload node information for Paradime to incorporate into its lineage and catalog
* Enhance data visibility by connecting Paradime with your entire data ecosystem

By leveraging this API, you can create a comprehensive, interconnected view of your data landscape, improving data governance, traceability, and insights across your organization. 

## Registering a New Integration

The `integrationUid` in the response will be used in later APIs. This enpoint needs to be called only once when registering a new type of integration.

#### Defining color for a node:

The `color` can be one defined from one of the provided color pallets:

* VIOLET  `#827be6`
* ORANGE `#fb982e`
* MANDY `#ef6292`
* TEAL `#33a9a9`
* GREEN `#27ae60`

#### Defining icon for a node:

* `icon_name` can be chosen from [Blueprint.js icons library](https://blueprintjs.com/docs/#icons/icons-list)

### Example request

{% tabs %}
{% tab title="GraphQL" %}

```python
import requests
import os

# API credentials
api_endpoint = "<YOUR_API_ENDPOINT>"
api_key = "<YOUR_API_KEY>"
api_secret = "<YOUR_API_SECRET>"

graphql_query = """
mutation {
  addCustomIntegration(
    logoUrl: "https://example.com/logo.png"
    name: "Sample Integration"
    nodeTypes: [
      {
        nodeType: "Type1"
        iconName: "icon1"
        color: CYAN
      }
      {
        nodeType: "Type2"
        iconName: "icon2"
        color: VIOLET
      }
    ]
  ) {
    ok
    integrationUid
  }
}
  """
  
response = requests.post(api_endpoint, json={"query": graphql_query}, headers={
      "Content-Type": "application/json",
      "X-API-KEY": api_key,
      "X-API-SECRET": api_secret,
  })

print(response.json())
```

{% endtab %}

{% tab title="cURL" %}

```bash
curl -X POST "<YOUR_API_ENDPOINT>" \
     -H "Content-Type: application/json" \
     -H "X-API-KEY: <YOUR_API_KEY>" \
     -H "X-API-SECRET: <YOUR_API_SECRET>" \
     -d '{
       "query": "mutation AddCustomIntegration($logoUrl: String!, $name: String!, $nodeTypes: [NodeTypeInput!]!) { addCustomIntegration(logoUrl: $logoUrl, name: $name, nodeTypes: $nodeTypes) { ok integrationUid } }",
       "variables": {
         "logoUrl": "https://example.com/logo.png",
         "name": "Sample Integration",
         "nodeTypes": [
           {
             "nodeType": "Type1",
             "iconName": "icon1",
             "color": "CYAN"
           },
           {
             "nodeType": "Type2",
             "iconName": "icon2",
             "color": "VIOLET"
           }
         ]
       }
     }'
```

{% endtab %}
{% endtabs %}

<details>

<summary><strong>Example response</strong></summary>

```json
{
  "data": {
    "addCustomIntegration": {
      "ok": true,
      "integrationUid": "uuid-422324"
    }
  }
}
```

The `integrationUid` from above will be used in later APIs. The above api needs to be called only once when registering a new type of integration.

</details>

## Adding nodes to an integration

Update a custom integration with the specified parameters.

### Example request

{% tabs %}
{% tab title="GraphQL" %}

```python
```

{% endtab %}

{% tab title="cURL" %}

```bash
// Some code
```

{% endtab %}
{% endtabs %}

<details>

<summary><strong>Example response</strong></summary>

```json
// Some code
```

</details>

## List Custom Integrations

Retrieves a list of all custom integrations. This includes both active and inactive integrations.

### Example request

{% tabs %}
{% tab title="GraphQL" %}

```python
import requests
import os

# API credentials
api_endpoint = "<YOUR_API_ENDPOINT>"
api_key = "<YOUR_API_KEY>"
api_secret = "<YOUR_API_SECRET>"

graphql_query = """
query {
  listCustomIntegrations {
    ok
    integrations {
      uid
      name
      logoBase64
      isActive
      nodeTypes {
        nodeType
        iconName
        color
      }
    }
  }
}
  """
  
response = requests.post(api_endpoint, json={"query": graphql_query}, headers={
      "Content-Type": "application/json",
      "X-API-KEY": api_key,
      "X-API-SECRET": api_secret,
  })

print(response.json())
```

{% endtab %}

{% tab title="cURL" %}

```bash
curl -X POST "<YOUR_API_ENDPOINT>" \
     -H "Content-Type: application/json" \
     -H "X-API-KEY: <YOUR_API_KEY>" \
     -H "X-API-SECRET: <YOUR_API_SECRET>" \
     -d '{
       "query": "query ListCustomIntegrations { listCustomIntegrations { ok integrations { uid name logoBase64 isActive nodeTypes { nodeType iconName color } } } }"
     }'
```

{% endtab %}
{% endtabs %}

<details>

<summary><strong>Example response</strong></summary>

```json
{
  "data": {
    "listCustomIntegrations": {
      "ok": true,
      "integrations": [
        {
          "uid": "abc123",
          "name": "Sample Integration 1",
          "logoBase64": "base64encodedlogoimage",
          "isActive": true,
          "nodeTypes": [
            {
              "nodeType": "NodeType1",
              "iconName": "icon1",
              "color": "CYAN"
            },
            {
              "nodeType": "NodeType2",
              "iconName": "icon2",
              "color": "VIOLET"
            }
          ]
        },
        {
          "uid": "def456",
          "name": "Sample Integration 2",
          "logoBase64": "base64encodedlogoimage",
          "isActive": false,
          "nodeTypes": [
            {
              "nodeType": "NodeType3",
              "iconName": "icon3",
              "color": "GREEN"
            }
          ]
        }
      ]
    }
  }
}
```

</details>


---

# 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.paradime.io/app-help/developers/graphql-api/examples/custom-integration-api.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.