---
title: "Search Keys"
method: GET
path: "/v1/mcp/projects/{project_id}/search-keys"
tags: ["mcp"]
---

# Search Keys

`GET /v1/mcp/projects/{project_id}/search-keys`

## Request

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

Find where a term lives, across a project's source + translation values, in ONE call.

Searches base translation VALUES (source language + every translation,
including ICU/CLDR plural sub-forms) and — when include_key_name=true — the
key name and description. Results are grouped BY KEY: each item carries a
`matched_in[]` of {language_code, is_source, field, value, offsets}, so the
caller sees the term is in e.g. the fr source AND the en translation without
a second query.

SCOPE LIMIT (not exhaustive): a11y surface overrides (aria_label, alt_text,
screen_reader, plain_language) are NOT included — only base values. Raw regex
is not supported in V1 (the query is matched literally); case_sensitive and
whole_word refine the match. Read-only, 0 credits.

## Path parameters

- `project_id` string, required

## Query parameters

- `query` string, required: The term to find. Literal substring (regex-escaped); NOT a regex in V1.
- `namespace` string, nullable: Restrict to one namespace slug.
- `languages` string, nullable: CSV of BCP-47 codes (e.g. 'fr,en-CA'). Default = ALL (source + every translation language).
- `case_sensitive` boolean
- `whole_word` boolean: Match on word boundaries.
- `include_key_name` boolean: Also search the key NAME and DESCRIPTION (reported with language_code=null).
- `cursor` string, nullable
- `limit` integer: Page size, in KEYS.

## Response `200`

Successful Response

- SearchKeysPage
  - `items` SearchKeysItem[], required
    - `key_uuid` string, required
    - `key_name` string, required
    - `namespace_slug` string, required
    - `namespace_uuid` string, required
    - `plurals` boolean, required
    - `matched_in` SearchKeysMatch[], required
      - `language_code` string, nullable, required
      - `is_source` boolean, nullable, required
      - `field` string, required
      - `value` string, required
      - `match_start` integer, required
      - `match_end` integer, required
  - `cursor_next` string, nullable, required
  - `total_keys` integer, required
  - `total_matches` integer, required
  - `truncated` 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)