From 0ea2ad99bd91827056c42301628bb71617c929ed Mon Sep 17 00:00:00 2001 From: Junior Dev Agent <288084488+junior-ai-bot[bot]@users.noreply.github.com> Date: Mon, 14 Sep 2026 12:54:29 +0000 Subject: [PATCH] docs(STRINGS-3195): Document account-wide translation search endpoint Move POST /accounts/{account_id}/search into the Translations section next to Search translations, correct its request params to match what the controller actually forwards (query string params, not a JSON body), and fix the response to be an array of search results. Co-Authored-By: Claude Sonnet 5 --- doc/compiled.json | 487 +++++++++++++++-------------- main.yaml | 1 - paths.yaml | 6 +- paths/search/in_account.yaml | 83 +++-- schemas/account_search_result.yaml | 5 +- 5 files changed, 289 insertions(+), 293 deletions(-) diff --git a/doc/compiled.json b/doc/compiled.json index 3dce7dc36..2e9a7c707 100644 --- a/doc/compiled.json +++ b/doc/compiled.json @@ -182,9 +182,6 @@ { "name": "Reports" }, - { - "name": "Search" - }, { "name": "Screenshot Markers" }, @@ -28542,6 +28539,250 @@ "x-cli-version": "2.5" } }, + "/accounts/{account_id}/search": { + "post": { + "summary": "Search translations and keys across projects", + "description": "Search for translation keys and translations across every project the user can access in the account. Optionally narrow the search to a subset of projects using `project_ids`.\n\n*Note: Search is limited to 10000 results and may not include recently updated data depending on the project sizes.*\n", + "operationId": "search/in_account", + "tags": [ + "Translations" + ], + "parameters": [ + { + "$ref": "#/components/parameters/X-PhraseApp-OTP" + }, + { + "$ref": "#/components/parameters/account_id" + }, + { + "description": "Search query, matched against both translation content and key names.", + "example": "keyword", + "name": "query", + "in": "query", + "required": false, + "schema": { + "type": "string" + } + }, + { + "description": "Restrict results to translations in this locale.", + "example": "de_DE", + "name": "locale_code", + "in": "query", + "required": false, + "schema": { + "type": "string" + } + }, + { + "description": "Restrict the search to the given project codes. When omitted, the search spans every project the user can access in this account.\n", + "name": "project_ids", + "in": "query", + "required": false, + "schema": { + "type": "array", + "items": { + "type": "string" + }, + "example": [ + "abcd1234abcd1234abcd1234abcd1234" + ] + } + }, + { + "$ref": "#/components/parameters/page" + }, + { + "$ref": "#/components/parameters/per_page" + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "array", + "items": { + "type": "object", + "title": "account_search_result", + "properties": { + "query": { + "type": "string" + }, + "excerpt": { + "type": "string" + }, + "key": { + "$ref": "#/components/schemas/key_preview" + }, + "locale": { + "$ref": "#/components/schemas/locale_preview" + }, + "project": { + "$ref": "#/components/schemas/project" + }, + "translation": { + "$ref": "#/components/schemas/translation" + }, + "other_translations": { + "type": "array", + "items": { + "$ref": "#/components/schemas/translation" + } + } + }, + "example": { + "query": "keyword", + "excerpt": "excerpt text", + "key": { + "id": "abcd1234cdef1234abcd1234cdef1234", + "name": "key.name", + "plural": false, + "use_ordinal_rules": false, + "data_type": "string", + "tags": [ + "tag 1", + "tag 2" + ] + }, + "locale": { + "id": "abcd1234cdef1234abcd1234cdef1234", + "name": "German", + "code": "de_DE" + }, + "project": { + "id": "abcd1234cdef1234abcd1234cdef1234", + "name": "project name", + "slug": "project-slug", + "main_format": "", + "project_image_url": "", + "created_at": "2021-05-04T14:16:26Z", + "updated_at": "2021-06-14T14:26:09Z", + "account": { + "id": "abcd1234cdef1234abcd1234cdef1234", + "name": "account name", + "slug": "account-slug", + "company": "company name", + "created_at": "2021-04-27T14:27:25Z", + "updated_at": "2021-06-14T14:35:15Z", + "company_logo_url": "" + }, + "space": { + "id": "abcd1234cdef1234abcd1234cdef1234", + "name": "space name", + "slug": "space-slug", + "created_at": "2015-01-28T09:52:53Z", + "updated_at": "2015-01-28T09:52:53Z", + "projects_count": 1 + } + }, + "translation": { + "id": "abcd1234cdef1234abcd1234cdef1234", + "content": "some content", + "unverified": true, + "excluded": false, + "plural_suffix": "", + "key": { + "id": "abcd1234cdef1234abcd1234cdef1234", + "name": "key.name", + "plural": false, + "use_ordinal_rules": false, + "data_type": "string", + "tags": [ + "tag 1", + "tag 2" + ] + }, + "created_at": "2021-05-04T14:17:04Z", + "updated_at": "2021-05-04T14:17:04Z", + "placeholders": [], + "state": "translated", + "locale": { + "id": "abcd1234cdef1234abcd1234cdef1234", + "name": "German", + "code": "de_DE" + } + }, + "other_translations": [ + { + "id": "abcd1234cdef1234abcd1234cdef1234", + "content": "some content", + "unverified": true, + "excluded": false, + "plural_suffix": "", + "key": { + "id": "abcd1234cdef1234abcd1234cdef1234", + "name": "key.name", + "plural": false, + "use_ordinal_rules": false, + "data_type": "string", + "tags": [ + "tag 1", + "tag 2" + ] + }, + "created_at": "2021-05-04T14:17:04Z", + "updated_at": "2021-05-04T14:17:04Z", + "placeholders": [], + "state": "translated", + "locale": { + "id": "abcd1234cdef1234abcd1234cdef1234", + "name": "English", + "code": "en_EN" + } + } + ] + } + } + } + } + }, + "headers": { + "X-Rate-Limit-Limit": { + "$ref": "#/components/headers/X-Rate-Limit-Limit" + }, + "X-Rate-Limit-Remaining": { + "$ref": "#/components/headers/X-Rate-Limit-Remaining" + }, + "X-Rate-Limit-Reset": { + "$ref": "#/components/headers/X-Rate-Limit-Reset" + }, + "Pagination": { + "$ref": "#/components/headers/Pagination" + } + } + }, + "400": { + "$ref": "#/components/responses/400" + }, + "401": { + "$ref": "#/components/responses/401" + }, + "403": { + "$ref": "#/components/responses/403", + "description": "Forbidden. Returned when the access token lacks the `read` scope or when the requesting user does not belong to this account." + }, + "404": { + "$ref": "#/components/responses/404" + }, + "429": { + "$ref": "#/components/responses/429" + } + }, + "x-code-samples": [ + { + "lang": "Curl", + "source": "curl \"https://api.phrase.com/v2/accounts/:account_id/search?query=keyword&locale_code=de_DE&page=1&per_page=25\" \\\n -u USERNAME_OR_ACCESS_TOKEN \\\n -X POST" + }, + { + "lang": "CLI v2", + "source": "phrase search in_account \\\n--account_id \\\n--data '{\"query\":\"keyword\",\"locale_code\": \"de_DE\",\"page\": 1,\"per_page\": 25}' \\\n--access_token " + } + ], + "x-cli-version": "2.5" + } + }, "/projects/{project_id}/translations/{id}": { "get": { "summary": "Get a single translation", @@ -30341,246 +30582,6 @@ "x-cli-version": "2.5" } }, - "/accounts/{account_id}/search": { - "post": { - "summary": "Search across projects", - "description": "Search for keys and translations in all account projects\n\n*Note: Search is limited to 10000 results and may not include recently updated data depending on the project sizes.*\n", - "operationId": "search/in_account", - "tags": [ - "Search" - ], - "parameters": [ - { - "$ref": "#/components/parameters/X-PhraseApp-OTP" - }, - { - "$ref": "#/components/parameters/account_id" - } - ], - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "type": "object", - "title": "account_search_result", - "properties": { - "query": { - "type": "string" - }, - "excerpt": { - "type": "string" - }, - "key": { - "$ref": "#/components/schemas/key_preview" - }, - "locale": { - "$ref": "#/components/schemas/locale_preview" - }, - "project": { - "$ref": "#/components/schemas/project" - }, - "translation": { - "$ref": "#/components/schemas/translation" - }, - "other_translations": { - "type": "array", - "items": { - "$ref": "#/components/schemas/translation" - } - } - }, - "example": { - "query": "keyword", - "excerpt": "excerpt text", - "key": { - "id": "abcd1234cdef1234abcd1234cdef1234", - "name": "key.name", - "plural": false, - "data_type": "string", - "tags": [ - "tag 1", - "tag 2" - ] - }, - "locale": { - "id": "abcd1234cdef1234abcd1234cdef1234", - "name": "German", - "code": "de_DE" - }, - "project": { - "id": "abcd1234cdef1234abcd1234cdef1234", - "name": "project name", - "slug": "project-slug", - "main_format": "", - "project_image_url": "", - "created_at": "2021-05-04T14:16:26Z", - "updated_at": "2021-06-14T14:26:09Z", - "account": { - "id": "abcd1234cdef1234abcd1234cdef1234", - "name": "account name", - "slug": "account-slug", - "company": "company name", - "created_at": "2021-04-27T14:27:25Z", - "updated_at": "2021-06-14T14:35:15Z", - "company_logo_url": "" - }, - "space": { - "id": "abcd1234cdef1234abcd1234cdef1234", - "name": "space name", - "slug": "space-slug", - "created_at": "2015-01-28T09:52:53Z", - "updated_at": "2015-01-28T09:52:53Z", - "projects_count": 1 - } - }, - "translation": { - "id": "abcd1234cdef1234abcd1234cdef1234", - "content": "some content", - "unverified": true, - "excluded": false, - "plural_suffix": "", - "key": { - "id": "abcd1234cdef1234abcd1234cdef1234", - "name": "key.name", - "plural": false, - "data_type": "string", - "tags": [ - "tag 1", - "tag 2" - ] - }, - "created_at": "2021-05-04T14:17:04Z", - "updated_at": "2021-05-04T14:17:04Z", - "placeholders": [], - "state": "translated", - "locale": { - "id": "abcd1234cdef1234abcd1234cdef1234", - "name": "German", - "code": "de_DE" - } - }, - "other_translations": [ - { - "id": "abcd1234cdef1234abcd1234cdef1234", - "content": "some content", - "unverified": true, - "excluded": false, - "plural_suffix": "", - "key": { - "id": "abcd1234cdef1234abcd1234cdef1234", - "name": "key.name", - "plural": false, - "data_type": "string", - "tags": [ - "tag 1", - "tag 2" - ] - }, - "created_at": "2021-05-04T14:17:04Z", - "updated_at": "2021-05-04T14:17:04Z", - "placeholders": [], - "state\"": "translated", - "locale": { - "id": "abcd1234cdef1234abcd1234cdef1234", - "name": "English", - "code": "en_EN" - } - } - ] - } - } - } - }, - "headers": { - "X-Rate-Limit-Limit": { - "$ref": "#/components/headers/X-Rate-Limit-Limit" - }, - "X-Rate-Limit-Remaining": { - "$ref": "#/components/headers/X-Rate-Limit-Remaining" - }, - "X-Rate-Limit-Reset": { - "$ref": "#/components/headers/X-Rate-Limit-Reset" - }, - "Pagination": { - "$ref": "#/components/headers/Pagination" - } - } - }, - "400": { - "$ref": "#/components/responses/400" - }, - "401": { - "$ref": "#/components/responses/401" - }, - "403": { - "$ref": "#/components/responses/403", - "description": "Forbidden. Returned when the access token lacks the `read` scope or when the requesting user is not allowed to read the account's translation keys." - }, - "404": { - "$ref": "#/components/responses/404" - }, - "429": { - "$ref": "#/components/responses/429" - } - }, - "x-code-samples": [ - { - "lang": "Curl", - "source": "curl \"https://api.phrase.com/v2/accounts/:account_id/search\" \\\n -u USERNAME_OR_ACCESS_TOKEN \\\n -X POST \\\n -F query=keyword \\\n -F locale_code=localecode \\\n -F page=1 \\\n -F per_page=25 \\" - }, - { - "lang": "CLI v2", - "source": "phrase search in_account \\\n--account_id \\\n--data '{\"q\":\"keyword\",\"locale_code\": \"de\",\"page\": 1,\"per_page\": 25}' \\\n--access_token " - } - ], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "type": "object", - "title": "search/in_account/parameters", - "properties": { - "query": { - "description": "Search query", - "type": "string", - "example": "keyword" - }, - "locale_code": { - "description": "Locale code", - "type": "string", - "example": "de_DE" - }, - "page": { - "description": "Page", - "type": "integer", - "example": 1 - }, - "per_page": { - "description": "Number of results per page", - "type": "integer", - "example": 25 - }, - "project_ids": { - "description": "Limit the search to the given project codes. When omitted, the search spans every project the user can access in this account.\n", - "type": "array", - "items": { - "type": "string" - }, - "example": [ - "abcd1234abcd1234abcd1234abcd1234" - ] - } - } - } - } - } - }, - "x-cli-version": "2.5" - } - }, "/projects/{project_id}/jobs/{job_id}/comments/{id}": { "get": { "summary": "Get a single job comment", diff --git a/main.yaml b/main.yaml index 4d14c27b0..56f579f9f 100644 --- a/main.yaml +++ b/main.yaml @@ -242,7 +242,6 @@ tags: You can import translations from your repository to Phrase and export translations from Phrase to your repository. - name: Repo Sync Events - name: Reports - - name: Search - name: Screenshot Markers - name: Screenshots - name: Spaces diff --git a/paths.yaml b/paths.yaml index e480dfa3a..ee9c4e4bd 100644 --- a/paths.yaml +++ b/paths.yaml @@ -621,6 +621,9 @@ "/projects/{project_id}/translations/search": post: "$ref": "./paths/translations/search.yaml" +"/accounts/{account_id}/search": + post: + "$ref": "./paths/search/in_account.yaml" "/projects/{project_id}/translations/{id}": get: "$ref": "./paths/translations/show.yaml" @@ -680,9 +683,6 @@ "/notification_groups/{id}/mark_as_read": patch: "$ref": "./paths/notification_groups/mark_as_read.yaml" -"/accounts/{account_id}/search": - post: - "$ref": "./paths/search/in_account.yaml" "/projects/{project_id}/jobs/{job_id}/comments/{id}": get: "$ref": "./paths/job_comments/show.yaml" diff --git a/paths/search/in_account.yaml b/paths/search/in_account.yaml index 590115423..23b273f49 100644 --- a/paths/search/in_account.yaml +++ b/paths/search/in_account.yaml @@ -1,22 +1,51 @@ --- -summary: Search across projects +summary: Search translations and keys across projects description: | - Search for keys and translations in all account projects - + Search for translation keys and translations across every project the user can access in the account. Optionally narrow the search to a subset of projects using `project_ids`. + *Note: Search is limited to 10000 results and may not include recently updated data depending on the project sizes.* operationId: search/in_account tags: -- Search +- Translations parameters: - "$ref": "../../parameters.yaml#/X-PhraseApp-OTP" - "$ref": "../../parameters.yaml#/account_id" +- description: Search query, matched against both translation content and key names. + example: keyword + name: query + in: query + required: false + schema: + type: string +- description: Restrict results to translations in this locale. + example: de_DE + name: locale_code + in: query + required: false + schema: + type: string +- description: | + Restrict the search to the given project codes. When omitted, the search spans every project the user can access in this account. + name: project_ids + in: query + required: false + schema: + type: array + items: + type: string + example: + - abcd1234abcd1234abcd1234abcd1234 +- "$ref": "../../parameters.yaml#/page" +- "$ref": "../../parameters.yaml#/per_page" responses: '200': description: OK content: application/json: schema: - "$ref": "../../schemas/account_search_result.yaml#/account_search_result" + type: array + items: + "$ref": "../../schemas/account_search_result.yaml#/account_search_result" headers: X-Rate-Limit-Limit: "$ref": "../../headers.yaml#/X-Rate-Limit-Limit" @@ -34,55 +63,19 @@ responses: "$ref": "../../responses.yaml#/401" '403': "$ref": "../../responses.yaml#/403" - description: Forbidden. Returned when the access token lacks the `read` scope or when the requesting user is not allowed to read the account's translation keys. + description: Forbidden. Returned when the access token lacks the `read` scope or when the requesting user does not belong to this account. '429': "$ref": "../../responses.yaml#/429" x-code-samples: - lang: Curl source: |- - curl "https://api.phrase.com/v2/accounts/:account_id/search" \ + curl "https://api.phrase.com/v2/accounts/:account_id/search?query=keyword&locale_code=de_DE&page=1&per_page=25" \ -u USERNAME_OR_ACCESS_TOKEN \ - -X POST \ - -F query=keyword \ - -F locale_code=localecode \ - -F page=1 \ - -F per_page=25 \ + -X POST - lang: CLI v2 source: |- phrase search in_account \ --account_id \ - --data '{"q":"keyword","locale_code": "de","page": 1,"per_page": 25}' \ + --data '{"query":"keyword","locale_code": "de_DE","page": 1,"per_page": 25}' \ --access_token -requestBody: - required: true - content: - application/json: - schema: - type: object - title: search/in_account/parameters - properties: - query: - description: Search query - type: string - example: keyword - locale_code: - description: Locale code - type: string - example: de_DE - page: - description: Page - type: integer - example: 1 - per_page: - description: Number of results per page - type: integer - example: 25 - project_ids: - description: | - Limit the search to the given project codes. When omitted, the search spans every project the user can access in this account. - type: array - items: - type: string - example: - - abcd1234abcd1234abcd1234abcd1234 x-cli-version: '2.5' diff --git a/schemas/account_search_result.yaml b/schemas/account_search_result.yaml index a66f68d50..464723b61 100644 --- a/schemas/account_search_result.yaml +++ b/schemas/account_search_result.yaml @@ -26,6 +26,7 @@ account_search_result: id: abcd1234cdef1234abcd1234cdef1234 name: key.name plural: false + use_ordinal_rules: false data_type: string tags: - "tag 1" @@ -67,6 +68,7 @@ account_search_result: id: abcd1234cdef1234abcd1234cdef1234 name: key.name plural: false + use_ordinal_rules: false data_type: string tags: - "tag 1" @@ -89,6 +91,7 @@ account_search_result: id: abcd1234cdef1234abcd1234cdef1234 name: key.name plural: false + use_ordinal_rules: false data_type: string tags: - "tag 1" @@ -96,7 +99,7 @@ account_search_result: created_at: "2021-05-04T14:17:04Z" updated_at: "2021-05-04T14:17:04Z" placeholders: [] - state": translated + state: translated locale: id: abcd1234cdef1234abcd1234cdef1234 name: English