Implement custom integrations

Published

February 6, 2026

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 models, from internal registries, proprietary platforms, or any service you control to the ​ValidMind model inventory.

Prerequisites

How 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 model 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

Reference API

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

NoneReference implementation

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

Required endpoints

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

List models
GET /models — Returns all models from your system. Supports optional ?resource_type= filter.
Get model
GET /models/{id} — Returns a specific model 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.

Model response format

Your models 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.

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 model identifier (vm_cuid) alongside your external records, creating a two-way link between systems.

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"
}

Set up custom integrations

Best practices

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.

Add a 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:
      • Model 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 displays.