Connections API

Get an existing connection

get

Get an existing connection with all credentials redacted.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

connectionKeystring · min: 1Required

A unique name for the connection. Connection key must contain only letters, numbers, hyphens, and underscores. Connection key cannot be one of the following reserved names: data, connection, object, crawl, search, settings, metadata, permission, sync, bulk, upgrade.

Example: my-connection

Responses

200

Connection object

application/json

The connection resource as returned on public endpoints. Sensitive strings are always '[REDACTED]'.

400

Invalid request payload

application/json

404

Connection not found

application/json

get/api/connections/{connectionKey}

GET /api/connections/{connectionKey} HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "technology": "text",
  "clientConfiguration": {
    "credential": {
      "authenticationType": "text",
      "clientId": "my-client-id",
      "authorityUrl": "https://login.authority.com",
      "scope": "session:role-any",
      "publicCertificateThumbprint": "[REDACTED]",
      "resource": "https://api.example.com",
      "privateKey": {
        "filename": "my-private-key.pem",
        "content": "[REDACTED]"
      }
    },
    "immutaResourcePrefix": "IMMUTA",
    "health": {
      "state": "ACTIVE",
      "errors": [
        {
          "code": "text",
          "message": "text",
          "details": null
        }
      ]
    },
    "host": "my-workspace.cloud.databricks.com",
    "port": 443,
    "path": "/sql/1.0/warehouses/abc123",
    "metastoreId": "metastore-123",
    "workspaceId": "123456789",
    "username": "service-principal@example.com",
    "immutaSystemCatalog": "immuta_system",
    "proxy": {
      "host": "https://proxy.example.com",
      "port": 8080,
      "credential": {
        "authenticationType": "text",
        "username": "my-username",
        "password": "[REDACTED]"
      }
    }
  },
  "state": "ACTIVE",
  "activeTasks": [
    {
      "taskId": "123e4567-e89b-12d3-a456-426614174000",
      "type": "text",
      "status": "PENDING",
      "trigger": "MANUAL",
      "createdBy": "text",
      "createdAt": "2026-01-01T00:00:00.000Z"
    }
  ],
  "connectionKey": "my-connection",
  "createdBy": "text",
  "createdAt": "2026-01-01T00:00:00.000Z",
  "updatedBy": "text",
  "updatedAt": "2026-01-01T00:00:00.000Z",
  "dataObjectDefaults": {
    "syncPolicy": false,
    "owners": [
      {
        "id": 1,
        "type": "USER"
      }
    ]
  },
  "dataObjectSync": {
    "enabled": true,
    "schedule": "EVERY_12_HOURS",
    "startTime": 1,
    "syncAllDataObjects": true
  },
  "policyConfiguration": {
    "enabled": true,
    "health": {
      "state": "ACTIVE",
      "errors": [
        {
          "code": "text",
          "message": "text",
          "details": null
        }
      ]
    },
    "excludeGroupPattern": "admin.*"
  },
  "auditConfiguration": {
    "enabled": true,
    "health": {
      "state": "ACTIVE",
      "errors": [
        {
          "code": "text",
          "message": "text",
          "details": null
        }
      ]
    },
    "workspaceIds": [
      "workspace-1",
      "workspace-2"
    ]
  }
}

Delete a connection and all its data objects

delete

Delete a connection and all its data objects. Returns a task ID for tracking the asynchronous deletion process. When supported by the technology, the response may include a generated teardown script to run against the data platform before the connection record is removed.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

connectionKeystring · min: 1Required

Example: my-connection

Query parameters

forcestringOptional

Whether to force delete the connection without cleaning up Immuta-managed resources in the remote platform. This action can only be done on unhealthy connections.

Responses

202

Deletion task created and accepted for processing

application/json

The response schema for deleting a connection. Returns a task ID for tracking the asynchronous deletion process.

taskIdstring · uuidRequiredPattern:

^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000)$

404

Connection not found

application/json

409

Unable to delete connection. Connection state must be INACTIVE to be deleted.

application/json

delete/api/connections/{connectionKey}

DELETE /api/connections/{connectionKey} HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "taskId": "123e4567-e89b-12d3-a456-426614174000",
  "teardown": [
    {
      "configuration": "text",
      "description": "text",
      "language": "SQL"
    }
  ]
}

Partially update the connection

patch

Partially update the connection for the specified connection key.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

connectionKeystring · min: 1Required

Example: my-connection

Query parameters

dryRunstringOptional

Whether to perform a dry run of the patch operation without making actual changes.

Body

The update connection request payload schema.

Responses

200

Connection object

application/json

The connection resource as returned on public endpoints. Sensitive strings are always '[REDACTED]'.

400

Invalid request payload

application/json

404

Connection not found

application/json

409

Unable to update connection. Connection state must be ACTIVE or UNHEALTHY to be updated.

application/json

patch/api/connections/{connectionKey}

PATCH /api/connections/{connectionKey} HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 845

{
  "clientConfiguration": {
    "credential": {
      "authenticationType": "text",
      "clientId": "my-client-id",
      "authorityUrl": "https://login.authority.com",
      "scope": "session:role-any",
      "publicCertificateThumbprint": "AB:CD:EF:12:34:56",
      "resource": "https://api.example.com",
      "privateKey": {
        "filename": "my-private-key.pem",
        "content": "-----BEGIN PRIVATE KEY-----\n...your-private-key-content...\n-----END PRIVATE KEY-----"
      }
    },
    "path": "/sql/1.0/warehouses/abc123",
    "proxy": {
      "host": "https://proxy.example.com",
      "port": 8080,
      "credential": {
        "authenticationType": "text",
        "username": "my-username",
        "password": "my-password"
      }
    }
  },
  "dataObjectDefaults": {
    "syncPolicy": true,
    "owners": [
      {
        "id": 1,
        "type": "USER"
      }
    ]
  },
  "dataObjectSync": {
    "enabled": true,
    "schedule": "EVERY_12_HOURS",
    "startTime": 1,
    "syncAllDataObjects": true
  },
  "auditConfiguration": {
    "enabled": true,
    "workspaceIds": [
      "workspace-1",
      "workspace-2"
    ]
  }
}

{
  "technology": "text",
  "clientConfiguration": {
    "credential": {
      "authenticationType": "text",
      "clientId": "my-client-id",
      "authorityUrl": "https://login.authority.com",
      "scope": "session:role-any",
      "publicCertificateThumbprint": "[REDACTED]",
      "resource": "https://api.example.com",
      "privateKey": {
        "filename": "my-private-key.pem",
        "content": "[REDACTED]"
      }
    },
    "immutaResourcePrefix": "IMMUTA",
    "health": {
      "state": "ACTIVE",
      "errors": [
        {
          "code": "text",
          "message": "text",
          "details": null
        }
      ]
    },
    "host": "my-workspace.cloud.databricks.com",
    "port": 443,
    "path": "/sql/1.0/warehouses/abc123",
    "metastoreId": "metastore-123",
    "workspaceId": "123456789",
    "username": "service-principal@example.com",
    "immutaSystemCatalog": "immuta_system",
    "proxy": {
      "host": "https://proxy.example.com",
      "port": 8080,
      "credential": {
        "authenticationType": "text",
        "username": "my-username",
        "password": "[REDACTED]"
      }
    }
  },
  "state": "ACTIVE",
  "activeTasks": [
    {
      "taskId": "123e4567-e89b-12d3-a456-426614174000",
      "type": "text",
      "status": "PENDING",
      "trigger": "MANUAL",
      "createdBy": "text",
      "createdAt": "2026-01-01T00:00:00.000Z"
    }
  ],
  "connectionKey": "my-connection",
  "createdBy": "text",
  "createdAt": "2026-01-01T00:00:00.000Z",
  "updatedBy": "text",
  "updatedAt": "2026-01-01T00:00:00.000Z",
  "dataObjectDefaults": {
    "syncPolicy": false,
    "owners": [
      {
        "id": 1,
        "type": "USER"
      }
    ]
  },
  "dataObjectSync": {
    "enabled": true,
    "schedule": "EVERY_12_HOURS",
    "startTime": 1,
    "syncAllDataObjects": true
  },
  "policyConfiguration": {
    "enabled": true,
    "health": {
      "state": "ACTIVE",
      "errors": [
        {
          "code": "text",
          "message": "text",
          "details": null
        }
      ]
    },
    "excludeGroupPattern": "admin.*"
  },
  "auditConfiguration": {
    "enabled": true,
    "health": {
      "state": "ACTIVE",
      "errors": [
        {
          "code": "text",
          "message": "text",
          "details": null
        }
      ]
    },
    "workspaceIds": [
      "workspace-1",
      "workspace-2"
    ]
  }
}

Get the generated setup script for a connection

get

Get the generated setup script for an existing connection. The response contains an ordered list of configuration steps the user runs against the underlying data platform to provision the access Immuta needs. For technologies that mint a one-time system API key (currently Trino), previously issued plaintext keys cannot be recovered; use POST /_regenerate-api-key to rotate and receive setup with a new key.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

connectionKeystring · min: 1Required

Example: my-connection

Responses

200

Generated setup script for the connection

application/json

Generated setup script for the connection.

warningstringOptional

Optional warning when setup generation fails after a successful key rotation. May include the new plaintext key so it is not lost. Only set on POST /_regenerate-api-key responses.

404

Connection not found

application/json

422

Unable to generate the setup script. Commonly caused by invalid credentials or an unreachable data platform.

application/json

get/api/connections/{connectionKey}/setup

GET /api/connections/{connectionKey}/setup HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "setup": [
    {
      "configuration": "text",
      "description": "text",
      "language": "SQL"
    }
  ],
  "warning": "text"
}

Regenerate the connection system API key

post

Rotate the connection-scoped system API key for technologies that support system API key regeneration (currently Trino) via BIM, persist the new key ID on the connection, and return setup with the plaintext key. Concurrent requests for the same connection coalesce to a single rotation (including shared failure outcomes — waiters do not re-rotate). When rotate succeeds but persistence or setup generation fails, the response still includes the plaintext key in warning. Connections whose connector does not support regeneration return 400.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

connectionKeystring · min: 1Required

Example: my-connection

Responses

200

Setup script with the new plaintext system API key (optional warning if persistence or setup generation fails after rotate)

application/json

Generated setup script for the connection.

warningstringOptional

Optional warning when setup generation fails after a successful key rotation. May include the new plaintext key so it is not lost. Only set on POST /_regenerate-api-key responses.

400

Invalid request (e.g. non-Trino connection)

application/json

404

Connection not found

application/json

422

Unable to rotate the system API key (BIM rotate or connector load failed before a new key was issued)

application/json

post/api/connections/{connectionKey}/_regenerate-api-key

POST /api/connections/{connectionKey}/_regenerate-api-key HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "setup": [
    {
      "configuration": "text",
      "description": "text",
      "language": "SQL"
    }
  ],
  "warning": "text"
}

Get the generated teardown script for a connection

get

Get the generated teardown script for an existing connection. The response contains an ordered list of configuration steps the user runs against the underlying data platform to remove Immuta-managed resources. Unsupported technologies return an empty list.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

connectionKeystring · min: 1Required

Example: my-connection

Responses

200

Generated teardown script for the connection

application/json

Generated teardown script for the connection.

404

Connection not found

application/json

422

Unable to generate the teardown script. Commonly caused by invalid credentials or an unreachable data platform.

application/json

get/api/connections/{connectionKey}/teardown

GET /api/connections/{connectionKey}/teardown HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "teardown": [
    {
      "configuration": "text",
      "description": "text",
      "language": "SQL"
    }
  ]
}

Activate the connection

post

Activate the connection for the specified connection key.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

connectionKeystring · min: 1Required

Example: my-connection

Query parameters

syncOnActivatestringOptional

Whether to run object sync as part of re-activating the connection.

Responses

200

Successfully activated connection

application/json

The connection resource as returned on public endpoints. Sensitive strings are always '[REDACTED]'.

404

Connection not found

application/json

409

Unable to activate connection. Connection state must be INACTIVE to be activated.

application/json

post/api/connections/{connectionKey}/_activate

POST /api/connections/{connectionKey}/_activate HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "technology": "text",
  "clientConfiguration": {
    "credential": {
      "authenticationType": "text",
      "clientId": "my-client-id",
      "authorityUrl": "https://login.authority.com",
      "scope": "session:role-any",
      "publicCertificateThumbprint": "[REDACTED]",
      "resource": "https://api.example.com",
      "privateKey": {
        "filename": "my-private-key.pem",
        "content": "[REDACTED]"
      }
    },
    "immutaResourcePrefix": "IMMUTA",
    "health": {
      "state": "ACTIVE",
      "errors": [
        {
          "code": "text",
          "message": "text",
          "details": null
        }
      ]
    },
    "host": "my-workspace.cloud.databricks.com",
    "port": 443,
    "path": "/sql/1.0/warehouses/abc123",
    "metastoreId": "metastore-123",
    "workspaceId": "123456789",
    "username": "service-principal@example.com",
    "immutaSystemCatalog": "immuta_system",
    "proxy": {
      "host": "https://proxy.example.com",
      "port": 8080,
      "credential": {
        "authenticationType": "text",
        "username": "my-username",
        "password": "[REDACTED]"
      }
    }
  },
  "state": "ACTIVE",
  "activeTasks": [
    {
      "taskId": "123e4567-e89b-12d3-a456-426614174000",
      "type": "text",
      "status": "PENDING",
      "trigger": "MANUAL",
      "createdBy": "text",
      "createdAt": "2026-01-01T00:00:00.000Z"
    }
  ],
  "connectionKey": "my-connection",
  "createdBy": "text",
  "createdAt": "2026-01-01T00:00:00.000Z",
  "updatedBy": "text",
  "updatedAt": "2026-01-01T00:00:00.000Z",
  "dataObjectDefaults": {
    "syncPolicy": false,
    "owners": [
      {
        "id": 1,
        "type": "USER"
      }
    ]
  },
  "dataObjectSync": {
    "enabled": true,
    "schedule": "EVERY_12_HOURS",
    "startTime": 1,
    "syncAllDataObjects": true
  },
  "policyConfiguration": {
    "enabled": true,
    "health": {
      "state": "ACTIVE",
      "errors": [
        {
          "code": "text",
          "message": "text",
          "details": null
        }
      ]
    },
    "excludeGroupPattern": "admin.*"
  },
  "auditConfiguration": {
    "enabled": true,
    "health": {
      "state": "ACTIVE",
      "errors": [
        {
          "code": "text",
          "message": "text",
          "details": null
        }
      ]
    },
    "workspaceIds": [
      "workspace-1",
      "workspace-2"
    ]
  }
}

Deactivate the connection

post

Deactivate the connection for the specified connection key.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

connectionKeystring · min: 1Required

Example: my-connection

Responses

200

Successfully deactivated connection

application/json

The connection resource as returned on public endpoints. Sensitive strings are always '[REDACTED]'.

404

Connection not found

application/json

409

Unable to deactivate connection. Connection state must be ACTIVE to be deactivated.

application/json

post/api/connections/{connectionKey}/_deactivate

POST /api/connections/{connectionKey}/_deactivate HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "technology": "text",
  "clientConfiguration": {
    "credential": {
      "authenticationType": "text",
      "clientId": "my-client-id",
      "authorityUrl": "https://login.authority.com",
      "scope": "session:role-any",
      "publicCertificateThumbprint": "[REDACTED]",
      "resource": "https://api.example.com",
      "privateKey": {
        "filename": "my-private-key.pem",
        "content": "[REDACTED]"
      }
    },
    "immutaResourcePrefix": "IMMUTA",
    "health": {
      "state": "ACTIVE",
      "errors": [
        {
          "code": "text",
          "message": "text",
          "details": null
        }
      ]
    },
    "host": "my-workspace.cloud.databricks.com",
    "port": 443,
    "path": "/sql/1.0/warehouses/abc123",
    "metastoreId": "metastore-123",
    "workspaceId": "123456789",
    "username": "service-principal@example.com",
    "immutaSystemCatalog": "immuta_system",
    "proxy": {
      "host": "https://proxy.example.com",
      "port": 8080,
      "credential": {
        "authenticationType": "text",
        "username": "my-username",
        "password": "[REDACTED]"
      }
    }
  },
  "state": "ACTIVE",
  "activeTasks": [
    {
      "taskId": "123e4567-e89b-12d3-a456-426614174000",
      "type": "text",
      "status": "PENDING",
      "trigger": "MANUAL",
      "createdBy": "text",
      "createdAt": "2026-01-01T00:00:00.000Z"
    }
  ],
  "connectionKey": "my-connection",
  "createdBy": "text",
  "createdAt": "2026-01-01T00:00:00.000Z",
  "updatedBy": "text",
  "updatedAt": "2026-01-01T00:00:00.000Z",
  "dataObjectDefaults": {
    "syncPolicy": false,
    "owners": [
      {
        "id": 1,
        "type": "USER"
      }
    ]
  },
  "dataObjectSync": {
    "enabled": true,
    "schedule": "EVERY_12_HOURS",
    "startTime": 1,
    "syncAllDataObjects": true
  },
  "policyConfiguration": {
    "enabled": true,
    "health": {
      "state": "ACTIVE",
      "errors": [
        {
          "code": "text",
          "message": "text",
          "details": null
        }
      ]
    },
    "excludeGroupPattern": "admin.*"
  },
  "auditConfiguration": {
    "enabled": true,
    "health": {
      "state": "ACTIVE",
      "errors": [
        {
          "code": "text",
          "message": "text",
          "details": null
        }
      ]
    },
    "workspaceIds": [
      "workspace-1",
      "workspace-2"
    ]
  }
}

Validate the connection

post

Validate the connection for the specified connection key. Runs validation against each enabled component of the connection (client, policy, and audit) and updates the persisted health state for each based on the result.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

connectionKeystring · min: 1Required

Example: my-connection

Responses

202

Validation task created and accepted for processing

application/json

The response schema for validating a connection. Returns a task ID for tracking the asynchronous validation process.

taskIdstring · uuidRequiredPattern:

^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000)$

404

Connection not found

application/json

409

Unable to validate connection. Connection state must be ACTIVE or UNHEALTHY to be validated.

application/json

post/api/connections/{connectionKey}/_validate

POST /api/connections/{connectionKey}/_validate HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "taskId": "123e4567-e89b-12d3-a456-426614174000"
}

Get a list of connections

get

Get a list of connections.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Query parameters

page[limit]integer · min: 1 · max: 100Optional

Maximum number of items to return.

Default: 20Example: 20

page[cursor]stringOptional

The cursor to start from.

Example: eyJpZCI6IjEyMzQ1In0=

Responses

200

Connections list

application/json

Response schema for listing connections with pagination. Sensitive strings are always '[REDACTED]'.

dataone of[]Required

The connection resource as returned on public endpoints. Sensitive strings are always '[REDACTED]'.

get/api/connections

GET /api/connections HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

200

Connections list

{
  "data": [
    {
      "technology": "text",
      "clientConfiguration": {
        "credential": {
          "authenticationType": "text",
          "clientId": "my-client-id",
          "authorityUrl": "https://login.authority.com",
          "scope": "session:role-any",
          "publicCertificateThumbprint": "[REDACTED]",
          "resource": "https://api.example.com",
          "privateKey": {
            "filename": "my-private-key.pem",
            "content": "[REDACTED]"
          }
        },
        "immutaResourcePrefix": "IMMUTA",
        "health": {
          "state": "ACTIVE",
          "errors": [
            {
              "code": "text",
              "message": "text",
              "details": null
            }
          ]
        },
        "host": "my-workspace.cloud.databricks.com",
        "port": 443,
        "path": "/sql/1.0/warehouses/abc123",
        "metastoreId": "metastore-123",
        "workspaceId": "123456789",
        "username": "service-principal@example.com",
        "immutaSystemCatalog": "immuta_system",
        "proxy": {
          "host": "https://proxy.example.com",
          "port": 8080,
          "credential": {
            "authenticationType": "text",
            "username": "my-username",
            "password": "[REDACTED]"
          }
        }
      },
      "state": "ACTIVE",
      "activeTasks": [
        {
          "taskId": "123e4567-e89b-12d3-a456-426614174000",
          "type": "text",
          "status": "PENDING",
          "trigger": "MANUAL",
          "createdBy": "text",
          "createdAt": "2026-01-01T00:00:00.000Z"
        }
      ],
      "connectionKey": "my-connection",
      "createdBy": "text",
      "createdAt": "2026-01-01T00:00:00.000Z",
      "updatedBy": "text",
      "updatedAt": "2026-01-01T00:00:00.000Z",
      "dataObjectDefaults": {
        "syncPolicy": false,
        "owners": [
          {
            "id": 1,
            "type": "USER"
          }
        ]
      },
      "dataObjectSync": {
        "enabled": true,
        "schedule": "EVERY_12_HOURS",
        "startTime": 1,
        "syncAllDataObjects": true
      },
      "policyConfiguration": {
        "enabled": true,
        "health": {
          "state": "ACTIVE",
          "errors": [
            {
              "code": "text",
              "message": "text",
              "details": null
            }
          ]
        },
        "excludeGroupPattern": "admin.*"
      },
      "auditConfiguration": {
        "enabled": true,
        "health": {
          "state": "ACTIVE",
          "errors": [
            {
              "code": "text",
              "message": "text",
              "details": null
            }
          ]
        },
        "workspaceIds": [
          "workspace-1",
          "workspace-2"
        ]
      }
    }
  ],
  "meta": {
    "sort": [
      {
        "field": "connectionKey",
        "order": "asc"
      }
    ],
    "page": {
      "limit": 20,
      "cursor": "eyJpZCI6IjEyMzQ1In0="
    }
  }
}

Create a new connection

post

Create a new connection.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Body

The create connection request payload schema.

Responses

201

Connection object

application/json

The create connection response as returned on public endpoints. Sensitive credential strings are always '[REDACTED]'. Optional setup scripts remain plaintext.

400

Invalid request payload

application/json

409

Unable to create connection. Connection key already exists.

application/json

post/api/connections

POST /api/connections HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 1066

{
  "technology": "text",
  "clientConfiguration": {
    "credential": {
      "authenticationType": "text",
      "clientId": "my-client-id",
      "authorityUrl": "https://login.authority.com",
      "scope": "session:role-any",
      "publicCertificateThumbprint": "AB:CD:EF:12:34:56",
      "resource": "https://api.example.com",
      "privateKey": {
        "filename": "my-private-key.pem",
        "content": "-----BEGIN PRIVATE KEY-----\n...your-private-key-content...\n-----END PRIVATE KEY-----"
      }
    },
    "host": "my-workspace.cloud.databricks.com",
    "port": 443,
    "path": "/sql/1.0/warehouses/abc123",
    "immutaSystemCatalog": "immuta_system",
    "proxy": {
      "host": "https://proxy.example.com",
      "port": 8080,
      "credential": {
        "authenticationType": "text",
        "username": "my-username",
        "password": "my-password"
      }
    }
  },
  "connectionKey": "my-connection",
  "dataObjectDefaults": {
    "syncPolicy": false,
    "owners": [
      {
        "id": 1,
        "type": "USER"
      }
    ]
  },
  "dataObjectSync": {
    "enabled": true,
    "schedule": "EVERY_24_HOURS",
    "startTime": 0,
    "syncAllDataObjects": true
  },
  "policyConfiguration": {
    "excludeGroupPattern": "admin.*"
  },
  "auditConfiguration": {
    "enabled": true,
    "workspaceIds": [
      "workspace-1",
      "workspace-2"
    ]
  },
  "syncOnCreate": true
}

{
  "technology": "text",
  "clientConfiguration": {
    "credential": {
      "authenticationType": "text",
      "clientId": "my-client-id",
      "authorityUrl": "https://login.authority.com",
      "scope": "session:role-any",
      "publicCertificateThumbprint": "[REDACTED]",
      "resource": "https://api.example.com",
      "privateKey": {
        "filename": "my-private-key.pem",
        "content": "[REDACTED]"
      }
    },
    "immutaResourcePrefix": "IMMUTA",
    "health": {
      "state": "ACTIVE",
      "errors": [
        {
          "code": "text",
          "message": "text",
          "details": null
        }
      ]
    },
    "host": "my-workspace.cloud.databricks.com",
    "port": 443,
    "path": "/sql/1.0/warehouses/abc123",
    "metastoreId": "metastore-123",
    "workspaceId": "123456789",
    "username": "service-principal@example.com",
    "immutaSystemCatalog": "immuta_system",
    "proxy": {
      "host": "https://proxy.example.com",
      "port": 8080,
      "credential": {
        "authenticationType": "text",
        "username": "my-username",
        "password": "[REDACTED]"
      }
    }
  },
  "state": "ACTIVE",
  "activeTasks": [
    {
      "taskId": "123e4567-e89b-12d3-a456-426614174000",
      "type": "text",
      "status": "PENDING",
      "trigger": "MANUAL",
      "createdBy": "text",
      "createdAt": "2026-01-01T00:00:00.000Z"
    }
  ],
  "connectionKey": "my-connection",
  "createdBy": "text",
  "createdAt": "2026-01-01T00:00:00.000Z",
  "updatedBy": "text",
  "updatedAt": "2026-01-01T00:00:00.000Z",
  "dataObjectDefaults": {
    "syncPolicy": false,
    "owners": [
      {
        "id": 1,
        "type": "USER"
      }
    ]
  },
  "dataObjectSync": {
    "enabled": true,
    "schedule": "EVERY_12_HOURS",
    "startTime": 1,
    "syncAllDataObjects": true
  },
  "policyConfiguration": {
    "enabled": true,
    "health": {
      "state": "ACTIVE",
      "errors": [
        {
          "code": "text",
          "message": "text",
          "details": null
        }
      ]
    },
    "excludeGroupPattern": "admin.*"
  },
  "auditConfiguration": {
    "enabled": true,
    "health": {
      "state": "ACTIVE",
      "errors": [
        {
          "code": "text",
          "message": "text",
          "details": null
        }
      ]
    },
    "workspaceIds": [
      "workspace-1",
      "workspace-2"
    ]
  },
  "setup": [
    {
      "configuration": "text",
      "description": "text",
      "language": "SQL"
    }
  ]
}

Search for data objects by connection and attributes

post

Search for data objects by connection and attributes.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Body

Request schema for searching data objects by connection and attributes with pagination.

Responses

200

Data objects search result

application/json

Response schema for searching data objects with pagination.

400

Invalid search filter

application/json

post/api/connections/dataObjects/_search

POST /api/connections/dataObjects/_search HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 226

{
  "filter": {
    "connection": {
      "connectionKey": "my-connection"
    },
    "dataObject": {
      "name": "text"
    }
  },
  "tags": {
    "include": [
      1
    ],
    "exclude": [
      1
    ]
  },
  "meta": {
    "sort": [
      {
        "field": "name",
        "order": "asc"
      }
    ],
    "page": {
      "limit": 20,
      "cursor": "eyJpZCI6IjEyMzQ1In0="
    }
  }
}

{
  "data": [
    {
      "id": "text",
      "name": "text",
      "type": "text",
      "normalizedType": "text",
      "technology": "text",
      "remoteId": "text",
      "remoteType": "text",
      "remoteFormat": "text",
      "remoteKind": "text",
      "remoteCreatedAt": "2026-01-01T00:00:00.000Z",
      "remoteUpdatedAt": "2026-01-01T00:00:00.000Z",
      "objectPath": {
        "name": "text",
        "type": "text",
        "id": "text",
        "child": {
          "name": "text",
          "type": "text",
          "id": "text",
          "child": {
            "name": "text",
            "type": "text",
            "id": "text",
            "child": "[Circular Reference]"
          }
        }
      },
      "lastSyncedAt": "2026-01-01T00:00:00.000Z",
      "settings": {
        "syncPolicy": {
          "value": true,
          "inheritedFrom": {
            "id": "text",
            "type": "CONNECTION"
          }
        },
        "owners": [
          {
            "id": 1,
            "type": "USER",
            "inheritedFrom": {
              "id": "text",
              "type": "CONNECTION"
            }
          }
        ]
      },
      "tags": [
        {
          "id": 1,
          "name": "text",
          "displayName": "text",
          "source": "text",
          "inheritedFrom": {
            "id": "text",
            "type": "CONNECTION"
          },
          "application": {
            "appliedAt": "2026-01-01T00:00:00.000Z",
            "appliedBy": {
              "profileId": 1,
              "name": "text"
            },
            "context": "text"
          }
        }
      ],
      "connectionKey": "my-connection",
      "createdBy": "text",
      "createdAt": "2026-01-01T00:00:00.000Z",
      "updatedBy": "text",
      "updatedAt": "2026-01-01T00:00:00.000Z"
    }
  ],
  "meta": {
    "sort": [
      {
        "field": "name",
        "order": "asc"
      }
    ],
    "page": {
      "limit": 20,
      "cursor": "eyJpZCI6IjEyMzQ1In0="
    },
    "totalCount": 1
  }
}

Get a data object by connection and ID without children

get

Get a data object by connection and ID without children.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

connectionKeystring · min: 1Required

Example: my-connection

idstringRequired

The unique, Immuta-generated identifier (UUID) for the data object.

Responses

200

Data object

application/json

The response schema for getting a data object.

idstringRequired

The unique, Immuta-generated identifier (UUID) for the data object.

namestring · min: 1Required

The name of the data object.

typestring · min: 1Required

The type of the data object.

normalizedTypestring · min: 1Required

The normalized type of the data object.

technologystring · min: 1Required

The technology of the data platform.

remoteIdstring · min: 1Required

The remote identifier for the data object.

remoteTypestringOptional

The type of the data object as returned by the remote platform.

remoteFormatstringOptional

The format of the data object as returned by the remote platform.

remoteKindstringOptional

The kind of the data object as returned by the remote platform.

remoteCreatedAtstring · date-timeOptional

The timestamp of the creation of the data object as returned by the remote platform.

remoteUpdatedAtstring · date-timeOptional

The timestamp of the last update of the data object as returned by the remote platform.

lastSyncedAtstring · date-timeRequired

The timestamp of the last sync of this data object.

connectionKeystring · min: 1Required

Example: my-connection

createdBystringRequired

The user or system account ID who created the data object.

createdAtstring · date-timeRequired

The date and time the data object was created.

updatedBystringRequired

The user or system account ID who updated the data object.

updatedAtstring · date-timeRequired

The date and time the data object was updated.

404

Connection or data object not found

application/json

get/api/connections/{connectionKey}/dataObjects/{id}

GET /api/connections/{connectionKey}/dataObjects/{id} HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "id": "text",
  "name": "text",
  "type": "text",
  "normalizedType": "text",
  "technology": "text",
  "remoteId": "text",
  "remoteType": "text",
  "remoteFormat": "text",
  "remoteKind": "text",
  "remoteCreatedAt": "2026-01-01T00:00:00.000Z",
  "remoteUpdatedAt": "2026-01-01T00:00:00.000Z",
  "objectPath": {
    "name": "text",
    "type": "text",
    "id": "text",
    "child": {
      "name": "text",
      "type": "text",
      "id": "text",
      "child": {
        "name": "text",
        "type": "text",
        "id": "text",
        "child": {
          "name": "text",
          "type": "text",
          "id": "text",
          "child": {
            "name": "text",
            "type": "text",
            "id": "text",
            "child": "[Circular Reference]"
          }
        }
      }
    }
  },
  "lastSyncedAt": "2026-01-01T00:00:00.000Z",
  "settings": {
    "syncPolicy": {
      "value": true,
      "inheritedFrom": {
        "id": "text",
        "type": "CONNECTION"
      }
    },
    "owners": [
      {
        "id": 1,
        "type": "USER",
        "inheritedFrom": {
          "id": "text",
          "type": "CONNECTION"
        }
      }
    ]
  },
  "tags": [
    {
      "id": 1,
      "name": "text",
      "displayName": "text",
      "source": "text",
      "inheritedFrom": {
        "id": "text",
        "type": "CONNECTION"
      },
      "application": {
        "appliedAt": "2026-01-01T00:00:00.000Z",
        "appliedBy": {
          "profileId": 1,
          "name": "text"
        },
        "context": "text"
      }
    }
  ],
  "connectionKey": "my-connection",
  "createdBy": "text",
  "createdAt": "2026-01-01T00:00:00.000Z",
  "updatedBy": "text",
  "updatedAt": "2026-01-01T00:00:00.000Z"
}

Delete a data object and all its descendants

delete

Delete a data object and all its descendants. Returns a task ID for tracking the asynchronous deletion process.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

connectionKeystring · min: 1Required

Example: my-connection

idstringRequired

The unique, Immuta-generated identifier (UUID) for the data object.

Responses

202

Deletion task created and accepted for processing

application/json

The response schema for deleting a data object. Returns a task ID for tracking the asynchronous deletion process.

taskIdstring · uuidRequiredPattern:

^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000)$

404

Connection or data object not found

application/json

delete/api/connections/{connectionKey}/dataObjects/{id}

DELETE /api/connections/{connectionKey}/dataObjects/{id} HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "taskId": "123e4567-e89b-12d3-a456-426614174000"
}

Update a data object by connection and ID

patch

Update a data object by connection and ID.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

connectionKeystring · min: 1Required

Example: my-connection

idstringRequired

The unique, Immuta-generated identifier (UUID) for the data object.

Body

The request body for updating a data object.

Responses

200

Data object updated

application/json

The response schema for updating a data object. Returns the full data object.

idstringRequired

The unique, Immuta-generated identifier (UUID) for the data object.

namestring · min: 1Required

The name of the data object.

typestring · min: 1Required

The type of the data object.

normalizedTypestring · min: 1Required

The normalized type of the data object.

technologystring · min: 1Required

The technology of the data platform.

remoteIdstring · min: 1Required

The remote identifier for the data object.

remoteTypestringOptional

The type of the data object as returned by the remote platform.

remoteFormatstringOptional

The format of the data object as returned by the remote platform.

remoteKindstringOptional

The kind of the data object as returned by the remote platform.

remoteCreatedAtstring · date-timeOptional

The timestamp of the creation of the data object as returned by the remote platform.

remoteUpdatedAtstring · date-timeOptional

The timestamp of the last update of the data object as returned by the remote platform.

lastSyncedAtstring · date-timeRequired

The timestamp of the last sync of this data object.

connectionKeystring · min: 1Required

Example: my-connection

createdBystringRequired

The user or system account ID who created the data object.

createdAtstring · date-timeRequired

The date and time the data object was created.

updatedBystringRequired

The user or system account ID who updated the data object.

updatedAtstring · date-timeRequired

The date and time the data object was updated.

400

Invalid request payload

application/json

404

Connection or data object not found

application/json

patch/api/connections/{connectionKey}/dataObjects/{id}

PATCH /api/connections/{connectionKey}/dataObjects/{id} HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 112

{
  "settings": {
    "syncPolicy": true,
    "owners": [
      {
        "id": 1,
        "type": "USER"
      }
    ]
  },
  "tags": {
    "add": [
      {
        "id": 1
      }
    ],
    "remove": [
      {
        "id": 1
      }
    ]
  }
}

{
  "id": "text",
  "name": "text",
  "type": "text",
  "normalizedType": "text",
  "technology": "text",
  "remoteId": "text",
  "remoteType": "text",
  "remoteFormat": "text",
  "remoteKind": "text",
  "remoteCreatedAt": "2026-01-01T00:00:00.000Z",
  "remoteUpdatedAt": "2026-01-01T00:00:00.000Z",
  "objectPath": {
    "name": "text",
    "type": "text",
    "id": "text",
    "child": {
      "name": "text",
      "type": "text",
      "id": "text",
      "child": {
        "name": "text",
        "type": "text",
        "id": "text",
        "child": {
          "name": "text",
          "type": "text",
          "id": "text",
          "child": {
            "name": "text",
            "type": "text",
            "id": "text",
            "child": "[Circular Reference]"
          }
        }
      }
    }
  },
  "lastSyncedAt": "2026-01-01T00:00:00.000Z",
  "settings": {
    "syncPolicy": {
      "value": true,
      "inheritedFrom": {
        "id": "text",
        "type": "CONNECTION"
      }
    },
    "owners": [
      {
        "id": 1,
        "type": "USER",
        "inheritedFrom": {
          "id": "text",
          "type": "CONNECTION"
        }
      }
    ]
  },
  "tags": [
    {
      "id": 1,
      "name": "text",
      "displayName": "text",
      "source": "text",
      "inheritedFrom": {
        "id": "text",
        "type": "CONNECTION"
      },
      "application": {
        "appliedAt": "2026-01-01T00:00:00.000Z",
        "appliedBy": {
          "profileId": 1,
          "name": "text"
        },
        "context": "text"
      }
    }
  ],
  "connectionKey": "my-connection",
  "createdBy": "text",
  "createdAt": "2026-01-01T00:00:00.000Z",
  "updatedBy": "text",
  "updatedAt": "2026-01-01T00:00:00.000Z"
}

Create a folder or securable under a Custom connection

post

Manually create a folder or securable under a Custom connection. Omit parentId to create under the connection root; otherwise parent must be a CONNECTION root or FOLDER. Name and type must be unique under the same parent.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

connectionKeystring · min: 1Required

Example: my-connection

Body

Request body to manually create a folder or securable under a Custom connection. Omit parentId to create under the connection root.

namestring · min: 1Required

The name of the data object to create. Trimmed; whitespace-only names are rejected. Must be unique with type under the same parent.

typestring · enumRequired

The object type. Only FOLDER and SECURABLE are supported for manual create (Custom connections).

Possible values:

parentIdstring · uuidOptional

Parent data object ID (CONNECTION root or FOLDER). Omit to create under the connection root. Do not pass null.

Pattern:

^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000)$

Responses

201

Data object created

application/json

The created data object.

idstringRequired

The unique, Immuta-generated identifier (UUID) for the data object.

namestring · min: 1Required

The name of the data object.

typestring · min: 1Required

The type of the data object.

normalizedTypestring · min: 1Required

The normalized type of the data object.

technologystring · min: 1Required

The technology of the data platform.

remoteIdstring · min: 1Required

The remote identifier for the data object.

remoteTypestringOptional

The type of the data object as returned by the remote platform.

remoteFormatstringOptional

The format of the data object as returned by the remote platform.

remoteKindstringOptional

The kind of the data object as returned by the remote platform.

remoteCreatedAtstring · date-timeOptional

The timestamp of the creation of the data object as returned by the remote platform.

remoteUpdatedAtstring · date-timeOptional

The timestamp of the last update of the data object as returned by the remote platform.

lastSyncedAtstring · date-timeRequired

The timestamp of the last sync of this data object.

connectionKeystring · min: 1Required

Example: my-connection

createdBystringRequired

The user or system account ID who created the data object.

createdAtstring · date-timeRequired

The date and time the data object was created.

updatedBystringRequired

The user or system account ID who updated the data object.

updatedAtstring · date-timeRequired

The date and time the data object was updated.

400

Invalid request or unsupported parent/technology

application/json

404

Connection or parent data object not found

application/json

409

A data object with this name and type already exists under the parent

application/json

post/api/connections/{connectionKey}/dataObjects

POST /api/connections/{connectionKey}/dataObjects HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 81

{
  "name": "text",
  "type": "FOLDER",
  "parentId": "123e4567-e89b-12d3-a456-426614174000"
}

{
  "id": "text",
  "name": "text",
  "type": "text",
  "normalizedType": "text",
  "technology": "text",
  "remoteId": "text",
  "remoteType": "text",
  "remoteFormat": "text",
  "remoteKind": "text",
  "remoteCreatedAt": "2026-01-01T00:00:00.000Z",
  "remoteUpdatedAt": "2026-01-01T00:00:00.000Z",
  "objectPath": {
    "name": "text",
    "type": "text",
    "id": "text",
    "child": {
      "name": "text",
      "type": "text",
      "id": "text",
      "child": {
        "name": "text",
        "type": "text",
        "id": "text",
        "child": {
          "name": "text",
          "type": "text",
          "id": "text",
          "child": {
            "name": "text",
            "type": "text",
            "id": "text",
            "child": "[Circular Reference]"
          }
        }
      }
    }
  },
  "lastSyncedAt": "2026-01-01T00:00:00.000Z",
  "settings": {
    "syncPolicy": {
      "value": true,
      "inheritedFrom": {
        "id": "text",
        "type": "CONNECTION"
      }
    },
    "owners": [
      {
        "id": 1,
        "type": "USER",
        "inheritedFrom": {
          "id": "text",
          "type": "CONNECTION"
        }
      }
    ]
  },
  "tags": [
    {
      "id": 1,
      "name": "text",
      "displayName": "text",
      "source": "text",
      "inheritedFrom": {
        "id": "text",
        "type": "CONNECTION"
      },
      "application": {
        "appliedAt": "2026-01-01T00:00:00.000Z",
        "appliedBy": {
          "profileId": 1,
          "name": "text"
        },
        "context": "text"
      }
    }
  ],
  "connectionKey": "my-connection",
  "createdBy": "text",
  "createdAt": "2026-01-01T00:00:00.000Z",
  "updatedBy": "text",
  "updatedAt": "2026-01-01T00:00:00.000Z"
}

Get the children of a data object by connection and ID

get

Get the children of a data object by connection and ID.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

connectionKeystring · min: 1Required

Example: my-connection

idstringRequired

The unique, Immuta-generated identifier (UUID) for the data object.

Query parameters

page[limit]integer · min: 1 · max: 100Optional

Maximum number of items to return.

Default: 20Example: 20

page[cursor]stringOptional

The cursor to start from.

Example: eyJpZCI6IjEyMzQ1In0=

Responses

200

Data object children

application/json

The response schema for getting the children of a data object.

404

Connection or data object not found

application/json

get/api/connections/{connectionKey}/dataObjects/{id}/children

GET /api/connections/{connectionKey}/dataObjects/{id}/children HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "data": [
    {
      "id": "text",
      "name": "text",
      "type": "text",
      "normalizedType": "text",
      "technology": "text",
      "remoteId": "text",
      "remoteType": "text",
      "remoteFormat": "text",
      "remoteKind": "text",
      "remoteCreatedAt": "2026-01-01T00:00:00.000Z",
      "remoteUpdatedAt": "2026-01-01T00:00:00.000Z",
      "objectPath": {
        "name": "text",
        "type": "text",
        "id": "text",
        "child": {
          "name": "text",
          "type": "text",
          "id": "text",
          "child": {
            "name": "text",
            "type": "text",
            "id": "text",
            "child": "[Circular Reference]"
          }
        }
      },
      "lastSyncedAt": "2026-01-01T00:00:00.000Z",
      "settings": {
        "syncPolicy": {
          "value": true,
          "inheritedFrom": {
            "id": "text",
            "type": "CONNECTION"
          }
        },
        "owners": [
          {
            "id": 1,
            "type": "USER",
            "inheritedFrom": {
              "id": "text",
              "type": "CONNECTION"
            }
          }
        ]
      },
      "tags": [
        {
          "id": 1,
          "name": "text",
          "displayName": "text",
          "source": "text",
          "inheritedFrom": {
            "id": "text",
            "type": "CONNECTION"
          },
          "application": {
            "appliedAt": "2026-01-01T00:00:00.000Z",
            "appliedBy": {
              "profileId": 1,
              "name": "text"
            },
            "context": "text"
          }
        }
      ],
      "connectionKey": "my-connection",
      "createdBy": "text",
      "createdAt": "2026-01-01T00:00:00.000Z",
      "updatedBy": "text",
      "updatedAt": "2026-01-01T00:00:00.000Z"
    }
  ],
  "meta": {
    "sort": [
      {
        "field": "name",
        "order": "asc"
      }
    ],
    "page": {
      "limit": 20,
      "cursor": "eyJpZCI6IjEyMzQ1In0="
    },
    "totalCount": 1
  }
}

Get a task run by ID

get

Get a task run by ID.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

connectionKeystring · min: 1Required

Example: my-connection

taskIdstring · uuidRequired

The task ID.

Pattern:

^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000)$

runIdstring · uuidRequired

The run ID.

Pattern:

^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000)$

Responses

200

Task run details

application/json

The get task run response schema.

runIdstring · uuidRequired

The run ID.

Pattern:

^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000)$

statusstring · enumRequired

The task run status.

Possible values:

createdAtstring · date-timeRequired

When the task run was created.

updatedAtstring · date-timeRequired

When the task run was last updated.

startedAtstring · date-timeOptional

When the task run was started.

completedAtstring · date-timeOptional

When the task run was completed.

canceledBystring · min: 1Optional

The user or system account ID that canceled the task run.

400

Invalid request payload

application/json

404

Connection, task, or run ID not found

application/json

get/api/connections/{connectionKey}/tasks/{taskId}/runs/{runId}

GET /api/connections/{connectionKey}/tasks/{taskId}/runs/{runId} HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "runId": "123e4567-e89b-12d3-a456-426614174000",
  "status": "PENDING",
  "createdAt": "2026-01-01T00:00:00.000Z",
  "updatedAt": "2026-01-01T00:00:00.000Z",
  "startedAt": "2026-01-01T00:00:00.000Z",
  "completedAt": "2026-01-01T00:00:00.000Z",
  "canceledBy": "text",
  "result": {
    "message": "text",
    "details": null
  },
  "error": {
    "code": "CONN001",
    "message": "text",
    "details": null
  }
}

Request to cancel a task run by ID

post

Cancels a task run in PENDING status and marks it CANCELED. Requests for runs in any other status return a conflict response. Use the GET endpoint to monitor the task run status.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

connectionKeystring · min: 1Required

Example: my-connection

taskIdstring · uuidRequired

The task ID.

Pattern:

^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000)$

runIdstring · uuidRequired

The run ID.

Pattern:

^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000)$

Responses

200

Task run cancelled response.

application/json

The cancel task run response schema.

runIdstring · uuidRequired

The run ID.

Pattern:

^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000)$

messagestringRequired

The cancel task run response message.

404

Connection, task, or run ID not found

application/json

post/api/connections/{connectionKey}/tasks/{taskId}/runs/{runId}/_cancel

POST /api/connections/{connectionKey}/tasks/{taskId}/runs/{runId}/_cancel HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "runId": "123e4567-e89b-12d3-a456-426614174000",
  "message": "text"
}

Get a list of tasks

get

Get a list of tasks for a connection.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

connectionKeystring · min: 1Required

Example: my-connection

Query parameters

page[limit]integer · min: 1 · max: 100Optional

Maximum number of items to return.

Default: 20Example: 20

page[cursor]stringOptional

The cursor to start from.

Example: eyJpZCI6IjEyMzQ1In0=

filter[type]string · enumOptional

Filter by task type.

Possible values:

filter[status]string · enumOptional

Filter by task status.

Possible values:

filter[trigger]string · enumOptional

Filter by trigger type.

Possible values:

filter[createdBy]stringOptional

Filter by the creator of the task using user or system account ID.

filter[parentId]string · uuidOptional

Filter by parent task ID.

Pattern:

^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000)$

Responses

200

Tasks list

application/json

The get tasks response schema.

tasksone of[]Required

400

Invalid request payload

application/json

404

Connection not found

application/json

get/api/connections/{connectionKey}/tasks

GET /api/connections/{connectionKey}/tasks HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "tasks": [
    {
      "taskId": "123e4567-e89b-12d3-a456-426614174000",
      "type": "text",
      "status": "PENDING",
      "trigger": "MANUAL",
      "createdBy": "text",
      "createdAt": "2026-01-01T00:00:00.000Z",
      "parentId": "123e4567-e89b-12d3-a456-426614174000",
      "input": {
        "objectPath": {
          "name": "text",
          "type": "text",
          "child": {
            "name": "text",
            "type": "text",
            "child": "[Circular Reference]"
          }
        },
        "syncAllDataObjects": false
      }
    }
  ],
  "meta": {
    "sort": [
      {
        "field": "type",
        "order": "asc"
      }
    ],
    "page": {
      "limit": 20,
      "cursor": "eyJpZCI6IjEyMzQ1In0="
    }
  }
}

Create a new task

post

Create a new task.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

connectionKeystring · min: 1Required

Example: my-connection

Body

The create task request schema.

typeconst: DATA_OBJECT_SYNCRequired

Responses

200

Task created

application/json

The create task response schema.

taskIdstring · uuidRequired

The task ID.

Pattern:

^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000)$

typeconst: DATA_OBJECT_SYNCRequired

statusstring · enumRequired

The task run status.

Possible values:

triggerstring · enumRequired

The task run trigger.

Possible values:

createdBystring · min: 1Required

The user or system account ID that created the task.

createdAtstring · date-timeRequired

When the task was created.

parentIdstring · uuidOptional

The parent task ID for hierarchical tasks.

Pattern:

^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000)$

400

Invalid request payload

application/json

404

Connection not found

application/json

409

A task with the same type and input is already in flight (status PENDING or RUNNING) for this connection. The body carries taskId so the caller can poll the existing task.

application/json

503

Task service unavailable

application/json

post/api/connections/{connectionKey}/tasks

POST /api/connections/{connectionKey}/tasks HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 240

{
  "type": "text",
  "input": {
    "objectPath": {
      "name": "text",
      "type": "text",
      "child": {
        "name": "text",
        "type": "text",
        "child": {
          "name": "text",
          "type": "text",
          "child": {
            "name": "text",
            "type": "text",
            "child": "[Circular Reference]"
          }
        }
      }
    },
    "syncAllDataObjects": false
  }
}

{
  "taskId": "123e4567-e89b-12d3-a456-426614174000",
  "type": "text",
  "status": "PENDING",
  "trigger": "MANUAL",
  "createdBy": "text",
  "createdAt": "2026-01-01T00:00:00.000Z",
  "parentId": "123e4567-e89b-12d3-a456-426614174000",
  "input": {
    "objectPath": {
      "name": "text",
      "type": "text",
      "child": {
        "name": "text",
        "type": "text",
        "child": {
          "name": "text",
          "type": "text",
          "child": {
            "name": "text",
            "type": "text",
            "child": "[Circular Reference]"
          }
        }
      }
    },
    "syncAllDataObjects": false
  }
}

Get a task by ID

get

Get a task by ID.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

connectionKeystring · min: 1Required

Example: my-connection

taskIdstring · uuidRequired

The task ID.

Pattern:

^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000)$

Responses

200

Task details

application/json

400

Invalid request payload

application/json

404

Connection or task ID not found

application/json

get/api/connections/{connectionKey}/tasks/{taskId}

GET /api/connections/{connectionKey}/tasks/{taskId} HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "taskId": "123e4567-e89b-12d3-a456-426614174000",
  "type": "text",
  "status": "PENDING",
  "trigger": "MANUAL",
  "createdBy": "text",
  "createdAt": "2026-01-01T00:00:00.000Z",
  "parentId": "123e4567-e89b-12d3-a456-426614174000",
  "input": {
    "objectPath": {
      "name": "text",
      "type": "text",
      "child": {
        "name": "text",
        "type": "text",
        "child": {
          "name": "text",
          "type": "text",
          "child": "[Circular Reference]"
        }
      }
    },
    "syncAllDataObjects": false
  }
}

Get task runs for a task

get

Get task runs for a specific task.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

connectionKeystring · min: 1Required

Example: my-connection

taskIdstring · uuidRequired

The task ID.

Pattern:

^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000)$

Query parameters

page[limit]integer · min: 1 · max: 100Optional

Maximum number of items to return.

Default: 20Example: 20

page[cursor]stringOptional

The cursor to start from.

Example: eyJpZCI6IjEyMzQ1In0=

filter[status]string · enumOptional

Filter by task run status.

Possible values:

Responses

200

Task runs list

application/json

The get task runs response schema.

400

Invalid request payload

application/json

404

Connection or task ID not found

application/json

get/api/connections/{connectionKey}/tasks/{taskId}/runs

GET /api/connections/{connectionKey}/tasks/{taskId}/runs HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "runs": [
    {
      "runId": "123e4567-e89b-12d3-a456-426614174000",
      "status": "PENDING",
      "createdAt": "2026-01-01T00:00:00.000Z",
      "updatedAt": "2026-01-01T00:00:00.000Z",
      "startedAt": "2026-01-01T00:00:00.000Z",
      "completedAt": "2026-01-01T00:00:00.000Z",
      "canceledBy": "text",
      "result": {
        "message": "text",
        "details": null
      },
      "error": {
        "code": "CONN001",
        "message": "text",
        "details": null
      }
    }
  ],
  "meta": {
    "sort": [
      {
        "field": "status",
        "order": "asc"
      }
    ],
    "page": {
      "limit": 20,
      "cursor": "eyJpZCI6IjEyMzQ1In0="
    }
  }
}

PreviousConnections API

NextHow-to Guides

Last updated 15 days ago

Was this helpful?