New VDF AI Enterprise is now available on AWS Marketplace
API Reference

Connections

A connection is a governed link to one of your own data sources. You register it once with your deployment; from then on the analysis, indexing, and fine-tuning endpoints reach the source through the connection rather than each caller holding credentials.

Credentials are never returned by any read endpoint. Responses expose only a presence map (secretFields) and a hasSecrets flag, so a client can tell which credential fields are set without ever seeing their values.

Every connection is private to the user who created it. You only ever see and act on your own connections; another user's connections are invisible and return 404.

Use List connectors to discover which source types this deployment supports and the exact configuration and credential fields each one expects.

Endpoints 8

Paths are relative to /data-api

The connection object

A registered data source. Credential values are omitted; only their presence is reported.

Attributes

  • id string

    Unique identifier for the connection, generated by your deployment.

  • name string

    Human-readable name you gave the connection.

  • type string

    Display name of the connector, such as PostgreSQL or Jira Data Center.

  • connectorId nullable string

    Canonical connector identifier, such as postgresql or s3-compatible.

  • status string

    Lifecycle state: configuring before a successful test, connected after one, or error if the last test failed.

  • statusReason nullable string

    Human-readable reason for the current status; set when a test fails and cleared on success.

  • description string

    Optional free-text description.

  • host nullable string

    Host (or host:port) of the source, for connectors that use one.

  • database nullable string

    Database, schema, or catalogue the connection is scoped to, for connectors that use one.

  • config object

    Non-secret, connector-specific settings validated against the connector's configSchema.

  • credentialRef nullable string

    Optional reference to an externally managed credential.

  • datasets integer

    Number of assets discovered on the connection; maintained by your deployment after each discovery.

  • lastTestedAt string

    Timestamp of the last connectivity test, or an empty string if never tested.

  • lastDiscoveredAt string

    Timestamp of the last asset discovery, or an empty string if never run.

  • hasSecrets boolean

    Whether any credential fields are stored for this connection.

  • secretFields object

    Presence map of stored credential field names to true. Values are never included.

  • capabilities array of strings

    What the connector supports, drawn from test-connection, discover-assets, extract-to-vector, and extract-to-finetune.

  • stagedMode string

    How far the connector is enabled: full or discovery-only.

The connection object 
{
  "id": "b3f1c2e4-5a6b-4c7d-8e9f-0a1b2c3d4e5f",
  "name": "Analytics warehouse",
  "type": "PostgreSQL",
  "connectorId": "postgresql",
  "status": "connected",
  "statusReason": null,
  "description": "Read-only replica for analysis.",
  "host": "db.example.com:5432",
  "database": "analytics",
  "config": {},
  "credentialRef": null,
  "datasets": 12,
  "lastTestedAt": "2026-09-01T09:30:00Z",
  "lastDiscoveredAt": "2026-09-01T09:32:00Z",
  "hasSecrets": true,
  "secretFields": {
    "username": true,
    "password": true
  },
  "capabilities": [
    "test-connection",
    "discover-assets",
    "extract-to-vector",
    "extract-to-finetune"
  ],
  "stagedMode": "full"
}

List connections

GET /data-api/v1/connections

Returns the connections you have registered.

Returns your connections, most recently updated first. Only your own connections are returned.

Authentication
Bearer token How it works

Parameters

No parameters.

Returns

Returns a list of connection objects in data.

Request 
curl "$VDF_BASE_URL/data-api/v1/connections" \
  -H "Authorization: Bearer $VDF_ACCESS_TOKEN"
Response 200 
{
  "success": true,
  "data": [
    {
      "id": "b3f1c2e4-5a6b-4c7d-8e9f-0a1b2c3d4e5f",
      "name": "Analytics warehouse",
      "type": "PostgreSQL",
      "connectorId": "postgresql",
      "status": "connected",
      "statusReason": null,
      "description": "Read-only replica for analysis.",
      "host": "db.example.com:5432",
      "database": "analytics",
      "config": {},
      "credentialRef": null,
      "datasets": 12,
      "lastTestedAt": "2026-09-01T09:30:00Z",
      "lastDiscoveredAt": "2026-09-01T09:32:00Z",
      "hasSecrets": true,
      "secretFields": {
        "username": true,
        "password": true
      },
      "capabilities": [
        "test-connection",
        "discover-assets",
        "extract-to-vector",
        "extract-to-finetune"
      ],
      "stagedMode": "full"
    }
  ]
}

Register a connection

POST /data-api/v1/connections

Registers a connection to one of your data sources.

Stores a connection your deployment can query on your behalf. Send credentials in secrets; they are never returned. config is validated against the connector's configSchema — unknown keys are rejected — and host/database live in their own fields.

Registration does not open a network connection. Call Test a connection afterwards to confirm the source is reachable and to move the connection from configuring to connected.

Authentication
Bearer token How it works

Body parameters application/json

  • name string Required

    Human-readable name for the connection.

  • connectorId string

    Connector to use. Required unless you send the legacy type. One of the identifiers returned by List connectors.

    Possible values
    • postgresql
    • mysql
    • microsoft-sql-server
    • oracle
    • sap-hana
    • exasol
    • presto
    • s3-compatible
    • jira
  • type string

    Legacy connector display name, accepted as an alternative to connectorId and resolved to one.

  • config object

    Connector-specific, non-secret settings. Keys must appear in the connector's configSchema; unknown keys return a validation_error. Values must be scalars.

  • secrets object

    Credential fields from the connector's secretSchema (for example username and password). Never returned.

  • host string

    Host (or host:port) of the source, where the connector uses one.

  • database string

    Database, schema, or catalogue to scope to, where the connector uses one.

  • description string

    Optional free-text description.

    Defaults to .

  • status string

    Initial lifecycle state.

    Defaults to configuring.

  • credentialRef string

    Optional reference to an externally managed credential.

Returns

Returns the newly created connection object in data.

Errors

  • 400 name is missing, neither connectorId nor type was supplied, the connector is not available in this deployment, or config contains an unknown or non-scalar field.
Request 
curl -X POST "$VDF_BASE_URL/data-api/v1/connections" \
  -H "Authorization: Bearer $VDF_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Analytics warehouse",
    "connectorId": "postgresql",
    "host": "db.example.com:5432",
    "database": "analytics",
    "description": "Read-only replica for analysis.",
    "secrets": {
      "username": "reporting",
      "password": "<CONNECTION_PASSWORD>"
    }
  }'
Response 200 
{
  "success": true,
  "data": {
    "id": "b3f1c2e4-5a6b-4c7d-8e9f-0a1b2c3d4e5f",
    "name": "Analytics warehouse",
    "type": "PostgreSQL",
    "connectorId": "postgresql",
    "status": "configuring",
    "statusReason": null,
    "description": "Read-only replica for analysis.",
    "host": "db.example.com:5432",
    "database": "analytics",
    "config": {},
    "credentialRef": null,
    "datasets": 0,
    "lastTestedAt": "",
    "lastDiscoveredAt": "",
    "hasSecrets": true,
    "secretFields": {
      "username": true,
      "password": true
    },
    "capabilities": [
      "test-connection",
      "discover-assets",
      "extract-to-vector",
      "extract-to-finetune"
    ],
    "stagedMode": "full"
  }
}

Update a connection

PUT /data-api/v1/connections/{connection_id}

Updates a connection you own.

Updates the fields you supply and leaves the rest unchanged. Secrets are merged with what is stored, so sending one field of a multi-field credential does not drop the others. Changing the connector clears any config that belonged to the previous connector's schema unless you send a new config.

Authentication
Bearer token How it works

Path parameters

  • connection_id string Required

    Identifier of the connection to update.

Body parameters application/json

  • name string

    New name.

  • connectorId string

    Change the connector. One of the identifiers returned by List connectors.

    Possible values
    • postgresql
    • mysql
    • microsoft-sql-server
    • oracle
    • sap-hana
    • exasol
    • presto
    • s3-compatible
    • jira
  • type string

    Legacy connector display name, accepted as an alternative to connectorId.

  • config object

    Replacement connector settings, validated against the connector's configSchema.

  • secrets object

    Credential fields to add or replace. Merged with stored values; empty values are dropped.

  • host string

    New host (or host:port).

  • database string

    New database, schema, or catalogue.

  • description string

    New description.

  • status string

    New lifecycle state.

  • credentialRef string

    New external credential reference.

Returns

Returns the updated connection object in data.

Errors

  • 404 No connection with this id belongs to you.
  • 400 The requested connector is not available in this deployment, or config contains an unknown or non-scalar field.
Request 
curl -X PUT "$VDF_BASE_URL/data-api/v1/connections/b3f1c2e4-5a6b-4c7d-8e9f-0a1b2c3d4e5f" \
  -H "Authorization: Bearer $VDF_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Analytics replica, refreshed nightly.",
    "secrets": {
      "password": "<CONNECTION_PASSWORD>"
    }
  }'
Response 200 
{
  "success": true,
  "data": {
    "id": "b3f1c2e4-5a6b-4c7d-8e9f-0a1b2c3d4e5f",
    "name": "Analytics warehouse",
    "type": "PostgreSQL",
    "connectorId": "postgresql",
    "status": "connected",
    "statusReason": null,
    "description": "Analytics replica, refreshed nightly.",
    "host": "db.example.com:5432",
    "database": "analytics",
    "config": {},
    "credentialRef": null,
    "datasets": 12,
    "lastTestedAt": "2026-09-01T09:30:00Z",
    "lastDiscoveredAt": "2026-09-01T09:32:00Z",
    "hasSecrets": true,
    "secretFields": {
      "username": true,
      "password": true
    },
    "capabilities": [
      "test-connection",
      "discover-assets",
      "extract-to-vector",
      "extract-to-finetune"
    ],
    "stagedMode": "full"
  }
}

Delete a connection

DEL /data-api/v1/connections/{connection_id}

Deletes a connection you own.

Permanently deletes the connection along with its stored credentials, discovered assets, and everything derived from them (exploration runs, feature lists, vector indexes, and fine-tuning datasets built on it).

Authentication
Bearer token How it works

Path parameters

  • connection_id string Required

    Identifier of the connection to delete.

Returns

Returns a confirmation object in data.

Errors

  • 404 No connection with this id belongs to you.
Request 
curl -X DELETE "$VDF_BASE_URL/data-api/v1/connections/b3f1c2e4-5a6b-4c7d-8e9f-0a1b2c3d4e5f" \
  -H "Authorization: Bearer $VDF_ACCESS_TOKEN"
Response 200 
{
  "success": true,
  "data": {
    "deleted": true
  }
}

Test a connection

POST /data-api/v1/connections/{connection_id}/test

Attempts a live connection to the source and records the result.

Opens a real connection to the configured source using the stored credentials and records the outcome on the connection. A successful test sets the status to connected and refreshes the connection's capabilities; a failure sets it to error and stores the source's own error message in statusReason.

Authentication
Bearer token How it works

Path parameters

  • connection_id string Required

    Identifier of the connection to test.

Returns

Returns the test result: whether it succeeded, the round-trip latency in milliseconds, and a message in data.

Errors

  • 404 No connection with this id belongs to you.
  • 400 The connector's configuration or credentials are incomplete.
Request 
curl -X POST "$VDF_BASE_URL/data-api/v1/connections/b3f1c2e4-5a6b-4c7d-8e9f-0a1b2c3d4e5f/test" \
  -H "Authorization: Bearer $VDF_ACCESS_TOKEN"
Response 200 
{
  "success": true,
  "data": {
    "success": true,
    "latencyMs": 42,
    "message": "PostgreSQL connection test completed successfully."
  }
}

Discover assets on a connection

GET /data-api/v1/connections/{connection_id}/assets

Inspects the source and returns the assets it exposes.

Connects to the source and enumerates the assets it exposes — tables and views for databases, files for object storage, projects for Jira. Discovered assets are recorded against the connection (updating its datasets count and lastDiscoveredAt) and returned. Run this before exploration, indexing, or fine-tuning, which all reference an assetId.

Authentication
Bearer token How it works

Path parameters

  • connection_id string Required

    Identifier of the connection to inspect.

Returns

Returns a list of asset objects in data.

Errors

  • 404 No connection with this id belongs to you.
  • 400 The connector is not enabled for discovery, or its configuration is incomplete.
  • 502 The source could not be reached or asset discovery failed.
Request 
curl "$VDF_BASE_URL/data-api/v1/connections/b3f1c2e4-5a6b-4c7d-8e9f-0a1b2c3d4e5f/assets" \
  -H "Authorization: Bearer $VDF_ACCESS_TOKEN"
Response 200 
{
  "success": true,
  "data": [
    {
      "id": "7a2d9e10-4c3b-4a1e-9f8d-2b6c1e0f5a3d",
      "name": "public.customers",
      "source": "PostgreSQL",
      "owner": "user-42",
      "rows": 48213,
      "qualityScore": 87.5,
      "tags": [
        "postgresql",
        "public"
      ],
      "featureListIds": [],
      "relationships": 0,
      "version": "v1",
      "comments": 0,
      "lastSnapshotAt": "2026-09-01T09:32:00Z"
    }
  ]
}

List discovered assets

GET /data-api/v1/connections/assets

Returns every asset discovered across your connections.

Returns all assets discovered across your connections, most recently updated first. Unlike Discover assets on a connection, this reads stored results and does not contact any source.

Authentication
Bearer token How it works

Parameters

No parameters.

Returns

Returns a list of asset objects in data.

Request 
curl "$VDF_BASE_URL/data-api/v1/connections/assets" \
  -H "Authorization: Bearer $VDF_ACCESS_TOKEN"
Response 200 
{
  "success": true,
  "data": [
    {
      "id": "7a2d9e10-4c3b-4a1e-9f8d-2b6c1e0f5a3d",
      "name": "public.customers",
      "source": "PostgreSQL",
      "owner": "user-42",
      "rows": 48213,
      "qualityScore": 87.5,
      "tags": [
        "postgresql",
        "public"
      ],
      "featureListIds": [],
      "relationships": 0,
      "version": "v1",
      "comments": 0,
      "lastSnapshotAt": "2026-09-01T09:32:00Z"
    }
  ]
}

List connectors

GET /data-api/v1/connections/meta/connectors

Returns the connector types this deployment supports.

Returns the connector registry for this deployment. Each entry describes a source type you can connect to, including the configuration fields (configSchema) and credential fields (secretSchema) it expects, the operations it supports (capabilities), and its network requirements. Use it to build a connection form and to choose a connectorId for Register a connection.

This on-premises build supports nine source types, all of which run inside your own network: PostgreSQL, MySQL/MariaDB, Microsoft SQL Server, Oracle, SAP HANA, Exasol, Presto/Trino, S3-compatible object storage, and Jira Data Center. Cloud-hosted warehouses and SaaS document stores are deliberately not offered.

Authentication
Bearer token How it works

Parameters

No parameters.

Returns

Returns a list of connector descriptors in data.

Request 
curl "$VDF_BASE_URL/data-api/v1/connections/meta/connectors" \
  -H "Authorization: Bearer $VDF_ACCESS_TOKEN"
Response 200 
{
  "success": true,
  "data": [
    {
      "connectorId": "postgresql",
      "displayName": "PostgreSQL",
      "category": "database",
      "availability": "ga",
      "adapterAvailable": true,
      "supportsJdbc": true,
      "stagedMode": "full",
      "description": "PostgreSQL — tables and views for discovery, EDA and RAG ingestion.",
      "authModes": [
        "username-password"
      ],
      "configSchema": [
        {
          "key": "host",
          "label": "Host",
          "type": "string",
          "required": true,
          "placeholder": "db.example.com:5432",
          "hint": "Host[:port] or postgresql:// DSN"
        },
        {
          "key": "database",
          "label": "Database",
          "type": "string",
          "required": false,
          "placeholder": "postgres",
          "hint": "Defaults to postgres when empty"
        }
      ],
      "secretSchema": [
        {
          "key": "username",
          "label": "Username",
          "type": "string",
          "required": true
        },
        {
          "key": "password",
          "label": "Password",
          "type": "password",
          "required": true
        }
      ],
      "capabilities": [
        "test-connection",
        "discover-assets",
        "extract-to-vector",
        "extract-to-finetune"
      ],
      "networkRequirements": {
        "tlsRequired": false,
        "outboundIpAllowlist": false,
        "privateConnectivity": true,
        "customerAgent": false
      }
    }
  ]
}