> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.twelvelabs.io/v1.3/sdk-reference/node-js/data-connectors/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.twelvelabs.io/_mcp/server. # Data connectors > Connect external data providers and manage connections with the Node.js SDK. 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`](#authorize-a-connection) method, passing your redirect URI. If you've already [authorized specific redirect URIs](#authorized-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`](#generate-a-picker-token) 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`](/v1.3/sdk-reference/node-js/data-connectors/imports#import-files) method. The `action` property of each item in the result identifies which files were newly imported and which were already imported. Each newly imported file becomes an asset in the `processing` status. Poll the [`imports.retrieveImport`](/v1.3/sdk-reference/node-js/data-connectors/imports#retrieve-an-import) 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`](#delete-a-connection) method. The platform revokes access and deletes the stored tokens. Assets you already imported are retained. # Authorized redirect URIs By default, the [`dataConnectors.authorizeConnection`](#authorize-a-connection) 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`](#register-a-redirect-uri): Authorize a redirect URI. Each URI must use HTTPS, resolve to a public host, and contain no wildcards. * [`dataConnectors.listRedirectUris`](#list-redirect-uris): Return your authorized redirect URIs. * [`dataConnectors.deleteRedirectUri`](#delete-a-redirect-uri): 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**: **`Function signature`** ```javascript Function signature authorizeConnection( request: TwelvelabsApi.AuthorizeConnectionRequest, requestOptions?: DataConnectors.RequestOptions ): Promise ``` **`Node.js example`** ```javascript Node.js example import { TwelveLabs } from "twelvelabs-js"; const client = new TwelveLabs({ apiKey: "" }); const response = await client.dataConnectors.authorizeConnection({ provider: "google_drive", redirectUri: "https://app.example.com/oauth/done", // customId: "end-user-1234", }); console.log(response.authorizeUrl); ``` ### 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](#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](/v1.3/sdk-reference/node-js/the-twelve-labs-class#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](/v1.3/api-reference/data-connectors/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**: **`Function signature`** ```javascript Function signature listConnections( request?: TwelvelabsApi.ListConnectionsRequest, requestOptions?: DataConnectors.RequestOptions ): Promise ``` **`Node.js example`** ```javascript Node.js example import { TwelveLabs } from "twelvelabs-js"; const client = new TwelveLabs({ apiKey: "" }); const response = await client.dataConnectors.listConnections({ // page: 1, // pageLimit: 10, }); console.log(response.data); ``` ### 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](/v1.3/sdk-reference/node-js/the-twelve-labs-class#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](#retrieve-a-connection). | | `pageInfo` | `PageInfo` | An object that provides information about pagination. Contains the `page`, `limitPerPage`, `totalPage`, and `totalResults` fields. | ### API Reference [List connections](/v1.3/api-reference/data-connectors/list-connections). ## Retrieve a connection **Description**: This method retrieves details about the specified connection. **Function signature and example**: **`Function signature`** ```javascript Function signature retrieveConnection( connectionId: string, requestOptions?: DataConnectors.RequestOptions ): Promise ``` **`Node.js example`** ```javascript Node.js example import { TwelveLabs } from "twelvelabs-js"; const client = new TwelveLabs({ apiKey: "" }); const connection = await client.dataConnectors.retrieveConnection(""); console.log(connection.status); ``` ### 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](/v1.3/sdk-reference/node-js/the-twelve-labs-class#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 you [authorized the connection](#authorize-a-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](/v1.3/api-reference/data-connectors/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**: **`Function signature`** ```javascript Function signature deleteConnection( connectionId: string, requestOptions?: DataConnectors.RequestOptions ): Promise ``` **`Node.js example`** ```javascript Node.js example import { TwelveLabs } from "twelvelabs-js"; const client = new TwelveLabs({ apiKey: "" }); await client.dataConnectors.deleteConnection(""); ``` ### 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](/v1.3/sdk-reference/node-js/the-twelve-labs-class#request-options). | ### Return value This method does not return a value. ### API Reference [Delete a connection](/v1.3/api-reference/data-connectors/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**: **`Function signature`** ```javascript Function signature createConnectionPickerToken( connectionId: string, requestOptions?: DataConnectors.RequestOptions ): Promise ``` **`Node.js example`** ```javascript Node.js example import { TwelveLabs } from "twelvelabs-js"; const client = new TwelveLabs({ apiKey: "" }); const token = await client.dataConnectors.createConnectionPickerToken(""); console.log(token.accessToken); ``` ### 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](/v1.3/sdk-reference/node-js/the-twelve-labs-class#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](/v1.3/api-reference/data-connectors/generate-a-picker-token). ## Register a redirect URI **Description**: This method registers a redirect URI so the [Authorize a connection](#authorize-a-connection) method accepts it. The URI must use HTTPS and resolve to a public host. **Function signature and example**: **`Function signature`** ```javascript Function signature createRedirectUri( request: TwelvelabsApi.CreateRedirectUriRequest, requestOptions?: DataConnectors.RequestOptions ): Promise ``` **`Node.js example`** ```javascript Node.js example import { TwelveLabs } from "twelvelabs-js"; const client = new TwelveLabs({ apiKey: "" }); const redirectUri = await client.dataConnectors.createRedirectUri({ redirectUri: "https://app.example.com/oauth/done", }); console.log(redirectUri.id); ``` ### 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](/v1.3/sdk-reference/node-js/the-twelve-labs-class#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 [Register a redirect URI](/v1.3/api-reference/data-connectors/register-a-redirect-uri). ## 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](#authorize-a-connection) method accepts. **Function signature and example**: **`Function signature`** ```javascript Function signature listRedirectUris( request?: TwelvelabsApi.ListRedirectUrisRequest, requestOptions?: DataConnectors.RequestOptions ): Promise ``` **`Node.js example`** ```javascript Node.js example import { TwelveLabs } from "twelvelabs-js"; const client = new TwelveLabs({ apiKey: "" }); const response = await client.dataConnectors.listRedirectUris({ // page: 1, // pageLimit: 10, }); console.log(response.data); ``` ### 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](/v1.3/sdk-reference/node-js/the-twelve-labs-class#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](#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](/v1.3/api-reference/data-connectors/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](#authorize-a-connection) method no longer accepts it. This action cannot be undone. **Function signature and example**: **`Function signature`** ```javascript Function signature deleteRedirectUri( redirectUriId: string, requestOptions?: DataConnectors.RequestOptions ): Promise ``` **`Node.js example`** ```javascript Node.js example import { TwelveLabs } from "twelvelabs-js"; const client = new TwelveLabs({ apiKey: "" }); await client.dataConnectors.deleteRedirectUri(""); ``` ### 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](/v1.3/sdk-reference/node-js/the-twelve-labs-class#request-options). | ### Return value This method does not return a value. ### API Reference [Delete a redirect URI](/v1.3/api-reference/data-connectors/delete-a-redirect-uri). > Connect external data providers and manage connections with the Node.js SDK. ## Docs - [Imports](https://docs.twelvelabs.io/sdk-reference/node-js/data-connectors/imports.md): Import files from a connected account with the Node.js SDK.