> This page is for version v1.3 (default).
> For other versions, use one of these documentation indexes:
> - v1.3 (default): https://beta.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://beta.docs.twelvelabs.io/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://beta.docs.twelvelabs.io/_mcp/server.

# Create a knowledge store item

POST https://api.twelvelabs.io/v1.3/knowledge-stores/{knowledge_store_id}/items
Content-Type: application/json

This method adds an asset to a knowledge store for processing.
The operation is asynchronous. The item is created immediately with the `queued`
status and processed in the background.

**Asset size limits**:
- **Video**: Up to 10 GB
- **Images**: Up to 32 MB


Reference: https://beta.docs.twelvelabs.io/api-reference/knowledge-store-items/create

## Authentication

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

## Request

### Path parameters

- `knowledge_store_id` (string, required) — The unique identifier of the knowledge store.

### Body (application/json)

This endpoint expects an object.

- `asset_id` (string, required) — The unique identifier of the asset to add to the knowledge store. If you uploaded the asset before your plan moved to the new billing, enable storage accounting for it before you add it to a knowledge store. Use the [Enable storage accounting for an asset](/v1.3/api-reference/manage-assets/enable-storage-accounting) method.
- `asset_type` (enum, optional) — The type of item to create.
  - Allowed values: `video`, `image`
- `item_metadata` (map from string to KnowledgeStoreMetadataValue, optional) — Custom metadata for the item, as user-defined key-value pairs. Up to 50 pairs, keys up to 128 characters, string values up to 8192 characters. Keys are strings; values can be a string, a number, a boolean, or an array of strings. A nested object, an array containing anything other than strings, and a null value are rejected. An integer must fit in 53 bits (-9007199254740991 to 9007199254740991). Send a wider integer, or an identifier that must be preserved verbatim, as a string. To change it after you create the item, use the [`PATCH`](/v1.3/api-reference/knowledge-store-items/update-item-metadata) or [`PUT`](/v1.3/api-reference/knowledge-store-items/replace-item-metadata) method of the `/knowledge-stores/{knowledge_store_id}/items/{item_id}/item-metadata` endpoint.
- `metadata` (map from string to KnowledgeStoreMetadataValue, optional, deprecated) — Deprecated. Use `item_metadata` instead. The item stores the pairs in its `item_metadata` field and not in its `metadata` field. Send `item_metadata` or `metadata`, not both. A request that sets both returns a `400` error.

## Response

### 202

The item creation request has been accepted and is processing.

- `asset_type` (enum, required) — The type of item.
  - Allowed values: `video`, `image`
- `_id` (string, optional) — The unique identifier of the knowledge store item.
- `asset_id` (string, optional) — The unique identifier of the source asset.
- `status` (enum, optional) — The processing status of the item. For the meaning of each value, see the [Item statuses](/v1.3/api-reference/knowledge-store-items/the-knowledge-store-item-object#item-statuses) section on **The knowledge store item object** page.
  - Allowed values: `queued`, `pending`, `processing`, `ready`, `failed`
- `system_metadata` (KnowledgeStoreItemSystemMetadata, optional) — System-generated metadata for the source asset. Its `asset_type` field always matches the item's top-level `asset_type` field.
- `metadata` (map from string to KnowledgeStoreMetadataValue, optional) — The custom metadata of the source asset. Keys are strings; each value is a string, a number, a boolean, or an array of strings. The platform updates it when the user-defined metadata of the asset changes. To change it, use the [`PATCH`](/v1.3/api-reference/upload-content/direct-uploads/update-user-metadata) method of the `/assets/{asset_id}/user-metadata` endpoint. To set custom metadata for the knowledge store item only, use `item_metadata`.
- `item_metadata` (map from string to KnowledgeStoreMetadataValue, optional) — The custom metadata of the knowledge store item. Keys are strings; each value is a string, a number, a boolean, or an array of strings. It is separate from the custom metadata of the source asset. A change to the custom metadata of the source asset does not change this field. The same key can have different values in the `metadata` field and in the `item_metadata` field. You set it when you create the item or change it with the [`PATCH`](/v1.3/api-reference/knowledge-store-items/update-item-metadata) or [`PUT`](/v1.3/api-reference/knowledge-store-items/replace-item-metadata) method of the `/knowledge-stores/{knowledge_store_id}/items/{item_id}/item-metadata` endpoint. This field is absent when no item metadata has been set.
- `enriched_metadata` (map from string to any, optional) — Metadata that the platform extracts from the whole item, as defined by the enrichment configuration of the knowledge store. It contains the properties that have the `granularity` keyword set to `video` for a video, or to `image` for an image. Properties that have the `granularity` keyword set to `shot` do not appear in this field. Keys are the property names; each value matches its property definition. A property with no value is omitted. The field is present only when the item is `ready` and contains at least one value.
- `created_at` (string, optional) — The date and time when the item was created, in the RFC 3339 format.
- `updated_at` (string, optional) — The date and time when the item was last updated, in the RFC 3339 format.

## 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.

### 409 Conflict Error

The platform cannot add this asset to the knowledge store because storage accounting is off for it. The error code is `asset_storage_accounting_required`. Enable storage accounting for the asset, then retry the request.

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

### 422 Unprocessable Entity Error

The request is well-formed, but the platform cannot process it. For example, the metadata has too many pairs, or a key or a string value is too long. A metadata value of an unsupported type returns a `400` error instead.

- `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.

## Types

### KnowledgeStoreMetadataValue

A single custom-metadata value: a string, a number, a boolean, or an array of strings. The value keeps the JSON type sent; a nested object, an array containing anything other than strings, and a null value are rejected. An integer must fit in 53 bits (-9007199254740991 to 9007199254740991). A wider integer, or an identifier that must be preserved verbatim, must be sent as a string.

### KnowledgeStoreItemSystemMetadata

System-generated metadata for the source asset. Its `asset_type` field always matches the item's top-level `asset_type` field.

- `asset_type`: `video` (video)
  - `codec_name` (string, optional) — The codec used to encode the video.
  - `duration` (double, optional) — The duration of the video in seconds.
  - `filename` (string, optional) — The original filename of the video.
  - `fps` (double, optional) — The frame rate of the video in frames per second.
  - `height` (integer, optional) — The height of the video in pixels.
  - `size` (long, optional) — The file size of the video in bytes.
  - `width` (integer, optional) — The width of the video in pixels.
- `asset_type`: `image` (image)
  - `codec_name` (string, optional) — The codec used to encode the image.
  - `filename` (string, optional) — The original filename of the image.
  - `height` (integer, optional) — The height of the image in pixels.
  - `size` (long, optional) — The file size of the image in bytes.
  - `width` (integer, optional) — The width of the image in pixels.

## Examples

**Request**

```json
{
  "asset_id": "6298d673f1090f1100476d4c"
}
```

**Response**

```json
{
  "asset_type": "video",
  "_id": "ksi_069e9870-3c4d-7abc-9012-3456789abcde",
  "asset_id": "6298d673f1090f1100476d4c",
  "status": "ready",
  "system_metadata": {
    "asset_type": "video",
    "codec_name": "h264",
    "duration": 531.998133,
    "filename": "01.mp4",
    "fps": 29.97,
    "height": 1080,
    "size": 65749715,
    "width": 1920
  },
  "metadata": {},
  "item_metadata": {
    "creator_handle": "@jane.doe",
    "view_count": 48210
  },
  "enriched_metadata": {
    "brand": "Acme"
  },
  "created_at": "2024-01-15T09:30:00Z",
  "updated_at": "2024-01-15T09:30:00Z"
}
```

**SDK Code**

```python
import requests

url = "https://api.twelvelabs.io/v1.3/knowledge-stores/ks_069e9869-1ea3-7481-8000-dae72bf6be6e/items"

payload = { "asset_id": "6298d673f1090f1100476d4c" }
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/knowledge-stores/ks_069e9869-1ea3-7481-8000-dae72bf6be6e/items';
const options = {
  method: 'POST',
  headers: {'x-api-key': '<apiKey>', 'Content-Type': 'application/json'},
  body: '{"asset_id":"6298d673f1090f1100476d4c"}'
};

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/knowledge-stores/ks_069e9869-1ea3-7481-8000-dae72bf6be6e/items"

	payload := strings.NewReader("{\n  \"asset_id\": \"6298d673f1090f1100476d4c\"\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/knowledge-stores/ks_069e9869-1ea3-7481-8000-dae72bf6be6e/items")

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  \"asset_id\": \"6298d673f1090f1100476d4c\"\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/knowledge-stores/ks_069e9869-1ea3-7481-8000-dae72bf6be6e/items")
  .header("x-api-key", "<apiKey>")
  .header("Content-Type", "application/json")
  .body("{\n  \"asset_id\": \"6298d673f1090f1100476d4c\"\n}")
  .asString();
```

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

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api.twelvelabs.io/v1.3/knowledge-stores/ks_069e9869-1ea3-7481-8000-dae72bf6be6e/items', [
  'body' => '{
  "asset_id": "6298d673f1090f1100476d4c"
}',
  '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/knowledge-stores/ks_069e9869-1ea3-7481-8000-dae72bf6be6e/items");
var request = new RestRequest(Method.POST);
request.AddHeader("x-api-key", "<apiKey>");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"asset_id\": \"6298d673f1090f1100476d4c\"\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = [
  "x-api-key": "<apiKey>",
  "Content-Type": "application/json"
]
let parameters = ["asset_id": "6298d673f1090f1100476d4c"] as [String : Any]

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

let request = NSMutableURLRequest(url: NSURL(string: "https://api.twelvelabs.io/v1.3/knowledge-stores/ks_069e9869-1ea3-7481-8000-dae72bf6be6e/items")! 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()
```