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

# DataGalaxy

> Manage DataGalaxy data catalog from Prisme.ai workflows and AI agents

The DataGalaxy app provides full read/write access to the DataGalaxy data catalog API. It can be used either as a Builder app (automations call DataGalaxy instructions directly) or as a remote MCP server consumed by an Knowledges agent.

<CardGroup cols={3}>
  <Card title="Catalog Management" icon="book">
    Sources, containers, structures, fields, glossary, usages, data processing
  </Card>

  <Card title="Links & Collaboration" icon="link">
    Relationships, comments and tasks across any catalog entity
  </Card>

  <Card title="Dual Interface" icon="plug">
    Use as Builder app or MCP server exposed to agents
  </Card>
</CardGroup>

## Prerequisites

* A **DataGalaxy account** with API access
* A **Personal Access Token (PAT)** or **integration token**
* The **DataGalaxy API base URL** (default: `https://api.datagalaxy.com`)

***

<Tabs>
  <Tab title="Usage as App">
    ## Installation

    1. Go to **Apps** in your workspace
    2. Search for **DataGalaxy** and install it
    3. Open the app instance configuration and fill in the required fields

    ## Configuration

    | Field                       | Description                                                                            |
    | --------------------------- | -------------------------------------------------------------------------------------- |
    | **DataGalaxy API Base URL** | Base URL of the DataGalaxy API (default `https://api.datagalaxy.com`)                  |
    | **Authentication Token**    | PAT or integration token, stored as a workspace secret                                 |
    | **MCP Endpoint**            | Auto-populated on install — URL of the MCP endpoint for this instance                  |
    | **MCP API Key**             | Auto-populated on install — signed key used in the `mcp-api-key` header. Do not modify |

    <Note>
      `MCP Endpoint` and `MCP API Key` are generated automatically by the `onInstall` flow and are only needed if you intend to expose this instance as an MCP server (see the next tab).
    </Note>

    ## Available Instructions

    Every instruction resolves credentials from the workspace configuration via `buildAppAuth`. Unless stated otherwise, all IDs use DataGalaxy's DoubleUuid format and `versionId` refers to a workspace version ID returned by `listVersions`.

    ### Search & Workspaces

    | Instruction      | Arguments                                | Description                                                                          |
    | ---------------- | ---------------------------------------- | ------------------------------------------------------------------------------------ |
    | `search`         | `query`, `versionId`, `limit`, `filters` | Search across all DataGalaxy objects by name, technical name, description or summary |
    | `listWorkspaces` | –                                        | List all DataGalaxy workspaces accessible to the authenticated user                  |
    | `listVersions`   | `workspaceId`                            | List all versions of a DataGalaxy workspace                                          |
    | `listAttributes` | –                                        | List all attributes (custom and built-in) defined in your DataGalaxy client space    |

    ### Generic Object Operations

    | Instruction    | Arguments                                                                                                          | Description                                                |
    | -------------- | ------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------- |
    | `getObject`    | `versionId`, `objectId`                                                                                            | Get details of any DataGalaxy object by its ID and version |
    | `updateObject` | `versionId`, `objectId`, `name`, `status`, `description`, `summary`, `owners`, `stewards`, `tags`, `technicalName` | Update attributes of any DataGalaxy object                 |

    `status` accepts `Proposed`, `InRevision`, `Validated`, `InValidation`, `Obsolete`.

    ### Sources

    | Instruction    | Arguments                                                                                                          |
    | -------------- | ------------------------------------------------------------------------------------------------------------------ |
    | `listSources`  | `versionId`, `limit`, `page`, `includeAttributes`                                                                  |
    | `getSource`    | `versionId`, `sourceId`                                                                                            |
    | `createSource` | `versionId`, `name`, `type`, `technicalName`, `description`, `summary`, `owners`, `stewards`, `tags`, `status`     |
    | `updateSource` | `versionId`, `sourceId`, `name`, `technicalName`, `description`, `summary`, `owners`, `stewards`, `tags`, `status` |
    | `deleteSource` | `versionId`, `sourceId`                                                                                            |

    ### Containers

    | Instruction       | Arguments                                                                                                                  |
    | ----------------- | -------------------------------------------------------------------------------------------------------------------------- |
    | `listContainers`  | `versionId`, `parentId`, `limit`, `page`, `includeAttributes`                                                              |
    | `getContainer`    | `versionId`, `containerId`                                                                                                 |
    | `createContainer` | `versionId`, `parentId`, `name`, `type`, `technicalName`, `description`, `summary`, `owners`, `stewards`, `tags`, `status` |
    | `updateContainer` | `versionId`, `containerId`, `name`, `technicalName`, `description`, `summary`, `owners`, `stewards`, `tags`, `status`      |
    | `deleteContainer` | `versionId`, `containerId`                                                                                                 |

    `type` accepts `Model`, `Directory`, `Equipment`.

    ### Structures

    | Instruction       | Arguments                                                                                                                  |
    | ----------------- | -------------------------------------------------------------------------------------------------------------------------- |
    | `listStructures`  | `versionId`, `parentId`, `limit`, `page`, `includeAttributes`                                                              |
    | `getStructure`    | `versionId`, `structureId`                                                                                                 |
    | `createStructure` | `versionId`, `parentId`, `name`, `type`, `technicalName`, `description`, `summary`, `owners`, `stewards`, `tags`, `status` |
    | `updateStructure` | `versionId`, `structureId`, `name`, `technicalName`, `description`, `summary`, `owners`, `stewards`, `tags`, `status`      |
    | `deleteStructure` | `versionId`, `structureId`                                                                                                 |

    `type` accepts `Table`, `Document`, `File`, `SubStructure`, `Tag`, `View`.

    ### Fields

    | Instruction   | Arguments                                                                                                                                               |
    | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
    | `listFields`  | `versionId`, `parentId`, `limit`, `page`, `includeAttributes`                                                                                           |
    | `getField`    | `versionId`, `fieldId`                                                                                                                                  |
    | `createField` | `versionId`, `structureId`, `name`, `type`, `technicalName`, `description`, `summary`, `columnDataType`, `size`, `owners`, `stewards`, `tags`, `status` |
    | `updateField` | `versionId`, `fieldId`, `name`, `technicalName`, `description`, `summary`, `columnDataType`, `size`, `owners`, `stewards`, `tags`, `status`             |
    | `deleteField` | `versionId`, `fieldId`                                                                                                                                  |

    `type` accepts `Column`, `Field`. `columnDataType` is free-form (e.g. `varchar`, `int`, `date`).

    ### Glossary Properties

    | Instruction      | Arguments                                                                                                                  |
    | ---------------- | -------------------------------------------------------------------------------------------------------------------------- |
    | `listProperties` | `versionId`, `limit`, `page`, `includeAttributes`                                                                          |
    | `getProperty`    | `versionId`, `propertyId`                                                                                                  |
    | `createProperty` | `versionId`, `parentId`, `name`, `type`, `technicalName`, `description`, `summary`, `owners`, `stewards`, `tags`, `status` |
    | `updateProperty` | `versionId`, `propertyId`, `name`, `technicalName`, `description`, `summary`, `owners`, `stewards`, `tags`, `status`       |
    | `deleteProperty` | `versionId`, `propertyId`                                                                                                  |

    `type` accepts `Universe`, `BusinessDomain`, `BusinessDomainGroup`, `ReferenceData`, `ReferenceDataValue`, `Dimension`, `DimensionGroup`, `Concept`, `Indicator`, `IndicatorGroup`, `BusinessTerm`.

    ### Usages

    | Instruction   | Arguments                                                                                                                  |
    | ------------- | -------------------------------------------------------------------------------------------------------------------------- |
    | `listUsages`  | `versionId`, `limit`, `page`, `includeAttributes`                                                                          |
    | `getUsage`    | `versionId`, `usageId`                                                                                                     |
    | `createUsage` | `versionId`, `parentId`, `name`, `type`, `technicalName`, `description`, `summary`, `owners`, `stewards`, `tags`, `status` |
    | `updateUsage` | `versionId`, `usageId`, `name`, `technicalName`, `description`, `summary`, `owners`, `stewards`, `tags`, `status`          |
    | `deleteUsage` | `versionId`, `usageId`                                                                                                     |

    `type` accepts `Application`, `Algorithm`, `Dashboard`, `Feature`, `DataSet`, `OpenDataSet`, `Screen`, `Process`, `Report`, `Usage`, `UsageField`, `UsageComponent`.

    ### Data Processing

    | Instruction            | Arguments                                                                                                                  |
    | ---------------------- | -------------------------------------------------------------------------------------------------------------------------- |
    | `listDataProcessing`   | `versionId`, `limit`, `page`, `includeAttributes`                                                                          |
    | `getDataProcessing`    | `versionId`, `dataProcessingId`                                                                                            |
    | `createDataProcessing` | `versionId`, `parentId`, `name`, `type`, `technicalName`, `description`, `summary`, `owners`, `stewards`, `tags`, `status` |
    | `updateDataProcessing` | `versionId`, `dataProcessingId`, `name`, `technicalName`, `description`, `summary`, `owners`, `stewards`, `tags`, `status` |
    | `deleteDataProcessing` | `versionId`, `dataProcessingId`                                                                                            |

    `type` accepts `DataFlow`, `DataProcessing`.

    ### Links

    | Instruction  | Arguments                                 | Description                                  |
    | ------------ | ----------------------------------------- | -------------------------------------------- |
    | `getLinks`   | `versionId`, `fromId`                     | Get all links (relationships) from an entity |
    | `createLink` | `versionId`, `fromId`, `toId`, `type`     | Create a link between two entities           |
    | `deleteLink` | `versionId`, `fromId`, `linkType`, `toId` | Delete a link between two entities           |

    ### Comments

    | Instruction     | Arguments                          | Description                                |
    | --------------- | ---------------------------------- | ------------------------------------------ |
    | `listComments`  | `versionId`, `entityId`            | List comments on an entity                 |
    | `createComment` | `versionId`, `entityId`, `content` | Create a comment (supports rich text HTML) |

    ### Tasks

    | Instruction  | Arguments                                                                       | Description                             |
    | ------------ | ------------------------------------------------------------------------------- | --------------------------------------- |
    | `listTasks`  | –                                                                               | List tasks assigned to the current user |
    | `createTask` | `versionId`, `entityId`, `title`, `description`, `type`, `assignee`, `status`   | Create a task on an entity              |
    | `updateTask` | `versionId`, `entityId`, `taskId`, `title`, `description`, `status`, `assignee` | Update an existing task                 |

    ## DSUL Examples

    ### Search the Catalog

    ```yaml theme={null}
    - DataGalaxy.search:
        query: customer
        versionId: '{{versionId}}'
        limit: 20
        output: results
    ```

    ### List Workspaces and Versions

    ```yaml theme={null}
    - DataGalaxy.listWorkspaces:
        output: workspaces
    - DataGalaxy.listVersions:
        workspaceId: '{{workspaces[0].id}}'
        output: versions
    ```

    ### Create a Source

    ```yaml theme={null}
    - DataGalaxy.createSource:
        versionId: '{{versionId}}'
        name: Customer Database
        type: Database
        technicalName: customer_db
        description: Production customer database
        owners:
          - alice@example.com
        status: Validated
        output: source
    ```

    ### Create a Structure and a Field

    ```yaml theme={null}
    - DataGalaxy.createStructure:
        versionId: '{{versionId}}'
        parentId: '{{containerId}}'
        name: customers
        type: Table
        output: structure
    - DataGalaxy.createField:
        versionId: '{{versionId}}'
        structureId: '{{structure.id}}'
        name: email
        type: Column
        columnDataType: varchar
        size: 255
        output: field
    ```

    ### Link Two Entities and Comment

    ```yaml theme={null}
    - DataGalaxy.createLink:
        versionId: '{{versionId}}'
        fromId: '{{field.id}}'
        toId: '{{businessTermId}}'
        type: implements
    - DataGalaxy.createComment:
        versionId: '{{versionId}}'
        entityId: '{{field.id}}'
        content: <p>Linked to business term.</p>
    ```
  </Tab>

  <Tab title="Usage as MCP">
    The DataGalaxy app ships with a built-in MCP server. Each app instance gets its own signed `mcp-api-key` that encodes the workspace ID and a credentials lookup URL, so no DataGalaxy token is ever passed through headers — credentials are resolved server-side from the app configuration.

    ## Legacy MCP Install (Advanced > Tools)

    Use this flow to plug the DataGalaxy MCP into an Knowledges agent that does not yet support the native MCP picker.

    <Steps>
      <Step title="Install the DataGalaxy app">
        Install and configure the app in the same workspace as your agent (see the *Usage as App* tab). Once configured, `mcpEndpoint` and `mcpApiKey` are auto-populated.
      </Step>

      <Step title="Copy the MCP credentials">
        Open the app instance config and copy the values of **MCP Endpoint** and **MCP API Key**.
      </Step>

      <Step title="Open your Knowledges project">
        Navigate to **Advanced > Tools**.
      </Step>

      <Step title="Add an MCP tool">
        Click **Add** and select the **MCP** tab.
      </Step>

      <Step title="Fill in the endpoint">
        Paste the **MCP Endpoint** URL copied from the app instance.
      </Step>

      <Step title="Add the auth header">
        In the **Headers** field, add the signed API key:

        ```json theme={null}
        {
          "mcp-api-key": "your-mcp-api-key"
        }
        ```
      </Step>

      <Step title="Save">
        The agent can now list and call DataGalaxy tools through the MCP endpoint.
      </Step>
    </Steps>

    <Note>
      The signed `mcp-api-key` encodes the workspace ID and the `getConfig` webhook URL. The MCP server validates the signature using the central app secret and transparently fetches the DataGalaxy `accessToken` and `baseUrl` from the installed app. Credentials are cached per tenant for 10 minutes.
    </Note>

    ## Runtime Credential Override

    At tool-call time, the MCP server resolves credentials in the following order:

    1. `Authorization: Bearer <token>` header (optional `x-datagalaxy-url` for the base URL)
    2. Session credentials set via the `configureDataGalaxy` tool
    3. Workspace-level credentials from the installed app

    This lets you either rely on the installed app configuration or override with per-session credentials from the agent.

    ## Available Tools

    ### Configuration

    | Tool                  | Description                                                                                |
    | --------------------- | ------------------------------------------------------------------------------------------ |
    | `configureDataGalaxy` | Store DataGalaxy PAT (and optional base URL) in the user session for subsequent tool calls |

    ### Search & Workspaces

    | Tool             | Description                           |
    | ---------------- | ------------------------------------- |
    | `search`         | Search across all DataGalaxy objects  |
    | `listWorkspaces` | List accessible DataGalaxy workspaces |
    | `listVersions`   | List versions of a workspace          |
    | `listAttributes` | List attributes (custom and built-in) |

    ### Generic Object Operations

    | Tool           | Description                      |
    | -------------- | -------------------------------- |
    | `getObject`    | Get any object by ID and version |
    | `updateObject` | Update attributes of any object  |

    ### Sources, Containers, Structures, Fields

    | Tool                                                                                          | Description                            |
    | --------------------------------------------------------------------------------------------- | -------------------------------------- |
    | `listSources` / `getSource` / `createSource` / `updateSource` / `deleteSource`                | Manage top-level dictionary entities   |
    | `listContainers` / `getContainer` / `createContainer` / `updateContainer` / `deleteContainer` | Manage databases, schemas, directories |
    | `listStructures` / `getStructure` / `createStructure` / `updateStructure` / `deleteStructure` | Manage tables, views, documents        |
    | `listFields` / `getField` / `createField` / `updateField` / `deleteField`                     | Manage columns and fields              |

    ### Glossary, Usage, Data Processing

    | Tool                                                                                                                  | Description                                                          |
    | --------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------- |
    | `listProperties` / `getProperty` / `createProperty` / `updateProperty` / `deleteProperty`                             | Manage glossary properties (business terms, concepts, indicators, …) |
    | `listUsages` / `getUsage` / `createUsage` / `updateUsage` / `deleteUsage`                                             | Manage usage entities (applications, dashboards, datasets, …)        |
    | `listDataProcessing` / `getDataProcessing` / `createDataProcessing` / `updateDataProcessing` / `deleteDataProcessing` | Manage data flows and processing entities                            |

    ### Links, Comments, Tasks

    | Tool                                      | Description                               |
    | ----------------------------------------- | ----------------------------------------- |
    | `getLinks` / `createLink` / `deleteLink`  | Manage relationships between entities     |
    | `listComments` / `createComment`          | List and post comments on an entity       |
    | `listTasks` / `createTask` / `updateTask` | Manage tasks assigned to the current user |

    ## Tool Details

    ### configureDataGalaxy

    Store DataGalaxy credentials in the user session. Takes precedence over the installed app configuration for the current session.

    ```json theme={null}
    {
      "name": "configureDataGalaxy",
      "arguments": {
        "token": "your-datagalaxy-pat",
        "baseUrl": "https://api.datagalaxy.com"
      }
    }
    ```

    | Parameter | Required | Description                                             |
    | --------- | -------- | ------------------------------------------------------- |
    | `token`   | Yes      | DataGalaxy PAT or integration token                     |
    | `baseUrl` | No       | API base URL (defaults to `https://api.datagalaxy.com`) |

    ### search

    ```json theme={null}
    {
      "name": "search",
      "arguments": {
        "query": "customer",
        "versionId": "abcd-1234...",
        "limit": 50,
        "filters": [
          { "attributeKey": "Status", "operator": "equals", "values": ["Validated"] }
        ]
      }
    }
    ```

    | Parameter   | Required | Description                                                |
    | ----------- | -------- | ---------------------------------------------------------- |
    | `query`     | Yes      | Search query text                                          |
    | `versionId` | No       | Scope the search to a workspace version                    |
    | `limit`     | No       | Max results (default: 50)                                  |
    | `filters`   | No       | Array of `{attributeKey, operator, values}` filter objects |

    ### createSource / updateSource / deleteSource

    ```json theme={null}
    {
      "name": "createSource",
      "arguments": {
        "versionId": "abcd-1234...",
        "name": "Customer Database",
        "type": "Database",
        "owners": ["alice@example.com"],
        "status": "Validated"
      }
    }
    ```

    See the *Usage as App* tab for the full argument list and enum values shared by create/update tools across sources, containers, structures, fields, properties, usages and data processing.

    ### createLink / deleteLink

    ```json theme={null}
    {
      "name": "createLink",
      "arguments": {
        "versionId": "abcd-1234...",
        "fromId": "field-id",
        "toId": "business-term-id",
        "type": "implements"
      }
    }
    ```

    ### createComment

    Rich text HTML is supported in the `content` field.

    ```json theme={null}
    {
      "name": "createComment",
      "arguments": {
        "versionId": "abcd-1234...",
        "entityId": "object-id",
        "content": "<p>Reviewed and validated.</p>"
      }
    }
    ```
  </Tab>
</Tabs>

***

## Error Handling

| HTTP Status | Error        | Solution                                                  |
| ----------- | ------------ | --------------------------------------------------------- |
| 401         | Unauthorized | Verify the PAT / integration token and `baseUrl`          |
| 403         | Forbidden    | Check DataGalaxy role and scopes on the workspace version |
| 404         | Not Found    | Verify `versionId`, `objectId` and parent IDs             |
| 429         | Rate Limited | Back off and retry with exponential delay                 |

### Common Issues

**"Not configured"** — No credentials could be resolved. Either complete the app install with a valid token, pass an `Authorization: Bearer` header, or call `configureDataGalaxy` before the first tool call.

**"Invalid API key"** — The `mcp-api-key` header does not match the central app secret. Reinstall the app instance to regenerate a signed key.

**"Credentials lookup failed"** — The MCP endpoint could not reach the `getConfig` webhook of the installed app. Verify that the app instance is still installed in the expected workspace.

## External Resources

<CardGroup cols={2}>
  <Card title="DataGalaxy API" icon="book" href="https://apidocs.datagalaxy.com">
    Official DataGalaxy API documentation
  </Card>

  <Card title="Tool Agents" icon="robot" href="/products/agent-factory/capabilities">
    Plug MCP servers into Knowledges agents
  </Card>
</CardGroup>