# Set a secret key (/en/api-reference/api-ref/conversational-ai/platform/set-secret-key)

> For AI agents: see the complete documentation index at [llms.txt](/llms.txt).

> Documentation: Conversational AI API.
> Documentation version: Preview.
> This document describes only this version. [Version index](/llms/doc-versions-convoai-api-v2.txt).


Adds a key to a secret set, or replaces the value of an existing key.

- OpenAPI: /openapi/conversational-ai/rest-api-platform.en.yaml
- Operation ID: set-secret-key
- Method: PUT
- Path: /v1/projects/{appid}/secrets/{name}/keys/{key}
- Endpoint: https://preview.ai.agora.io/conversational-ai/v1/projects/{appid}/secrets/{name}/keys/{key}

## Servers

- https://preview.ai.agora.io/conversational-ai

Use this endpoint to add or rotate one key without sending the set's other values. Repeating the request is safe. Agents keep referencing `$secrets.<set>.<key>` without changes, and new sessions use the new value.

The response returns `201` when the key is new and `200` when it replaces an existing value. Both headers are optional. Without them, the last write to the key wins.


## Authorization

This endpoint requires authentication.

- `tokenAuth`
- `basicAuth`

## Parameters

- `appid` (path, required, string) - The App ID of your project.
- `name` (path, required, string) - The name of the secret set.
- `key` (path, required, string) - The name of the key in the secret set. When you add a key, use 1 to 64 characters from `A-Z`, `a-z`, `0-9`, and `_`.
- `If-Match` (header, optional, string) - The key's `ETag` from your last write to it. The request fails with `412` if the key has changed since then.
- `If-None-Match` (header, optional, string) - Set to `*` to create the key only if it doesn't exist. If the key exists, the request fails with `412`, so a live value is never overwritten by accident.

## Request body

- `value` (string, required) - The secret value. It is write-only and is never returned. The whole set, including this value, can hold at most 64 KiB.
  - Format: `password`
  - Min length: `1`

### Request body example

```json
{
  "value": "<your_new_llm_api_key>"
}
```

## Responses

### 200

The key's value was replaced.

- `key` (string, required) - The name of the key.
### 201

The key was added to the set.

- `key` (string, required) - The name of the key.
### 401

Authentication is missing or invalid. The reason is `InvalidPermission`.

- `detail` (string, required) - A human-readable description of the error. It names the field or resource involved, when there is one. Don't parse it; branch on `reason` instead.
- `reason` (string, required) - A machine-readable error reason, such as `InvalidFieldValue` or `ResourceNotFound`. For all reasons, see [Status codes](/en/api-reference/api-ref/conversational-ai/platform/status-codes).
### 404

The resource in the path doesn't exist. The reason is `ResourceNotFound`.

- `detail` (string, required) - A human-readable description of the error. It names the field or resource involved, when there is one. Don't parse it; branch on `reason` instead.
- `reason` (string, required) - A machine-readable error reason, such as `InvalidFieldValue` or `ResourceNotFound`. For all reasons, see [Status codes](/en/api-reference/api-ref/conversational-ai/platform/status-codes).
### 412

The `If-Match` value doesn't match the current version of the resource. The reason is `PreconditionFailed`. Retrieve the resource, apply your change again, and retry with the new `ETag`.

- `detail` (string, required) - A human-readable description of the error. It names the field or resource involved, when there is one. Don't parse it; branch on `reason` instead.
- `reason` (string, required) - A machine-readable error reason, such as `InvalidFieldValue` or `ResourceNotFound`. For all reasons, see [Status codes](/en/api-reference/api-ref/conversational-ai/platform/status-codes).
### default

The request failed. The response body contains the `reason` and `detail` of the failure. For possible reasons, see [Status codes](/en/api-reference/api-ref/conversational-ai/platform/status-codes).

- `detail` (string, required) - A human-readable description of the error. It names the field or resource involved, when there is one. Don't parse it; branch on `reason` instead.
- `reason` (string, required) - A machine-readable error reason, such as `InvalidFieldValue` or `ResourceNotFound`. For all reasons, see [Status codes](/en/api-reference/api-ref/conversational-ai/platform/status-codes).

## Response examples

### 200

```json
{
  "key": "llm"
}
```
### 201

```json
{
  "key": "tts"
}
```