> ## Documentation Index
> Fetch the complete documentation index at: https://docs.paradime.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Custom Integration API

### Overview

<Info>
  **Prerequisites:**

  * This feature is available with the **Paradime Enterprise pack**.
  * Your API keys ***must*** have the Custom Integrations Admin capability**.**
</Info>

<Info>
  The examples below authenticate with an **account API key** — pass `Authorization: Bearer <token>` and `X-Paradime-Workspace: <workspace_uid>` (the account key starts with `prdm_cmp_`). Legacy **workspace API keys** are still supported: send `X-API-KEY` and `X-API-SECRET` headers instead. See API Keys.
</Info>

The Customer Integration API empowers users to seamlessly extend Paradime's lineage and catalog 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 theme={"system"}
    import requests
    import os

    # API credentials
    api_endpoint = "<YOUR_API_ENDPOINT>"
    api_token = "<YOUR_API_TOKEN>"          # account API key (starts with prdm_cmp_)
    workspace_uid = "<YOUR_WORKSPACE_UID>"

    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",
          "Authorization": f"Bearer {api_token}",
          "X-Paradime-Workspace": workspace_uid,
      })

    print(response.json())
    ```
  </Tab>

  <Tab title="cURL">
    ```bash theme={"system"}
    curl -X POST "<YOUR_API_ENDPOINT>" \
         -H "Content-Type: application/json" \
         -H "Authorization: Bearer <YOUR_API_TOKEN>" \
         -H "X-Paradime-Workspace: <YOUR_WORKSPACE_UID>" \
         -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"
               }
             ]
           }
         }'
    ```
  </Tab>
</Tabs>

<Accordion title="Example response">
  ```json theme={"system"}
  {
    "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.
</Accordion>

### Adding nodes to an integration

Update a custom integration with the specified parameters.

#### Example request

<Tabs>
  <Tab title="GraphQL">
    ```python theme={"system"}
    ```
  </Tab>

  <Tab title="cURL">
    ```bash theme={"system"}
    // Some code
    ```
  </Tab>
</Tabs>

<Accordion title="Example response">
  ```json theme={"system"}
  // Some code
  ```
</Accordion>

### List Custom Integrations

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

#### Example request

<Tabs>
  <Tab title="GraphQL">
    ```python theme={"system"}
    import requests
    import os

    # API credentials
    api_endpoint = "<YOUR_API_ENDPOINT>"
    api_token = "<YOUR_API_TOKEN>"          # account API key (starts with prdm_cmp_)
    workspace_uid = "<YOUR_WORKSPACE_UID>"

    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",
          "Authorization": f"Bearer {api_token}",
          "X-Paradime-Workspace": workspace_uid,
      })

    print(response.json())
    ```
  </Tab>

  <Tab title="cURL">
    ```bash theme={"system"}
    curl -X POST "<YOUR_API_ENDPOINT>" \
         -H "Content-Type: application/json" \
         -H "Authorization: Bearer <YOUR_API_TOKEN>" \
         -H "X-Paradime-Workspace: <YOUR_WORKSPACE_UID>" \
         -d '{
           "query": "query ListCustomIntegrations { listCustomIntegrations { ok integrations { uid name logoBase64 isActive nodeTypes { nodeType iconName color } } } }"
         }'
    ```
  </Tab>
</Tabs>

<Accordion title="Example response">
  ```json theme={"system"}
  {
    "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"
              }
            ]
          }
        ]
      }
    }
  }
  ```
</Accordion>


## Related topics

- [API Reference](/developers/graphql-api/api-reference/index.md)
- [GraphQL API](/developers/graphql-api/index.md)
- [Custom Integration](/developers/python-sdk/modules/custom-integration.md)
- [API Keys](/developers/api-keys.md)
- [Generate API Keys (Legacy)](/developers/generate-api-keys-legacy.md)