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

# Update an item tag

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

This method updates the range or the `tag_metadata` of the specified tag and returns the tag. Send at least one field. A field you omit keeps its current value. To clear the end of the range, send `end_sec` as `null`. The tag becomes a single moment. The platform merges your changes to `tag_metadata` with the existing metadata:
- A key with a value creates or replaces that key.
- A key set to `null` deletes that key.
- A key set to an empty string (`""`) or an empty array (`[]`) is ignored.
- A key you omit from the request keeps its current value.

The tag must keep at least one key in `tag_metadata`, and it holds up to 50 pairs. If the merged result breaks either limit, the request fails.


Reference: https://docs.twelvelabs.io/api-reference/knowledge-store-items/item-tags/update

## 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.
- `item_id` (string, required) — The unique identifier of the knowledge store item.
- `tag_id` (string, required) — The unique identifier of the item tag.

### Body (application/json)

This endpoint expects an UpdateKnowledgeStoreItemTagRequest.

- `start_sec` (double, optional) — The new start of the tag, in seconds from the start of the video. It must be less than the duration of the video. The tag must still end after it starts.
- `end_sec` (double, optional, nullable) — The new end of the range, in seconds from the start of the video. It must be greater than `start_sec`. It must not exceed the duration of the video. Send `null` to clear the end, which turns a range into a single moment. Omit the field to keep the current end.
- `tag_metadata` (map from string to KnowledgeStoreMetadataValue, optional) — The keys to change. Send at least one key. Keys are strings of up to 128 characters. String values can have up to 8192 characters. Values can be a string, a number, a boolean, an array of strings, or `null` to delete the key. A key you omit keeps its current value. A nested object and an array containing anything other than strings are rejected. The tag holds up to 50 pairs after the merge. 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.

## Response

### 200

The item tag has been successfully updated.

- `_id` (string, required) — The unique identifier of the item tag.
- `knowledge_store_id` (string, required) — The unique identifier of the knowledge store.
- `item_id` (string, required) — The unique identifier of the knowledge store item that holds the tag.
- `start_sec` (double, required) — The start of the tag, in seconds from the start of the video.
- `end_sec` (double, required, nullable) — The end of the range, in seconds from the start of the video. The value is `null` for a tag on a single moment.
- `tag_metadata` (map from string to KnowledgeStoreMetadataValue, required) — The custom metadata of the tag. Keys are strings. Each value is a string, a number, a boolean, or an array of strings.
- `created_at` (string, required) — The date and time when the tag was created, in the RFC 3339 format.
- `updated_at` (string, required) — The date and time when the tag 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.

### 404 Not Found Error

The specified resource does not exist.

- `code` (string, optional) — Represents 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.

### 422 Unprocessable Entity Error

The request has failed. For example, the tag would hold no `tag_metadata` keys, the tag would hold more than 50 keys, the range does not end after it starts, or the range exceeds the duration of the video.

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

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

## Examples

**Request**

```json
{
  "end_sec": 18.25,
  "tag_metadata": {
    "replay": null
  }
}
```

**Response**

```json
{
  "_id": "ksit_069e9870-3c4d-7abc-9012-3456789abcde",
  "knowledge_store_id": "ks_069e9869-1ea3-7481-8000-dae72bf6be6e",
  "item_id": "ksi_069e9870-3c4d-7abc-9012-3456789abcde",
  "start_sec": 12.5,
  "end_sec": 18.25,
  "tag_metadata": {
    "event": "goal",
    "team": "home"
  },
  "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/ksi_069e9870-3c4d-7abc-9012-3456789abcde/tags/ksit_069e9870-3c4d-7abc-9012-3456789abcde"

payload = {
    "end_sec": 18.25,
    "tag_metadata": { "replay": None }
}
headers = {
    "x-api-key": "<apiKey>",
    "Content-Type": "application/json"
}

response = requests.patch(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/ksi_069e9870-3c4d-7abc-9012-3456789abcde/tags/ksit_069e9870-3c4d-7abc-9012-3456789abcde';
const options = {
  method: 'PATCH',
  headers: {'x-api-key': '<apiKey>', 'Content-Type': 'application/json'},
  body: '{"end_sec":18.25,"tag_metadata":{"replay":null}}'
};

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/ksi_069e9870-3c4d-7abc-9012-3456789abcde/tags/ksit_069e9870-3c4d-7abc-9012-3456789abcde"

	payload := strings.NewReader("{\n  \"end_sec\": 18.25,\n  \"tag_metadata\": {\n    \"replay\": null\n  }\n}")

	req, _ := http.NewRequest("PATCH", 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/ksi_069e9870-3c4d-7abc-9012-3456789abcde/tags/ksit_069e9870-3c4d-7abc-9012-3456789abcde")

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

request = Net::HTTP::Patch.new(url)
request["x-api-key"] = '<apiKey>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"end_sec\": 18.25,\n  \"tag_metadata\": {\n    \"replay\": null\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.patch("https://api.twelvelabs.io/v1.3/knowledge-stores/ks_069e9869-1ea3-7481-8000-dae72bf6be6e/items/ksi_069e9870-3c4d-7abc-9012-3456789abcde/tags/ksit_069e9870-3c4d-7abc-9012-3456789abcde")
  .header("x-api-key", "<apiKey>")
  .header("Content-Type", "application/json")
  .body("{\n  \"end_sec\": 18.25,\n  \"tag_metadata\": {\n    \"replay\": null\n  }\n}")
  .asString();
```

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

$client = new \GuzzleHttp\Client();

$response = $client->request('PATCH', 'https://api.twelvelabs.io/v1.3/knowledge-stores/ks_069e9869-1ea3-7481-8000-dae72bf6be6e/items/ksi_069e9870-3c4d-7abc-9012-3456789abcde/tags/ksit_069e9870-3c4d-7abc-9012-3456789abcde', [
  'body' => '{
  "end_sec": 18.25,
  "tag_metadata": {
    "replay": null
  }
}',
  '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/ksi_069e9870-3c4d-7abc-9012-3456789abcde/tags/ksit_069e9870-3c4d-7abc-9012-3456789abcde");
var request = new RestRequest(Method.PATCH);
request.AddHeader("x-api-key", "<apiKey>");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"end_sec\": 18.25,\n  \"tag_metadata\": {\n    \"replay\": null\n  }\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = [
  "x-api-key": "<apiKey>",
  "Content-Type": "application/json"
]
let parameters = [
  "end_sec": 18.25,
  "tag_metadata": ["replay": ]
] 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/ksi_069e9870-3c4d-7abc-9012-3456789abcde/tags/ksit_069e9870-3c4d-7abc-9012-3456789abcde")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "PATCH"
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()
```