# Create a secret set (/en/api-reference/api-ref/conversational-ai/platform/create-secret-set)

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


Creates a named set of secrets in your project.

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

## Servers

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

Use secret sets to keep provider API keys out of your agent configurations. To use a secret, pass `$secrets.<set_name>.<key>` in an agent's `credential.fields`, for example in `credential.fields.api_key`. Agora resolves references when each session starts.

If a set with the same name exists, the request fails with `SecretSetAlreadyExists`. To change values, [update the set](/en/api-reference/api-ref/conversational-ai/platform/update-secret-set) or [set a key](/en/api-reference/api-ref/conversational-ai/platform/set-secret-key).


## Authorization

This endpoint requires authentication.

- `tokenAuth`
- `basicAuth`

## Parameters

- `appid` (path, required, string) - The App ID of your project.

## Request body

- `name` (string, required) - A name for the secret set, unique in the project. Use 1 to 64 characters from `A-Z`, `a-z`, `0-9`, and `_`. Names are case-sensitive.
  - Min length: `1`
  - Max length: `64`
- `secrets` (object, required) - The secrets, as key-value pairs. Each key is 1 to 64 characters from `A-Z`, `a-z`, `0-9`, and `_`, and must be unique within the set. Values are write-only and are never returned. A set can hold at most 64 KiB, measured as the UTF-8 size of its keys and values encoded as a JSON object. A larger set is rejected with `400`.

### Request body example

```json
{
  "name": "support_prod",
  "secrets": {
    "asr": "<your_asr_api_key>",
    "llm": "<your_llm_api_key>",
    "tts": "<your_tts_api_key>"
  }
}
```

## Responses

### 201

The secret set was created. The response body lists its keys.

- `name` (string, required) - The name of the secret set.
- `keys` (array, required) - The names of the keys in the set. Values are never returned.
  - `keys.items` (string)
- `create_ts` (integer, required) - The time the set was created, as a Unix timestamp in seconds.
- `update_ts` (integer, required) - The time the set was last updated, as a Unix timestamp in seconds.
### 400

The request is invalid. Check `reason` and `detail` in the response body.

- `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).
### 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).
### 409

`SecretSetAlreadyExists`: A set with this name exists.

- `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).
### 422

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

### 201

```json
{
  "name": "support_prod",
  "keys": [
    "asr",
    "llm",
    "tts"
  ],
  "create_ts": 1789898400,
  "update_ts": 1789898400
}
```