Connections API

Get an existing connection

get

Get an existing connection with all credentials redacted.

Authorizations

bearerAuth

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. Sensitive strings will be returned with a value of '[REDACTED]'.

or

400

Invalid request payload

application/json

404

Connection not found

application/json

get

/api/connections/{connectionKey}

HTTPcURLJavaScriptPython

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": "AB:CD:EF:12:34:56",
      "resource": "https://api.example.com",
      "privateKey": {
        "name": "my-private-key",
        "filename": "my-private-key.pem",
        "content": "-----BEGIN PRIVATE KEY-----\n...your-private-key-content...\n-----END PRIVATE KEY-----"
      }
    },
    "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",
    "immutaSystemCatalog": "immuta_system",
    "proxy": {
      "host": "https://proxy.example.com",
      "port": 8080,
      "credential": {
        "authenticationType": "text",
        "username": "my-username",
        "password": "my-password"
      }
    }
  },
  "state": "ACTIVE",
  "activeTasks": [
    {
      "taskId": "123e4567-e89b-12d3-a456-426614174000",
      "type": "text",
      "status": "PENDING",
      "trigger": "MANUAL",
      "createdBy": "text",
      "createdAt": "2026-05-13T22:41:57.480Z"
    }
  ],
  "connectionKey": "my-connection",
  "createdBy": "text",
  "createdAt": "2026-05-13T22:41:57.480Z",
  "updatedBy": "text",
  "updatedAt": "2026-05-13T22:41:57.480Z",
  "dataObjectDefaults": {
    "syncPolicy": false,
    "owners": [
      {
        "id": 1,
        "type": "USER"
      }
    ]
  },
  "dataObjectSync": {
    "enabled": true,
    "schedule": "EVERY_HOUR",
    "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"
    }
  ]
}

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.

Authorizations

bearerAuth

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

202

Deletion task created and accepted for processing

application/json

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}

HTTPcURLJavaScriptPython

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

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

Partially update the connection

patch

Partially update the connection for the specified connection key.

Authorizations

bearerAuth

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

Query parameters

dryRunstringOptional

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

Body

application/json

The update connection request payload schema.

or

Responses

200

Connection object

application/json

The update connection response schema.

or

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}

HTTPcURLJavaScriptPython

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

{
  "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": {
        "name": "my-private-key",
        "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"
      }
    }
  },
  "dataObjectDefaults": {
    "syncPolicy": true,
    "owners": [
      {
        "id": 1,
        "type": "USER"
      }
    ]
  },
  "dataObjectSync": {
    "enabled": true,
    "schedule": "EVERY_HOUR",
    "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": "AB:CD:EF:12:34:56",
      "resource": "https://api.example.com",
      "privateKey": {
        "name": "my-private-key",
        "filename": "my-private-key.pem",
        "content": "-----BEGIN PRIVATE KEY-----\n...your-private-key-content...\n-----END PRIVATE KEY-----"
      }
    },
    "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",
    "immutaSystemCatalog": "immuta_system",
    "proxy": {
      "host": "https://proxy.example.com",
      "port": 8080,
      "credential": {
        "authenticationType": "text",
        "username": "my-username",
        "password": "my-password"
      }
    }
  },
  "state": "ACTIVE",
  "activeTasks": [
    {
      "taskId": "123e4567-e89b-12d3-a456-426614174000",
      "type": "text",
      "status": "PENDING",
      "trigger": "MANUAL",
      "createdBy": "text",
      "createdAt": "2026-05-13T22:41:57.480Z"
    }
  ],
  "connectionKey": "my-connection",
  "createdBy": "text",
  "createdAt": "2026-05-13T22:41:57.480Z",
  "updatedBy": "text",
  "updatedAt": "2026-05-13T22:41:57.480Z",
  "dataObjectDefaults": {
    "syncPolicy": false,
    "owners": [
      {
        "id": 1,
        "type": "USER"
      }
    ]
  },
  "dataObjectSync": {
    "enabled": true,
    "schedule": "EVERY_HOUR",
    "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"
    }
  ]
}

Activate the connection

post

Activate the connection for the specified connection key.

Authorizations

bearerAuth

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

Successfully activated connection

application/json

The activate connection response schema.

or

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

HTTPcURLJavaScriptPython

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": "AB:CD:EF:12:34:56",
      "resource": "https://api.example.com",
      "privateKey": {
        "name": "my-private-key",
        "filename": "my-private-key.pem",
        "content": "-----BEGIN PRIVATE KEY-----\n...your-private-key-content...\n-----END PRIVATE KEY-----"
      }
    },
    "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",
    "immutaSystemCatalog": "immuta_system",
    "proxy": {
      "host": "https://proxy.example.com",
      "port": 8080,
      "credential": {
        "authenticationType": "text",
        "username": "my-username",
        "password": "my-password"
      }
    }
  },
  "state": "ACTIVE",
  "activeTasks": [
    {
      "taskId": "123e4567-e89b-12d3-a456-426614174000",
      "type": "text",
      "status": "PENDING",
      "trigger": "MANUAL",
      "createdBy": "text",
      "createdAt": "2026-05-13T22:41:57.480Z"
    }
  ],
  "connectionKey": "my-connection",
  "createdBy": "text",
  "createdAt": "2026-05-13T22:41:57.480Z",
  "updatedBy": "text",
  "updatedAt": "2026-05-13T22:41:57.480Z",
  "dataObjectDefaults": {
    "syncPolicy": false,
    "owners": [
      {
        "id": 1,
        "type": "USER"
      }
    ]
  },
  "dataObjectSync": {
    "enabled": true,
    "schedule": "EVERY_HOUR",
    "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"
    }
  ]
}

Deactivate the connection

post

Deactivate the connection for the specified connection key.

Authorizations

bearerAuth

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

Successfully deactivated connection

application/json

The deactivate connection response schema.

or

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

HTTPcURLJavaScriptPython

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": "AB:CD:EF:12:34:56",
      "resource": "https://api.example.com",
      "privateKey": {
        "name": "my-private-key",
        "filename": "my-private-key.pem",
        "content": "-----BEGIN PRIVATE KEY-----\n...your-private-key-content...\n-----END PRIVATE KEY-----"
      }
    },
    "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",
    "immutaSystemCatalog": "immuta_system",
    "proxy": {
      "host": "https://proxy.example.com",
      "port": 8080,
      "credential": {
        "authenticationType": "text",
        "username": "my-username",
        "password": "my-password"
      }
    }
  },
  "state": "ACTIVE",
  "activeTasks": [
    {
      "taskId": "123e4567-e89b-12d3-a456-426614174000",
      "type": "text",
      "status": "PENDING",
      "trigger": "MANUAL",
      "createdBy": "text",
      "createdAt": "2026-05-13T22:41:57.480Z"
    }
  ],
  "connectionKey": "my-connection",
  "createdBy": "text",
  "createdAt": "2026-05-13T22:41:57.480Z",
  "updatedBy": "text",
  "updatedAt": "2026-05-13T22:41:57.480Z",
  "dataObjectDefaults": {
    "syncPolicy": false,
    "owners": [
      {
        "id": 1,
        "type": "USER"
      }
    ]
  },
  "dataObjectSync": {
    "enabled": true,
    "schedule": "EVERY_HOUR",
    "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

bearerAuth

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

202

Validation task created and accepted for processing

application/json

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

HTTPcURLJavaScriptPython

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

bearerAuth

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.

get

/api/connections

HTTPcURLJavaScriptPython

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": "AB:CD:EF:12:34:56",
          "resource": "https://api.example.com",
          "privateKey": {
            "name": "my-private-key",
            "filename": "my-private-key.pem",
            "content": "-----BEGIN PRIVATE KEY-----\n...your-private-key-content...\n-----END PRIVATE KEY-----"
          }
        },
        "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",
        "immutaSystemCatalog": "immuta_system",
        "proxy": {
          "host": "https://proxy.example.com",
          "port": 8080,
          "credential": {
            "authenticationType": "text",
            "username": "my-username",
            "password": "my-password"
          }
        }
      },
      "state": "ACTIVE",
      "activeTasks": [
        {
          "taskId": "123e4567-e89b-12d3-a456-426614174000",
          "type": "text",
          "status": "PENDING",
          "trigger": "MANUAL",
          "createdBy": "text",
          "createdAt": "2026-05-13T22:41:57.480Z"
        }
      ],
      "connectionKey": "my-connection",
      "createdBy": "text",
      "createdAt": "2026-05-13T22:41:57.480Z",
      "updatedBy": "text",
      "updatedAt": "2026-05-13T22:41:57.480Z",
      "dataObjectDefaults": {
        "syncPolicy": false,
        "owners": [
          {
            "id": 1,
            "type": "USER"
          }
        ]
      },
      "dataObjectSync": {
        "enabled": true,
        "schedule": "EVERY_HOUR",
        "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

bearerAuth

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Body

application/json

The create connection request payload schema.

or

Responses

201

Connection object

application/json

400

Invalid request payload

application/json

409

Unable to create connection. Connection key already exists.

application/json

post

/api/connections

HTTPcURLJavaScriptPython

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

{
  "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": {
        "name": "my-private-key",
        "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": "AB:CD:EF:12:34:56",
      "resource": "https://api.example.com",
      "privateKey": {
        "name": "my-private-key",
        "filename": "my-private-key.pem",
        "content": "-----BEGIN PRIVATE KEY-----\n...your-private-key-content...\n-----END PRIVATE KEY-----"
      }
    },
    "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",
    "immutaSystemCatalog": "immuta_system",
    "proxy": {
      "host": "https://proxy.example.com",
      "port": 8080,
      "credential": {
        "authenticationType": "text",
        "username": "my-username",
        "password": "my-password"
      }
    }
  },
  "state": "ACTIVE",
  "activeTasks": [
    {
      "taskId": "123e4567-e89b-12d3-a456-426614174000",
      "type": "text",
      "status": "PENDING",
      "trigger": "MANUAL",
      "createdBy": "text",
      "createdAt": "2026-05-13T22:41:57.480Z"
    }
  ],
  "connectionKey": "my-connection",
  "createdBy": "text",
  "createdAt": "2026-05-13T22:41:57.480Z",
  "updatedBy": "text",
  "updatedAt": "2026-05-13T22:41:57.480Z",
  "dataObjectDefaults": {
    "syncPolicy": false,
    "owners": [
      {
        "id": 1,
        "type": "USER"
      }
    ]
  },
  "dataObjectSync": {
    "enabled": true,
    "schedule": "EVERY_HOUR",
    "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"
    }
  ]
}

Search for data objects by connection and attributes

post

Search for data objects by connection and attributes.

Authorizations

bearerAuth

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Body

application/json

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

HTTPcURLJavaScriptPython

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-05-13T22:41:57.480Z",
      "remoteUpdatedAt": "2026-05-13T22:41:57.480Z",
      "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-05-13T22:41:57.480Z",
      "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",
          "inheritedFrom": {
            "id": "text",
            "type": "CONNECTION"
          }
        }
      ],
      "connectionKey": "my-connection",
      "createdBy": "text",
      "createdAt": "2026-05-13T22:41:57.480Z",
      "updatedBy": "text",
      "updatedAt": "2026-05-13T22:41:57.480Z"
    }
  ],
  "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

bearerAuth

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

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

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

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}

HTTPcURLJavaScriptPython

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-05-13T22:41:57.480Z",
  "remoteUpdatedAt": "2026-05-13T22:41:57.480Z",
  "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-05-13T22:41:57.480Z",
  "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",
      "inheritedFrom": {
        "id": "text",
        "type": "CONNECTION"
      }
    }
  ],
  "connectionKey": "my-connection",
  "createdBy": "text",
  "createdAt": "2026-05-13T22:41:57.480Z",
  "updatedBy": "text",
  "updatedAt": "2026-05-13T22:41:57.480Z"
}

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

bearerAuth

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

idstringRequired

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

Responses

202

Deletion task created and accepted for processing

application/json

404

Connection or data object not found

application/json

delete

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

HTTPcURLJavaScriptPython

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

bearerAuth

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

idstringRequired

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

Body

application/json

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

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

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}

HTTPcURLJavaScriptPython

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-05-13T22:41:57.480Z",
  "remoteUpdatedAt": "2026-05-13T22:41:57.480Z",
  "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-05-13T22:41:57.480Z",
  "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",
      "inheritedFrom": {
        "id": "text",
        "type": "CONNECTION"
      }
    }
  ],
  "connectionKey": "my-connection",
  "createdBy": "text",
  "createdAt": "2026-05-13T22:41:57.480Z",
  "updatedBy": "text",
  "updatedAt": "2026-05-13T22:41:57.480Z"
}

Get the children of a data object by connection and ID

get

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

Authorizations

bearerAuth

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

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

HTTPcURLJavaScriptPython

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-05-13T22:41:57.480Z",
      "remoteUpdatedAt": "2026-05-13T22:41:57.480Z",
      "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-05-13T22:41:57.480Z",
      "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",
          "inheritedFrom": {
            "id": "text",
            "type": "CONNECTION"
          }
        }
      ],
      "connectionKey": "my-connection",
      "createdBy": "text",
      "createdAt": "2026-05-13T22:41:57.480Z",
      "updatedBy": "text",
      "updatedAt": "2026-05-13T22:41:57.480Z"
    }
  ],
  "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

bearerAuth

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

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}

HTTPcURLJavaScriptPython

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-05-13T22:41:57.480Z",
  "updatedAt": "2026-05-13T22:41:57.480Z",
  "startedAt": "2026-05-13T22:41:57.480Z",
  "completedAt": "2026-05-13T22:41:57.480Z",
  "canceledBy": "text",
  "result": {
    "message": "text",
    "details": null
  },
  "error": {
    "code": "CONN001",
    "message": "text",
    "details": null
  }
}

Request to cancel a task run by ID

post

Request to cancel a task run by ID. This will not immediately cancel the task run, but will request the task run to be cancelled. To check the status of the task run, use the GET endpoint.

Authorizations

bearerAuth

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

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

HTTPcURLJavaScriptPython

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

bearerAuth

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

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

or

or

or

or

or

or

400

Invalid request payload

application/json

404

Connection not found

application/json

get

/api/connections/{connectionKey}/tasks

HTTPcURLJavaScriptPython

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-05-13T22:41:57.480Z",
      "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

bearerAuth

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

Body

application/json

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

HTTPcURLJavaScriptPython

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-05-13T22:41:57.480Z",
  "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

bearerAuth

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

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

or

or

or

or

or

or

400

Invalid request payload

application/json

404

Connection or task ID not found

application/json

get

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

HTTPcURLJavaScriptPython

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-05-13T22:41:57.480Z",
  "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

bearerAuth

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

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

HTTPcURLJavaScriptPython

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-05-13T22:41:57.480Z",
      "updatedAt": "2026-05-13T22:41:57.480Z",
      "startedAt": "2026-05-13T22:41:57.480Z",
      "completedAt": "2026-05-13T22:41:57.480Z",
      "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="
    }
  }
}