The DataConnectors class provides methods to connect an external data provider, such as Google Drive, and manage the resulting connections.

Import limits:

Video: Up to 10 GB
Audio: Up to 4 GB
Images: Up to 32 MB

You can import up to 100 files per request.

Workflow

Start the OAuth flow with the dataConnectors.authorizeConnection method, passing your redirect URL. Redirect the user to the authorization URL you receive. After the user grants access in the browser, the platform redirects them back, with the identifier of the new connection in the connection_id query parameter. Store this identifier.

Generate a short-lived access token with the dataConnectors.createConnectionPickerToken method. Use it with the Google Drive Picker so the user can select files, and store the identifier of each selected file.

Import the selected files with the imports.importFiles method. Each accepted file becomes an asset in the processing status.

Poll the imports.retrieveImport method until each item reaches the ready or failed status. Once an item is ready, use its asset identifier with the rest of the SDK.

(Optional) Disconnect the account with the dataConnectors.deleteConnection method. The platform revokes access and deletes the stored tokens. Assets you already imported are retained.

Methods

Authorize a connection

Description: This method starts the OAuth authorization flow for a data connector. The platform returns an authorization URL. Redirect the user to this URL so they can grant access to their account.

After the user grants or denies access, the platform redirects them to the redirect URL you provided, with the outcome appended to that URL as query parameters. Read these parameters from the redirect that your application receives:

connection_id: The identifier of the new connection, returned on success. Store this value and pass it as the connectionId argument in later requests.
status: Set to ok on success.
custom_id: The label you supplied, returned on success when you provided one.
error: An error code, returned instead of the other parameters when the user denies access or the flow fails.

Function signature and example:

1 authorizeConnection(
2   request: TwelvelabsApi.AuthorizeConnectionRequest,
3   requestOptions?: DataConnectors.RequestOptions
4 ): Promise<TwelvelabsApi.AuthorizeConnectionResponse>

Parameters

Name	Type	Required	Description
`provider`	`AuthorizeConnection` `RequestProvider`	Yes	The data connector provider to authorize. Values: `google_drive`.
`redirectUri`	`string`	Yes	The URL where the user is redirected after granting or denying access. If your account has an allow-list of redirect URLs configured, this URL must be on it.
`customId`	`string`	No	A label you supplied, stored on the connection and returned with it. Use a value that does not identify a person so you can match the connection to your own records.
`requestOptions`	`DataConnectors.` `RequestOptions`	No	Per-call SDK settings such as timeout, retries, and headers. For all fields, see Request options.

Return value

Returns an AuthorizeConnectionResponse object. The AuthorizeConnectionResponse object contains the following properties:

Name	Type	Description
`authorizeUrl`	`string`	The URL to redirect the user to so they can grant access.
`state`	`string`	A value the platform uses to secure the authorization flow. You do not need to read or send it: the platform includes it in the `authorizeUrl` field and checks it automatically when the user is redirected back. It is returned only so you can match or troubleshoot requests.

API Reference

Authorize a connection.

List connections

Description: This method returns a list of the connections in your account. The platform returns your connections sorted by creation date, with the newest at the top of the list.

Function signature and example:

1 listConnections(
2   request?: TwelvelabsApi.ListConnectionsRequest,
3   requestOptions?: DataConnectors.RequestOptions
4 ): Promise<TwelvelabsApi.ListConnectionsResponse>

Parameters

Name	Type	Required	Description
`page`	`number`	No	A number that identifies the page to retrieve. Default: `1`.
`pageLimit`	`number`	No	The number of items to return on each page. Default: `10`. Max: `50`.
`requestOptions`	`DataConnectors.` `RequestOptions`	No	Per-call SDK settings such as timeout, retries, and headers. For all fields, see Request options.

Return value

Returns a ListConnectionsResponse object. The ListConnectionsResponse object contains the following properties:

Name	Type	Description
`data`	`Connection[]`	An array containing the connections. For the properties of each `Connection` object, see Retrieve a connection.
`pageInfo`	`PageInfo`	An object that provides information about pagination. Contains the `page`, `limitPerPage`, `totalPage`, and `totalResults` fields.

API Reference

List connections.

Retrieve a connection

Description: This method retrieves details about the specified connection.

Function signature and example:

1 retrieveConnection(
2   connectionId: string,
3   requestOptions?: DataConnectors.RequestOptions
4 ): Promise<TwelvelabsApi.Connection>

Parameters

Name	Type	Required	Description
`connectionId`	`string`	Yes	The unique identifier of the connection to retrieve.
`requestOptions`	`DataConnectors.` `RequestOptions`	No	Per-call SDK settings such as timeout, retries, and headers. For all fields, see Request options.

Return value

Returns a Connection object. The Connection object contains the following properties:

Name	Type	Description
`id`	`string`	The unique identifier of the connection.
`provider`	`ConnectionProvider`	The data connector provider. Values: `google_drive`.
`status`	`ConnectionStatus`	The status of the connection. Values: `active`, `expired`, `revoked`.
`customId`	`string`	The label you supplied when creating the connection. The platform does not interpret this value, and it does not need to be unique. Multiple connections can share the same `customId` value.
`account`	`ConnectionAccount`	Information about the connected provider account.
`scopes`	`string[]`	The scopes granted to the connection.
`connectedAt`	`Date`	The date and time, in the RFC 3339 format (“YYYY-MM-DDTHH:mm:ssZ”), when the connection was established.
`lastUsedAt`	`Date`	The date and time, in the RFC 3339 format (“YYYY-MM-DDTHH:mm:ssZ”), when the connection was last used.

The ConnectionAccount object contains the following properties:

Name	Type	Description
`externalId`	`string`	The identifier of the account at the provider. It does not change.
`displayName`	`string`	A human-readable label for the account, such as an email address.

API Reference

Retrieve a connection.

Delete a connection

Description: This method disconnects the specified connection. The platform revokes access at the provider and deletes the stored tokens. Assets imported through this connection are retained.

Function signature and example:

1 deleteConnection(
2   connectionId: string,
3   requestOptions?: DataConnectors.RequestOptions
4 ): Promise<void>

Parameters

Name	Type	Required	Description
`connectionId`	`string`	Yes	The unique identifier of the connection to delete.
`requestOptions`	`DataConnectors.` `RequestOptions`	No	Per-call SDK settings such as timeout, retries, and headers. For all fields, see Request options.

Return value

This method does not return a value.

API Reference

Delete a connection.

Generate a picker token

Description: This method generates a short-lived, read-only access token that you use with the provider’s file picker, such as the Google Drive Picker. The platform never returns the refresh token of the connection.

Function signature and example:

1 createConnectionPickerToken(
2   connectionId: string,
3   requestOptions?: DataConnectors.RequestOptions
4 ): Promise<TwelvelabsApi.CreateConnectionPickerTokenResponse>

Parameters

Name	Type	Required	Description
`connectionId`	`string`	Yes	The unique identifier of the connection.
`requestOptions`	`DataConnectors.` `RequestOptions`	No	Per-call SDK settings such as timeout, retries, and headers. For all fields, see Request options.

Return value

Returns a CreateConnectionPickerTokenResponse object. The CreateConnectionPickerTokenResponse object contains the following properties:

Name	Type	Description
`accessToken`	`string`	A short-lived, read-only access token for use with the provider’s file picker.
`expiresIn`	`number`	The number of seconds until the token expires.
`scope`	`string`	A space-delimited list of the scopes granted to the token.
`appId`	`string`	The Google Cloud project number, used with the Google Picker’s `setAppId`. May be absent if the provider does not require this value for its picker.
`developerKey`	`string`	A browser API key, used with the Google Picker’s `setDeveloperKey`. May be absent if the provider does not require this value for its picker.

API Reference

Generate a picker token.