Implement custom integrations

Connect ​ValidMind to third-party systems that aren’t supported out of the box by building custom integrations using our reference API.

Custom integrations let you link resources, such as AI systems or records such as models, from internal registries, proprietary platforms, or any service you control to the ​ValidMind inventory.

How do custom integrations work?

To create a custom integration, you build a service that implements the reference API endpoints:

1. Build a service that implements the required endpoints and connects to your data sources.
2. Deploy your service at a URL accessible to ​ValidMind.
3. Configure a custom integration in ​ValidMind that points to your service URL.
4. After implementation, your users can browse and link resources from your system to records in the ​ValidMind inventory.

Data flows bidirectionally — ​ValidMind reads your data and can write back metadata to enable linking.

flowchart LR
    VM[ValidMind Platform]
    API[Your API service]
    DATA[Your data sources]

    VM <-->|Reference API| API
    API <--> DATA

Prerequisites

• You are logged in to ValidMind.
• You are assigned a role that can manage permissions.¹
• Your integration service is deployed and accessible from ​ValidMind.
• You have the endpoint URL and API key for your integration service.
• A secret containing your API key exists in integration secrets.²

¹ Manage permissions

² Manage secrets

Reference API

The reference API defines the HTTP endpoints your service must implement. ​ValidMind calls these endpoints to discover and synchronize resources.

Bidirectional sync

When linking resources, ​ValidMind can write metadata back to your system via PUT requests. This bidirectional sync enables you to store the ​ValidMind record identifier (vm_cuid) alongside your external records, creating a two-way link between systems.

Required endpoints

Your service must expose these endpoints at the /api/v1 base path:

List models

GET /models — Returns all records from your system. Supports optional ?resource_type= filter.

Get model

GET /models/{id} — Returns a specific record by its unique identifier.

Update model (optional)

PUT /models/{id} — Accepts metadata updates from ​ValidMind, enabling bidirectional sync.

Health check

GET /health — Returns the connection status so users can test the integration.

Optional endpoints

List tickets

GET /tickets — Returns tickets or findings from your system.

Get ticket

GET /tickets/{id} — Returns a specific ticket by ID.

Schema

GET /schema — Returns field definitions to enable formula and workflow access to your integration data.

Resource types

GET /resource-types — Returns available resource categories for filtering in the UI.

/models response format

Your /models (records) endpoint should return objects with these fields:

Field	Required	Description
id	Yes	Unique identifier
name	Yes	Human-readable name
status	No	Lifecycle status (active, training, deprecated)
resource_type	No	Category for filtering (ml_model, llm, agent)
metadata	No	Flexible object with additional fields
created_at	No	ISO 8601 timestamp
updated_at	No	ISO 8601 timestamp

Authentication

​ValidMind authenticates requests using the X-API-Key header. Your service should validate this key and return 401 Unauthorized if invalid or missing.

Code examples

GET /models response

[
  {
    "id": "model-001",
    "name": "fraud-detection-xgboost",
    "status": "active",
    "resource_type": "ml_model",
    "metadata": {
      "framework": "xgboost",
      "version": "2.1.3"
    },
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-22T14:20:00Z"
  }
]

PUT /models/{id} request body

What ​ValidMind sends:

{
  "vm_cuid": "mdl_abc123xyz"
}

Health check response

{
  "status": "healthy"
}

Error response format

{
  "detail": "Model not found"
}

NoneReference implementation

A reference implementation with sample code is available. Contact your ​ValidMind representative for access.

Set up custom integrations

1. Add custom integration

1. In the left sidebar, click Settings.

2. Under Integrations, select Connections.

3. Click Add Connection.

4. In the modal that opens, select Custom Integration.

5. Enter the:

   • Integration Name – A display name to identify this integration.
   • Description (optional) – Additional details about the intended usage.
   • Endpoint URL – The base URL of your deployed integration that implements the reference API.
   • API Key – Select a secret containing the API key for authenticating with your integration.
   • Integration Types – Select which types of objects this integration provides:
     • Record Registry – Sync models from your external system.
     • Artifact / Ticket Source – Sync artifacts or tickets from your external system.
   • Initial Status – Set to Operational to enable immediately or Disabled to finish setup later.

6. Click Save Integration.

7. Test the connection to verify your service is reachable:

   1. Hover over the custom integration you created.
   2. When the menu appears, click it and select Test Connection.

   If the test succeeds, the message Connection successful is displayed.

2. Link resources

After configuring your custom integration, link resources to inventory records or artifacts:

Link inventory records to models

1. In the left sidebar, click Inventory.

2. Select a record or find your record by applying a filter or searching for it.³

3. Click the Integrations tab.

4. Select your custom integration connection.

5. When the menu appears, click it and select Link Model:

   • Select the external model to link.⁴
   • Select a Sync Frequency.
   • Click Test Connection to verify the binding configuration.

6. Click Link Model.

³ Working with the inventory

⁴ If your integration exposes multiple resource types, select the resource type first to filter the available models.

Link artifacts to tickets

1. Locate the artifact you want to link to a ticket.⁵

2. Click the Integrations tab.

3. Select your custom integration connection.

4. When the menu appears, click it and select Link Artifact:

   • Search for or select the external ticket to link.⁶
   • Select a Sync Frequency.
   • Click Test Connection to verify the binding configuration.

5. Click Link Ticket.

⁵ View and filter artifacts

⁶ If the ticket isn’t available in the list, enter the ticket or issue ID from the external system.

NoneWhat are some best practices for implementing custom integrations?

Secure your service

Deploy your integration service behind HTTPS. Validate the API key on every request.

Handle errors gracefully

Return appropriate HTTP status codes (400, 401, 404, 500) and error messages so users can troubleshoot connection issues.

Paginate large responses

If your external system contains many resources, implement pagination to keep responses fast.

Monitor availability

Track the health of your integration service. ​ValidMind displays connection status in the UI, so users notice outages quickly.

Version your API

Include version information in your API path (/api/v1/) to support future changes without breaking existing integrations.