Skip to main content

Update vault

Update a vault's name or metadata. Updates use POST and replace metadata as a whole.

Endpoint

POST /vaults/{vault_id} Paths are relative to the Base URL. Send Authorization: Bearer $DASHSCOPE_API_KEY on every request. For authentication details, see Authentication.

Path parameters

vault_id string (required)Vault ID. Treat it as an opaque ID

Request body

name string / null (optional)Vault name, when omitted, the current value is kept; null clears the name, when provided, 1–256 bytes after trimmingmetadata object (optional)Metadata, when omitted, the current value is kept; null returns 400; {} clears it. Up to 16 items; key 1–64 characters, value up to 512 charactersmetadata is replaced as a whole, not merged; old keys that are not in the new object are removed. An empty object {} does not change nullable fields. Unknown fields return 400 unknown_parameter.

Request example

curl -sS -X POST "$BASE_URL/vaults/vlt_xxx" \
  -H "Authorization: Bearer $DASHSCOPE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "production-secrets-v2",
    "metadata": {"team": "support", "stage": "prod"}
  }'

Response fields

200, returns the updated vault:id stringVault IDobject stringVault object type, fixed as vaultcreated_at integerCreation time in Unix secondsname string / nullDisplay namemetadata objectMetadata, string key-value pairs; {} when not set

Response example

{
  "id": "vlt_xxx",
  "object": "vault",
  "created_at": 1793941200,
  "name": "production-secrets-v2",
  "metadata": {"team": "support", "stage": "prod"}
}

Error codes

For the error response structure, see Errors.
HTTP statusError type / codeSolution
400invalid_request_error / unknown_parameterRemove unknown fields such as status
400invalid_request_error / invalid_typeFix the field type as described
400invalid_request_error / invalid_request_errorFix name as described and do not send metadata as null
401authentication_error / invalid_api_keySend a valid Authorization: Bearer $DASHSCOPE_API_KEY header
404not_found_error / not_found_errorThe vault does not exist, is deleted, or belongs to another workspace
409conflict_error / conflict_errorRetry later. If it keeps failing, submit a ticket with x-request-id
500server_error / server_errorRetry later. If it keeps failing, submit a ticket with x-request-id