> This page is for version v1.3 (default).
> For other versions, use one of these documentation indexes:
> - v1.3 (default): https://docs.twelvelabs.io/v1.3/llms.txt

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.twelvelabs.io/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.twelvelabs.io/_mcp/server.

# Import files

POST https://api.twelvelabs.io/v1.3/connections/{connection_id}/imports
Content-Type: application/json

This method imports one or more files from the connected provider account into the platform as assets. Videos can be up to 10 GB, audio up to 4 GB, and images up to 32 MB. For each newly imported file, the platform creates an asset in the `processing` status and fetches the file asynchronously. If you import a file that was already imported through this account, the platform returns the existing asset with its current status, without fetching the file again. If the earlier fetch had failed, the platform fetches the file again. The response contains one entry per requested file, in request order. Use the `action` field of each entry to identify which files were newly imported and which were already imported.


Reference: https://docs.twelvelabs.io/api-reference/data-connectors/imports/import-files

## Authentication

- `x-api-key` header (required) — Your API key. You can find your API key on the API Keys page.

## Request

### Path parameters

- `connection_id` (string, required) — The unique identifier of the connection to import through.

### Body (application/json)

This endpoint expects an object.

- `items` (list of ConnectionsConnectionIdImportsPostRequestBodyContentApplicationJsonSchemaItemsItems, required) — The files to import. Provide an array of one item for a single import, or multiple items for a batch import. A maximum of 100 items can be imported per request. The `source_id` field of each item must be unique within a request.

## Response

### 202

The import request has been accepted. The response contains one item per requested file, in request order. Use the `action` field of each item to identify which files were newly imported and which were already imported. An accepted item includes the identifier and status of its asset. A rejected item includes an `error` object instead, and omits both. The `has_failures` field is `true` when at least one item was rejected. A rejected item does not fail the request; the response is `202` even when no item is accepted.

- `_id` (string, optional) — The unique identifier of the import created for this request.
- `has_failures` (boolean, optional) — Whether at least one item was rejected before an asset was created. When `true`, inspect the `error` object of each item to identify the rejected ones. An item the platform skipped as a duplicate is not a failure.
- `items` (list of ImportItem, optional) — One entry per requested file, in request order, with its `action` value and the current status of its asset.

## Errors

### 400 Bad Request Error

The request has failed.

- `code` (string, optional) — A string representing the code associated with the error. See the [Error codes](/v1.3/api-reference/error-codes) page for details.
- `message` (string, optional) — A human-readable string describing the error, intended to be suitable for display in a user interface.

### 404 Not Found Error

The specified connection does not exist.

- `code` (string, optional) — A string representing the code associated with the error. See the [Error codes](/v1.3/api-reference/error-codes) page for details.
- `message` (string, optional) — A human-readable string describing the error, intended to be suitable for display in a user interface.
- `docs_url` (string, optional) — The URL of the relevant documentation page.

### 409 Conflict Error

The connection is not in an active state.

- `code` (string, optional) — A string representing the code associated with the error. See the [Error codes](/v1.3/api-reference/error-codes) page for details.
- `message` (string, optional) — A human-readable string describing the error, intended to be suitable for display in a user interface.
- `docs_url` (string, optional) — The URL of the relevant documentation page.

## Types

### ConnectionsConnectionIdImportsPostRequestBodyContentApplicationJsonSchemaItemsItems

- `source_id` (string, required) — The identifier of the file at the provider. For Google Drive, this is the identifier Google Drive assigns to the file.

### ImportItem

An import item, including the `action` value and the current status of its asset. The `action` field does not change. The `status` field reflects the current status of the asset. An item rejected before an asset was created has no value in its `status` field; its `error` object describes the reason instead.

- `source_id` (string, optional) — The identifier of the file at the provider. For Google Drive, this is the identifier Google Drive assigns to the file.
- `action` (enum, optional) — The action taken for this file: created, skipped, retried, or rejected. The platform sets this value while processing the request, and the value does not change afterward. The [Import files](/v1.3/api-reference/data-connectors/imports/import-files) endpoint always returns this field. The [Retrieve an import](/v1.3/api-reference/data-connectors/imports/retrieve-an-import) endpoint omits it for imports from before this field existed. Treat an absent value as unknown rather than as a specific action. The `skipped` and `retried` values both mean the file was already imported through this account: for the `skipped` action, the platform returns the existing asset; for the `retried` action, the earlier fetch had failed, so the platform fetches the file again. See [The import object](/v1.3/api-reference/data-connectors/imports/the-import-object#item-actions) for the meaning of each value.
  - Allowed values: `created`, `skipped`, `retried`, `rejected`
- `asset_id` (string, optional) — The unique identifier of the asset for this file. When the `action` field is `created`, this identifies a new asset; when it is `skipped` or `retried`, this identifies the asset from the earlier import of the same file. Absent when the item was rejected before an asset was created.
- `status` (enum, optional) — The status of the asset. See [The import object](/v1.3/api-reference/data-connectors/imports/the-import-object#item-statuses) for the possible values. Absent when the item was rejected before an asset was created, in which case an `error` object is present.
  - Allowed values: `processing`, `ready`, `failed`
- `error` (ImportItemError, optional) — Details of the rejection. Present when the item was rejected before an asset was created, in which case the `status` field is absent.

### ImportItemError

Details of the rejection. Present when the item was rejected before an asset was created, in which case the `status` field is absent.

- `code` (string, optional) — A string representing the code associated with the error. For the possible values, see the [Error codes](/v1.3/api-reference/error-codes#the-connections-endpoints) page.
- `message` (string, optional) — A human-readable string describing the error, intended to be suitable for display in a user interface.

## Examples

**Request**

```json
{
  "items": [
    {
      "source_id": "1AbCDef_drive_file_id_x"
    }
  ]
}
```

**Response**

```json
{
  "_id": "665f0afe9b1e4d0012a3f7d0",
  "has_failures": true,
  "items": [
    {
      "source_id": "1AbCDef_drive_file_id_x",
      "action": "created",
      "asset_id": "665f0b1f9b1e4d0012a3f7e1",
      "status": "processing"
    },
    {
      "source_id": "2XyZGhi_drive_file_id_y",
      "action": "skipped",
      "asset_id": "665f0b1f9b1e4d0012a3f7e2",
      "status": "ready"
    },
    {
      "source_id": "3PqRStu_drive_file_id_z",
      "action": "retried",
      "asset_id": "665f0b1f9b1e4d0012a3f7e3",
      "status": "processing"
    },
    {
      "source_id": "4LmNOpq_drive_file_id_w",
      "action": "rejected",
      "error": {
        "code": "source_unavailable",
        "message": "The file could not be accessed."
      }
    }
  ]
}
```

**SDK Code**

```python
import requests

url = "https://api.twelvelabs.io/v1.3/connections/665f0a2c9b1e4d0012a3f7c9/imports"

payload = { "items": [{ "source_id": "1AbCDef_drive_file_id_x" }] }
headers = {
    "x-api-key": "<apiKey>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.json())
```

```javascript
const url = 'https://api.twelvelabs.io/v1.3/connections/665f0a2c9b1e4d0012a3f7c9/imports';
const options = {
  method: 'POST',
  headers: {'x-api-key': '<apiKey>', 'Content-Type': 'application/json'},
  body: '{"items":[{"source_id":"1AbCDef_drive_file_id_x"}]}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.twelvelabs.io/v1.3/connections/665f0a2c9b1e4d0012a3f7c9/imports"

	payload := strings.NewReader("{\n  \"items\": [\n    {\n      \"source_id\": \"1AbCDef_drive_file_id_x\"\n    }\n  ]\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("x-api-key", "<apiKey>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.twelvelabs.io/v1.3/connections/665f0a2c9b1e4d0012a3f7c9/imports")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["x-api-key"] = '<apiKey>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"items\": [\n    {\n      \"source_id\": \"1AbCDef_drive_file_id_x\"\n    }\n  ]\n}"

response = http.request(request)
puts response.read_body
```

```java
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.post("https://api.twelvelabs.io/v1.3/connections/665f0a2c9b1e4d0012a3f7c9/imports")
  .header("x-api-key", "<apiKey>")
  .header("Content-Type", "application/json")
  .body("{\n  \"items\": [\n    {\n      \"source_id\": \"1AbCDef_drive_file_id_x\"\n    }\n  ]\n}")
  .asString();
```

```php
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api.twelvelabs.io/v1.3/connections/665f0a2c9b1e4d0012a3f7c9/imports', [
  'body' => '{
  "items": [
    {
      "source_id": "1AbCDef_drive_file_id_x"
    }
  ]
}',
  'headers' => [
    'Content-Type' => 'application/json',
    'x-api-key' => '<apiKey>',
  ],
]);

echo $response->getBody();
```

```csharp
using RestSharp;

var client = new RestClient("https://api.twelvelabs.io/v1.3/connections/665f0a2c9b1e4d0012a3f7c9/imports");
var request = new RestRequest(Method.POST);
request.AddHeader("x-api-key", "<apiKey>");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"items\": [\n    {\n      \"source_id\": \"1AbCDef_drive_file_id_x\"\n    }\n  ]\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = [
  "x-api-key": "<apiKey>",
  "Content-Type": "application/json"
]
let parameters = ["items": [["source_id": "1AbCDef_drive_file_id_x"]]] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://api.twelvelabs.io/v1.3/connections/665f0a2c9b1e4d0012a3f7c9/imports")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```