---
title: "Create Key"
method: POST
path: "/v1/mcp/projects/{project_id}/keys"
tags: ["mcp"]
---

# Create Key

`POST /v1/mcp/projects/{project_id}/keys`

## Request

- Base URL: `https://api.sonenta.dev`
- URL: `https://api.sonenta.dev/v1/mcp/projects/{project_id}/keys`
- Auth: none declared

LLM-friendly key creation: name-based addressing, idempotent.

Claude calls this with `namespace` slug + `name`; if the key already
exists we return it untouched (created=false). When `source_value` is
provided AND the project has a source language, we ALSO upsert that
value as a source-language translation in the same call.

## Path parameters

- `project_id` string, required

## Request body

- AppRoutesMcpKeyCreateIn
  - `namespace` string, required: Namespace slug (LLM-friendly)
  - `name` string, required
  - `type` string
  - `source_value` string, nullable: Optional source-language value. When set, also upserts a translation row in the project's source language.
  - `description` string, nullable
  - `plurals` boolean
  - `max_length` integer, nullable
  - `update_source` boolean: When true, upsert the source value even if the key already exists (otherwise source_value is a no-op on existing keys). Task 750.

## Response `201`

Successful Response

- KeyCreateOut
  - `key_uuid` string, required
  - `key_name` string, required
  - `namespace_slug` string, required
  - `namespace_uuid` string, required
  - `source_value` string, nullable, required
  - `plurals` boolean, required
  - `max_length` integer, nullable, required
  - `created` boolean, required

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/sonenta/apis/sonenta-api.md) · [All operations](https://skmtc.dev/sonenta/apis/sonenta-api/llms.txt) · [OpenAPI document](https://skmtc.dev/sonenta/apis/sonenta-api/revisions/f853ea49fb05?raw)