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 URI. If you’ve already authorized specific redirect URIs, this URI must be one of them. 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.

Authorized redirect URIs

By default, the dataConnectors.authorizeConnection method accepts any redirect URI. To restrict it, authorize specific redirect URIs: once you register one or more, the method accepts only those. This keeps the OAuth callback (and the connection identifier it returns) from reaching an endpoint you don’t control.

Use the following methods to manage your authorized redirect URIs:

dataConnectors.createRedirectUri: Authorize a redirect URI. Each URI must use HTTPS, resolve to a public host, and contain no wildcards.
dataConnectors.listRedirectUris: Return your authorized redirect URIs.
dataConnectors.deleteRedirectUri: Remove a redirect URI so it is no longer authorized.

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 URI you provided, with the outcome appended to that URI 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: The ok value, returned 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 URI where the user is redirected after granting or denying access. By default, any redirect URI is accepted. If you’ve authorized specific redirect URIs with the Register a redirect URI method, this URI must be one of them.
`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.

Register a redirect URI

Description: This method registers a redirect URI so the Authorize a connection method accepts it. The URI must use HTTPS and resolve to a public host.

Function signature and example:

1 createRedirectUri(
2   request: TwelvelabsApi.CreateRedirectUriRequest,
3   requestOptions?: DataConnectors.RequestOptions
4 ): Promise<TwelvelabsApi.RedirectUri>

Parameters

Name	Type	Required	Description
`redirectUri`	`string`	Yes	The redirect URI to register. Must use HTTPS, resolve to a public host, and contain no wildcards. Register it exactly as your application sends it, because the authorization flow requires an exact match.
`requestOptions`	`DataConnectors.` `RequestOptions`	No	Per-call SDK settings such as timeout, retries, and headers. For all fields, see Request options.

Return value

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

Name	Type	Description
`id`	`string`	The unique identifier of the redirect URI.
`redirectUri`	`string`	The registered redirect URI.
`createdAt`	`Date`	The date and time, in the RFC 3339 format (“YYYY-MM-DDTHH:mm:ssZ”), when the redirect URI was registered.

API Reference

List redirect URIs

Description: This method returns your authorized redirect URIs, sorted by creation date with the newest at the top. Each one is a redirect URI the Authorize a connection method accepts.

Function signature and example:

1 listRedirectUris(
2   request?: TwelvelabsApi.ListRedirectUrisRequest,
3   requestOptions?: DataConnectors.RequestOptions
4 ): Promise<TwelvelabsApi.ListRedirectUrisResponse>

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 ListRedirectUrisResponse object. The ListRedirectUrisResponse object contains the following properties:

Name	Type	Description
`data`	`RedirectUri[]`	An array containing the redirect URIs. For the properties of each `RedirectUri` object, see Register a redirect URI.
`pageInfo`	`PageInfo`	An object that provides information about pagination. Contains the `page`, `limitPerPage`, `totalPage`, and `totalResults` fields.

API Reference

List redirect URIs.

Delete a redirect URI

Description: This method removes a redirect URI from your authorized redirect URIs. After deletion, the Authorize a connection method no longer accepts it. This action cannot be undone.

Function signature and example:

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

Parameters

Name	Type	Required	Description
`redirectUriId`	`string`	Yes	The unique identifier of the redirect URI 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 redirect URI.