> ## Documentation Index
> Fetch the complete documentation index at: https://docs.prisme.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# DataGalaxy
> Read and write the DataGalaxy data catalog from Agent Factory agents and Builder workflows
The DataGalaxy app exposes the [DataGalaxy](https://www.datagalaxy.com) data catalog API. It can be consumed two ways: as a remote MCP server that **Agent Factory** agents call as tools, or as a Builder app whose instructions you call directly from DSUL. It covers the full catalog — dictionary (sources, containers, structures, fields), glossary, usages, data processings — plus links, comments and tasks, and a global search across every object.
Authentication is a single **DataGalaxy Personal Access Token (PAT) or integration token** stored in the workspace configuration: the connector exchanges it server-side for a short-lived access token. The credential is never exposed to the agent — agents are identified by the capability **Scope** `context_id,agent_id,user_id` and the connector resolves the token from its own app configuration.
Create, read, update and delete sources, containers, structures and fields, with the generic object operations for any entity type.
Manage glossary properties (business terms, concepts, indicators), usages (applications, dashboards, datasets) and data flows / processings.
Relate any two catalog entities, post comments and manage tasks across the catalog, with full-text search over everything.
## Who is this for?
This connector is used by three different roles. Jump to the section that matches yours — each one is self-contained.
You build agents in **Agent Factory** and want them to read and write the DataGalaxy catalog. → *Agent builder* tab.
You run the platform and want to publish DataGalaxy as a reusable capability. → *Platform admin setup* accordion below.
You write Builder automations (DSUL) that call DataGalaxy operations directly. → *Workspace builder* tab.
## Prerequisites
* A **DataGalaxy account** with API access to the workspaces (client spaces) you intend to manage.
* A **Personal Access Token (PAT)** or **integration token** — generated in DataGalaxy under your account / integration settings. The connector exchanges it server-side for a short-lived access token.
* Your **DataGalaxy API base URL** — default `https://api.datagalaxy.com` (override only for a region-specific or self-hosted instance).
* The token's user must hold the DataGalaxy roles needed for the operations you call (read for list/get, write for create/update/delete on the relevant workspace version).
**Goal:** DataGalaxy is a **per-workspace** connector — each workspace pastes its own DataGalaxy token in the app configuration (see the *Workspace builder* tab), so there is **no platform-wide credential to provision** and no central OAuth client.
There is no shared DataGalaxy credential. The PAT / integration token always lives in the consuming workspace's app configuration and is resolved server-side. A Governance capability you publish here points at a specific workspace's MCP endpoint; that workspace still owns the credential.
## Declare the capability in AI Governance (optional)
Create (or edit) the **DataGalaxy** capability.
Set the capability's MCP server URL to the connector's **MCP Endpoint** (the workspace running the connector), and set its **Scope** to:
```text theme={null}
context_id,agent_id,user_id
```
The `agent_id` in the scope is what lets the connector identify the calling agent.
Once created, the capability appears in the capability picker for agent builders in your organization, who enable it on their agents. Access to the catalog follows your organization's existing roles; there is no per-capability role grant for this connector.
Declaring the capability makes the connector **available**; it does not provision any credential. This connector resolves a single DataGalaxy token from the consuming workspace's app configuration — there is **no OAuth auth-config JSON** to attach in Governance and **no per-user OAuth flow**.
***
## Agent builder
**Goal:** let an agent you build in Agent Factory read and write the DataGalaxy catalog through MCP tools.
Before an agent can call the connector, a *Workspace builder* must have installed and configured the DataGalaxy app in a workspace (see the *Workspace builder* tab). Optionally, a *Platform admin* may have published a DataGalaxy capability in AI Governance (see the *Platform admin setup* accordion above).
The DataGalaxy credential is resolved server-side from the app configuration — never exposed to the agent. Your agent is identified by the `agent_id` that Agent Factory injects through the capability *Scope*.
Follow the *Workspace builder* tab: install **DataGalaxy** in a workspace and provide the PAT / integration token and (optionally) the base URL.
In your agent, add a capability pointing at that workspace's **MCP Endpoint** URL, and set its **Scope** to:
```text theme={null}
context_id,agent_id,user_id
```
The `agent_id` is what lets the connector identify your agent.
Tell the agent the tools exist and when to reach for them. Copy-pasteable starter:
```text theme={null}
You have access to the DataGalaxy MCP server. Use it whenever the user asks about catalog content — sources, containers, structures (tables), fields, glossary terms, usages, data processings, links, comments or tasks. Each tool takes an `action` argument selecting the concrete operation. Examples: "Find all glossary terms tagged GDPR" (catalog search), "List the structures of the Snowflake source", "Add a comment to the customer table", "Create a task to review the orders dataset". DataGalaxy IDs use the DoubleUuid format and most operations need a `versionId` (use the catalog tool's listWorkspaces / listVersions actions to discover it). Prefer calling a tool over guessing, and confirm with the user before any destructive action (delete a structure, remove a glossary term).
```
Refine the trigger keywords (source names, glossary domains, project tags) so the agent reliably picks up the right intent in your context.
**Legacy AI Knowledge agents** (no native MCP picker): add the connector under **Advanced > Tools > MCP** and paste the **MCP Endpoint** URL. The DataGalaxy token is still resolved server-side from the installed app configuration.
## Available Tools
Tools are **entity-grouped**: each tool takes an `action` argument selecting the concrete operation, plus the per-action parameters. Most operations need a `versionId` (a DataGalaxy workspace version) — discover it with the `catalog` tool.
| Tool | Description |
| ----------------- | -------------------------------------------------------------------------------------------------------------------- |
| `catalog` | Catalog metadata + global search. Actions: `listWorkspaces`, `listVersions`, `listAttributes`, `search`. |
| `sources` | Sources — top-level dictionary entities. Actions: `list`, `get`, `create`, `update`, `delete`. |
| `containers` | Containers (models, directories). Actions: `list`, `get`, `create`, `update`, `delete`. |
| `structures` | Structures (tables, datasets, views). Actions: `list`, `get`, `create`, `update`, `delete`. |
| `fields` | Fields (columns of a structure). Actions: `list`, `get`, `create`, `update`, `delete`. |
| `properties` | Glossary properties (business terms, concepts, indicators, …). Actions: `list`, `get`, `create`, `update`, `delete`. |
| `usages` | Usages (applications, dashboards, datasets, …). Actions: `list`, `get`, `create`, `update`, `delete`. |
| `dataProcessings` | Data flows and processings. Actions: `list`, `get`, `create`, `update`, `delete`. |
| `links` | Relationships between entities. Actions: `get`, `create`, `delete`. |
| `comments` | Comments on an entity (rich-text HTML). Actions: `list`, `create`. |
| `tasks` | Tasks assigned across the catalog. Actions: `list`, `create`, `update`. |
| `objects` | Generic object operations for any entity type. Actions: `get`, `update`. |
## Output Formats
Every tool accepts an `outputFormat` argument that controls the MCP response shape:
* **`verbose`** (default) — human-readable text optimized for LLM consumption
* **`structured`** — concise machine-readable JSON in `structuredContent`
* **`both`** — the structured payload, with its JSON also rendered as text
## Tool Details
### catalog — search
Global full-text search across every catalog object.
```json theme={null}
{
"name": "catalog",
"arguments": {
"action": "search",
"query": "customer",
"versionId": "abcd-1234...",
"limit": 50,
"filters": { "Status": ["Validated"] }
}
}
```
| Parameter | Required | Description |
| ------------- | ---------------- | -------------------------------------------------------------------- |
| `action` | Yes | One of `listWorkspaces`, `listVersions`, `listAttributes`, `search`. |
| `query` | For search | Search query text. |
| `versionId` | No | Scope the search to a workspace version. |
| `limit` | No | Max results. |
| `filters` | No | Attribute filter object. |
| `workspaceId` | For listVersions | Workspace (client space) id. |
### sources — create
```json theme={null}
{
"name": "sources",
"arguments": {
"action": "create",
"versionId": "abcd-1234...",
"name": "Customer Database",
"type": "Database",
"technicalName": "customer_db",
"owners": ["alice@example.com"],
"status": "Validated"
}
}
```
| Parameter | Required | Description |
| --------------------------------------------------------------------------------------- | --------------------- | ---------------------------------------------------------------------------------------------------------- |
| `action` | Yes | One of `list`, `get`, `create`, `update`, `delete`. |
| `versionId` | Yes | Workspace version id. |
| `name` | For create | Source display name. |
| `type` | For create | Entity type code (DataGalaxy-specific). |
| `sourceId` | For get/update/delete | Source id (UUID). |
| `technicalName` / `description` / `summary` / `status` / `owners` / `stewards` / `tags` | No | Standard catalog attributes (`status`: `Proposed`, `InRevision`, `Validated`, `InValidation`, `Obsolete`). |
### fields — create
Creates a field (column) under a structure.
```json theme={null}
{
"name": "fields",
"arguments": {
"action": "create",
"versionId": "abcd-1234...",
"structureId": "struct-id",
"name": "email",
"type": "Column",
"columnDataType": "varchar",
"size": 255
}
}
```
| Parameter | Required | Description |
| ---------------- | --------------------- | ---------------------------------------------------- |
| `action` | Yes | One of `list`, `get`, `create`, `update`, `delete`. |
| `versionId` | Yes | Workspace version id. |
| `structureId` | For create | Parent structure id. |
| `name` / `type` | For create | Field name and type code (`Column`, `Field`). |
| `columnDataType` | No | Free-form data type (e.g. `varchar`, `int`, `date`). |
| `size` | No | Column size. |
| `fieldId` | For get/update/delete | Field id (UUID). |
### links — create
```json theme={null}
{
"name": "links",
"arguments": {
"action": "create",
"versionId": "abcd-1234...",
"fromId": "field-id",
"toId": "business-term-id",
"type": "implements"
}
}
```
| Parameter | Required | Description |
| ----------- | ----------------- | --------------------------------- |
| `action` | Yes | One of `get`, `create`, `delete`. |
| `versionId` | Yes | Workspace version id. |
| `fromId` | Yes | Source entity id. |
| `toId` | For create/delete | Target entity id. |
| `type` | For create | Link type code. |
| `linkType` | For delete | Link type code to remove. |
### comments — create
Rich-text HTML is supported in the `content` field.
```json theme={null}
{
"name": "comments",
"arguments": {
"action": "create",
"versionId": "abcd-1234...",
"entityId": "object-id",
"content": "Reviewed and validated.
"
}
}
```
| Parameter | Required | Description |
| ----------- | ---------- | ---------------------------------------- |
| `action` | Yes | `list` or `create`. |
| `versionId` | Yes | Workspace version id. |
| `entityId` | Yes | Entity the comment is attached to. |
| `content` | For create | Comment body (rich-text HTML supported). |
## Workspace builder
**Goal:** install the connector in a workspace, paste your DataGalaxy token, and call catalog operations from your automations.
## 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 **Authentication Token** (and the base URL if it differs from the default)
## Configuration
| Field | Description |
| --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **DataGalaxy API Base URL** | Base URL of the DataGalaxy API (default `https://api.datagalaxy.com`). |
| **Authentication Token** | DataGalaxy PAT or integration token, stored as a workspace secret. Exchanged server-side for a short-lived access token. |
| **MCP Endpoint** | Auto-populated on install — the URL of the MCP endpoint for this instance, used when wiring the connector into an agent (see the *Agent builder* tab). |
The connector resolves its credential through the following order at call time:
| Source | What you provide | Best for |
| ---------------------------------------- | --------------------------------------------------------------------------------------------- | -------------------------------------------------------------- |
| Workspace configuration (default) | The **Authentication Token** in the app config | Standard setup — the token is exchanged server-side and cached |
| `configureDataGalaxy` session credential | A PAT (and optional base URL) stored in the session via the `configureDataGalaxy` instruction | Per-session override without changing the app config |
| `Authorization: Bearer` header | A caller-supplied access token (optional `x-datagalaxy-url` for the base URL) | Externally-minted / short-lived tokens |
All IDs use DataGalaxy's DoubleUuid format and `versionId` refers to a workspace version id returned by `listVersions`.
## Available Instructions
Every instruction resolves credentials from the workspace configuration.
### Search & Workspaces
| Instruction | Description | Returns |
| ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------- |
| `search` | Full-text search across all DataGalaxy objects by name, technical name, description or summary; optional `versionId`, `limit`, `filters`. | `{ results: [{ id, name, type, … }] }` |
| `listWorkspaces` | List all DataGalaxy workspaces (client spaces) accessible to the token. | `[{ id, name, … }]` |
| `listVersions` | List versions of a workspace by `workspaceId`. | `[{ id, versionName, … }]` |
| `listAttributes` | List all attributes (custom and built-in) defined in your client space. | `[{ attributeKey, dataType, … }]` |
### Generic Object Operations
| Instruction | Description | Returns |
| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------- |
| `getObject` | Get any object by `versionId` + `objectId`. | The object resource `{ id, name, type, … }` |
| `updateObject` | Update any object by `versionId` + `objectId` (`name`, `technicalName`, `description`, `summary`, `status`, `owners`, `stewards`, `tags`). | The updated object resource |
`status` accepts `Proposed`, `InRevision`, `Validated`, `InValidation`, `Obsolete`.
### Sources
| Instruction | Description | Returns |
| -------------- | ---------------------------------------------------------------------- | ----------------------- |
| `listSources` | List sources for a `versionId` (`limit`, `page`, `includeAttributes`). | `[{ id, name, … }]` |
| `getSource` | Get a source by `versionId` + `sourceId`. | The source resource |
| `createSource` | Create a source from `name` + `type` (+ standard attributes). | The created source |
| `updateSource` | Update a source by `sourceId`. | The updated source |
| `deleteSource` | Delete a source by `sourceId`. | Empty / acknowledgement |
### Containers
| Instruction | Description | Returns |
| ----------------- | --------------------------------------------------------------------------------------------- | ----------------------- |
| `listContainers` | List containers for a `versionId` (optional `parentId`). | `[{ id, name, … }]` |
| `getContainer` | Get a container by `containerId`. | The container resource |
| `createContainer` | Create a container under `parentId` from `name` + `type` (`Model`, `Directory`, `Equipment`). | The created container |
| `updateContainer` | Update a container by `containerId`. | The updated container |
| `deleteContainer` | Delete a container by `containerId`. | Empty / acknowledgement |
### Structures
| Instruction | Description | Returns |
| ----------------- | ---------------------------------------------------------------------------------------------------------------------- | ----------------------- |
| `listStructures` | List structures for a `versionId` (optional `parentId`). | `[{ id, name, … }]` |
| `getStructure` | Get a structure by `structureId`. | The structure resource |
| `createStructure` | Create a structure under `parentId` from `name` + `type` (`Table`, `Document`, `File`, `SubStructure`, `Tag`, `View`). | The created structure |
| `updateStructure` | Update a structure by `structureId`. | The updated structure |
| `deleteStructure` | Delete a structure by `structureId`. | Empty / acknowledgement |
### Fields
| Instruction | Description | Returns |
| ------------- | ------------------------------------------------------------------------------------------------------------ | ----------------------- |
| `listFields` | List fields for a `versionId` (optional `parentId`). | `[{ id, name, … }]` |
| `getField` | Get a field by `fieldId`. | The field resource |
| `createField` | Create a field under `structureId` from `name` + `type` (`Column`, `Field`), with `columnDataType` + `size`. | The created field |
| `updateField` | Update a field by `fieldId`. | The updated field |
| `deleteField` | Delete a field by `fieldId`. | Empty / acknowledgement |
### Glossary Properties
| Instruction | Description | Returns |
| ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------- |
| `listProperties` | List glossary properties for a `versionId`. | `[{ id, name, … }]` |
| `getProperty` | Get a property by `propertyId`. | The property resource |
| `createProperty` | Create a property under `parentId` from `name` + `type` (`Universe`, `BusinessDomain`, `ReferenceData`, `Concept`, `Indicator`, `BusinessTerm`, …). | The created property |
| `updateProperty` | Update a property by `propertyId`. | The updated property |
| `deleteProperty` | Delete a property by `propertyId`. | Empty / acknowledgement |
### Usages
| Instruction | Description | Returns |
| ------------- | --------------------------------------------------------------------------------------------------------------------- | ----------------------- |
| `listUsages` | List usages for a `versionId`. | `[{ id, name, … }]` |
| `getUsage` | Get a usage by `usageId`. | The usage resource |
| `createUsage` | Create a usage under `parentId` from `name` + `type` (`Application`, `Dashboard`, `DataSet`, `Report`, `Process`, …). | The created usage |
| `updateUsage` | Update a usage by `usageId`. | The updated usage |
| `deleteUsage` | Delete a usage by `usageId`. | Empty / acknowledgement |
### Data Processing
| Instruction | Description | Returns |
| ---------------------- | ---------------------------------------------------------------------------------------------- | ---------------------------- |
| `listDataProcessing` | List data processings for a `versionId`. | `[{ id, name, … }]` |
| `getDataProcessing` | Get a data processing by `dataProcessingId`. | The data processing resource |
| `createDataProcessing` | Create a data processing under `parentId` from `name` + `type` (`DataFlow`, `DataProcessing`). | The created data processing |
| `updateDataProcessing` | Update a data processing by `dataProcessingId`. | The updated data processing |
| `deleteDataProcessing` | Delete a data processing by `dataProcessingId`. | Empty / acknowledgement |
### Links
| Instruction | Description | Returns |
| ------------ | --------------------------------------------------------- | ----------------------------- |
| `getLinks` | Get all links (relationships) from an entity by `fromId`. | `[{ fromId, toId, type, … }]` |
| `createLink` | Create a link from `fromId` to `toId` with a `type`. | The created link |
| `deleteLink` | Delete a link by `fromId` + `toId` + `linkType`. | Empty / acknowledgement |
### Comments
| Instruction | Description | Returns |
| --------------- | --------------------------------------------------------------- | ------------------------------ |
| `listComments` | List comments on an entity by `entityId`. | `[{ id, content, author, … }]` |
| `createComment` | Create a comment on `entityId` with `content` (rich-text HTML). | The created comment |
### Tasks
| Instruction | Description | Returns |
| ------------ | ----------------------------------------------------------------------------------- | ---------------------------- |
| `listTasks` | List tasks assigned to the current user. | `[{ id, title, status, … }]` |
| `createTask` | Create a task on `entityId` (`title`, `description`, `type`, `assignee`, `status`). | The created task |
| `updateTask` | Update a task by `taskId` (`title`, `description`, `status`, `assignee`). | The updated task |
`Returns` shows the shape of the operation output.
## DSUL Examples
### Discover a version, then search the catalog
```yaml theme={null}
- DataGalaxy.listWorkspaces:
output: workspaces
- DataGalaxy.listVersions:
workspaceId: '{{workspaces[0].id}}'
output: versions
- DataGalaxy.search:
query: customer
versionId: '{{versions[0].id}}'
limit: 20
output: results
```
### 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: Linked to business term.
```
***
## Error Handling
| HTTP Status | Error | Solution |
| ----------- | ------------- | -------------------------------------------------------------------------------------------------------------------------- |
| 401 | Unauthorized | Verify the PAT / integration token and `baseUrl`. The token is exchanged server-side; an invalid token fails the exchange. |
| 403 | Forbidden | Check the DataGalaxy role and scopes on the workspace version. |
| 404 | Not Found | Verify `versionId`, `objectId` and any parent IDs (DoubleUuid format). |
| 422 | Unprocessable | A required attribute is missing or an enum value (`type`, `status`) is invalid. |
| 429 | Rate Limited | Back off and retry with exponential delay. |
| 500 | Server Error | Transient DataGalaxy error — retry shortly. |
### Common Issues
**"DataGalaxy not configured"** — No token could be resolved. Complete the app install with a valid token, call `configureDataGalaxy` to store one in the session, or pass an `Authorization: Bearer` header.
**"DataGalaxy credentials exchange failed"** — The provided PAT / integration token was rejected when exchanging it for an access token. Re-generate the token in DataGalaxy and re-paste it in the app config; confirm the base URL points at the right region.
**"The calling agent could not be identified"** — The MCP capability *Scope* does not declare `agent_id`. Set the Scope to `context_id,agent_id,user_id` on the capability.
**`versionId` errors** — Most operations are scoped to a workspace version. Use the `catalog` tool's `listWorkspaces` then `listVersions` actions (or the `listWorkspaces` / `listVersions` instructions) to obtain a valid `versionId` before calling entity operations.
## External Resources
Official DataGalaxy API documentation.
Learn how Agent Factory agents consume MCP tools in Prisme.ai.