> 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 a knowledge store

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

This method updates the specified knowledge store. Only the `name`, `description`, and `metadata` fields can be updated.


Reference: https://docs.twelvelabs.io/api-reference/knowledge-stores/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.

### Body (application/json)

This endpoint expects an object.

- `name` (string, optional) — The name of the knowledge store.
- `description` (string, optional) — An optional description of the knowledge store.
- `metadata` (map from string to KnowledgeStoreMetadataValue, optional) — Custom metadata for the knowledge store, as user-defined key-value pairs. Up to 10 pairs, keys up to 128 characters, string values up to 2048 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. The provided object replaces the existing metadata in full, so include every key you want to keep and omit the ones you want to remove. To clear all metadata, set this field to an empty object (`{}`).

## Response

### 200

The knowledge store has been successfully updated.

- `_id` (string, optional) — The unique identifier of the knowledge store.
- `name` (string, optional) — The name of the knowledge store.
- `description` (string, optional) — An optional description of the knowledge store.
- `ingestion_config` (IngestionConfig, optional) — The ingestion configuration set when this knowledge store was created. Immutable.
- `item_count` (integer, optional) — The number of items in the knowledge store.
- `created_at` (string, optional) — The date and time when the knowledge store was created, in the RFC 3339 format.
- `updated_at` (string, optional) — The date and time when the knowledge store was last updated, in the RFC 3339 format.
- `metadata` (map from string to KnowledgeStoreMetadataValue, optional) — Custom metadata for the knowledge store. Keys are strings; each value is a string, a number, a boolean, or an array of strings.

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

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

### IngestionConfig

Configuration that controls how content added to the knowledge store is processed.

- `enrichment_config` (EnrichmentConfig, required) — Metadata enrichment configuration. The `type` field selects one variant: - `type: json_schema` - Structured extraction conforming to a provided JSON Schema. - `type: description` - Natural-language instructions that the platform converts into a schema internally.

### EnrichmentConfig

Metadata enrichment configuration. The `type` field selects one variant: - `type: json_schema` - Structured extraction conforming to a provided JSON Schema. - `type: description` - Natural-language instructions that the platform converts into a schema internally.

- `type`: `json_schema` (json_schema)
  - `json_schema` (EnrichmentConfigJsonSchemaJsonSchema, required) — A JSON Schema (draft 2020-12) that defines the structure of metadata to extract from each video shot. The platform accepts only the JSON Schema keywords listed below; unknown keywords return a `422` error. Keep schemas focused — deeply nested or overly complex schemas may degrade extraction quality. **Supported keywords** | Category | Keywords | |---|---| | Core | `type`, `title`, `description`, `enum` | | Object | `properties`, `required`, `additionalProperties` | | Array | `items`, `prefixItems`, `minItems`, `maxItems` | | Number | `minimum`, `maximum` | | String | `format` | Notes: - The root `type` keyword must be `"object"`. - Every entry under the `properties` keyword (including nested ones) must include a `description` field. This text guides extraction quality. - The `required` keyword behaves as in standard JSON Schema. - The `additionalProperties` keyword accepts a boolean value (`true` or `false`). Use `false` to enforce strict shapes. The platform does not support schema-valued forms. - **Unknown keywords return `422` — they are not silently ignored.** If you generate schemas programmatically (for example, using `pydantic.model_json_schema()`), strip annotative keywords such as `default`, `examples`, and `readOnly` before submitting. - **The platform does not support nullable fields.** This includes both `nullable: true` and `type: ["string", "null"]`. To express an optional field, omit it from the `required` array — the platform omits the field from the result when no value is present. **Not supported (returns `422`)** - Schema composition: `anyOf`, `allOf`, `oneOf`, `not` - Conditional schemas: `if` / `then` / `else` - Property dependencies: `dependentSchemas`, `dependentRequired` - Object size constraints: `minProperties`, `maxProperties` - String constraints: `pattern`, `minLength`, `maxLength` - Number constraints: `exclusiveMinimum`, `exclusiveMaximum`, `multipleOf` - Value constraints: `const` - Null handling: `nullable`, `type` arrays (e.g., `["string", "null"]`) - Annotative keywords: `default`, `examples`, `readOnly`, `writeOnly` - References and reuse: `$ref`, `$defs`, `definitions` - Any other keyword not listed under "Supported keywords" above
- `type`: `description` (description)
  - `description` (string, required) — A natural-language description of what knowledge should be extracted from the videos. The platform converts this into a JSON Schema internally.

### EnrichmentConfigJsonSchemaJsonSchema

A JSON Schema (draft 2020-12) that defines the structure of metadata to extract from each video shot. The platform accepts only the JSON Schema keywords listed below; unknown keywords return a `422` error. Keep schemas focused — deeply nested or overly complex schemas may degrade extraction quality. **Supported keywords** | Category | Keywords | |---|---| | Core | `type`, `title`, `description`, `enum` | | Object | `properties`, `required`, `additionalProperties` | | Array | `items`, `prefixItems`, `minItems`, `maxItems` | | Number | `minimum`, `maximum` | | String | `format` | Notes: - The root `type` keyword must be `"object"`. - Every entry under the `properties` keyword (including nested ones) must include a `description` field. This text guides extraction quality. - The `required` keyword behaves as in standard JSON Schema. - The `additionalProperties` keyword accepts a boolean value (`true` or `false`). Use `false` to enforce strict shapes. The platform does not support schema-valued forms. - **Unknown keywords return `422` — they are not silently ignored.** If you generate schemas programmatically (for example, using `pydantic.model_json_schema()`), strip annotative keywords such as `default`, `examples`, and `readOnly` before submitting. - **The platform does not support nullable fields.** This includes both `nullable: true` and `type: ["string", "null"]`. To express an optional field, omit it from the `required` array — the platform omits the field from the result when no value is present. **Not supported (returns `422`)** - Schema composition: `anyOf`, `allOf`, `oneOf`, `not` - Conditional schemas: `if` / `then` / `else` - Property dependencies: `dependentSchemas`, `dependentRequired` - Object size constraints: `minProperties`, `maxProperties` - String constraints: `pattern`, `minLength`, `maxLength` - Number constraints: `exclusiveMinimum`, `exclusiveMaximum`, `multipleOf` - Value constraints: `const` - Null handling: `nullable`, `type` arrays (e.g., `["string", "null"]`) - Annotative keywords: `default`, `examples`, `readOnly`, `writeOnly` - References and reuse: `$ref`, `$defs`, `definitions` - Any other keyword not listed under "Supported keywords" above

- `type` (enum, required) — The top-level type of the schema. Must be `"object"`. Primitive and array top-level types are not supported. The platform uses this object structure to map extracted metadata to named fields.
  - Allowed values: `object`
- `properties` (map from string to any, required) — A map of property names to their JSON Schema definitions. Each property must include a field named `description`. The platform uses this field to guide extraction quality. Omitting it returns a `422` error.

## Examples

**Request**

```json
{}
```

**Response**

```json
{
  "_id": "ks_069e9869-1ea3-7481-8000-dae72bf6be6e",
  "name": "Product Demo Analysis",
  "description": "Knowledge store for product demo videos",
  "ingestion_config": {
    "enrichment_config": {
      "type": "json_schema",
      "json_schema": {
        "type": "object",
        "properties": {
          "topic": {
            "type": "string",
            "description": "The main topic discussed in this shot"
          },
          "sentiment": {
            "type": "string",
            "enum": [
              "positive",
              "negative",
              "neutral"
            ],
            "description": "The overall sentiment of the shot"
          }
        },
        "required": [
          "topic"
        ]
      }
    }
  },
  "item_count": 5,
  "created_at": "2024-01-15T09:30:00Z",
  "updated_at": "2024-01-15T09:30:00Z",
  "metadata": {}
}
```

**SDK Code**

```python
import requests

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

payload = {}
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';
const options = {
  method: 'PATCH',
  headers: {'x-api-key': '<apiKey>', 'Content-Type': 'application/json'},
  body: '{}'
};

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"

	payload := strings.NewReader("{}")

	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")

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 = "{}"

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")
  .header("x-api-key", "<apiKey>")
  .header("Content-Type", "application/json")
  .body("{}")
  .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', [
  'body' => '{}',
  '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");
var request = new RestRequest(Method.PATCH);
request.AddHeader("x-api-key", "<apiKey>");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = [
  "x-api-key": "<apiKey>",
  "Content-Type": "application/json"
]
let parameters = [] 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")! 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()
```