diff --git a/doc/compiled.json b/doc/compiled.json index afba5090..db9e4169 100644 --- a/doc/compiled.json +++ b/doc/compiled.json @@ -30941,7 +30941,7 @@ }, "post": { "summary": "Link child keys to a parent key", - "description": "Creates links between a given parent key and one or more child keys.", + "description": "Designates a translation key as a parent and links one or more child keys to it. Once linked, child keys receive a special reference marker as their translation content, signalling that their translations are derived from the parent. Use this when you want to group related keys — for example, a short label and its long-form variant — so translators see them in context together.\n\nPass an empty child_key_ids array to mark the key as a parent without linking any children yet. Both the parent key and every child key must belong to the main project; branch keys cannot participate in key links. A child key can have at most one parent at a time; attempting to link a child that already has a parent returns a 422 error with code CHILD_IS_ALREADY_LINKED. Parent and child key plurality must match — linking a plural child to a non-plural parent (or vice versa) also returns a 422.\n\nErrors:\n\n- key_links_bad_request (400): The request body is malformed or a required field is missing. Correct the request structure and retry.\n- key_links_unauthorized (401): The access token is missing or invalid. Supply a valid token.\n- key_links_forbidden (403): The access token lacks the write scope, the requesting user does not have write permission on key links, or the parent key is on a branch project. Grant the required permission or use a main-project key.\n- key_links_not_found (404): The parent key does not exist in this project. Verify the project_id and id values.\n- key_links_unprocessable (422): The link could not be created. Common causes: PARENT_IS_ALREADY_CHILD (the parent key is itself a child), PARENT_IS_SAME_AS_CHILD (a child key ID matches the parent), CHILD_IS_ALREADY_LINKED (a child key already has another parent), CHILD_IS_ON_BRANCH (a child key is on a branch), PARENT_IS_NOT_PLURAL / PARENT_IS_PLURAL (plurality mismatch between parent and child). Inspect the errors array in the response body for the specific code.\n- key_links_rate_limited (429): Too many requests. Wait until the X-Rate-Limit-Reset time before retrying.\n", "operationId": "key_links/create", "tags": [ "Linked Keys" @@ -30969,52 +30969,139 @@ "title": "key_links/create/parameters", "properties": { "child_key_ids": { - "description": "The IDs of the child keys to link to the parent key. Can be left empty, to only mark the given translation-key as parent", + "description": "Codes of the keys to link as children. Pass an empty array to mark the parent key without linking any children.", "type": "array", "example": [ - "child_key_id1", - "child_key_id2" + "ijkl9012mnop3456ijkl9012mnop3456", + "abcd1234efgh5678abcd1234efgh5678" ], "items": { "type": "string" } } } + }, + "example": { + "child_key_ids": [ + "ijkl9012mnop3456ijkl9012mnop3456", + "abcd1234efgh5678abcd1234efgh5678" + ] } } } }, "responses": { "201": { - "description": "Created", + "description": "Key link reference created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/key_link" + }, + "example": { + "created_at": "2024-03-15T10:22:00Z", + "updated_at": "2024-03-15T10:22:00Z", + "created_by": { + "id": "usr1a2b3c4d5e6f7a8b9c", + "username": "jane.doe", + "name": "Jane Doe", + "gravatar_uid": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4" + }, + "updated_by": { + "id": "usr1a2b3c4d5e6f7a8b9c", + "username": "jane.doe", + "name": "Jane Doe", + "gravatar_uid": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4" + }, + "account": { + "id": "acct9z8y7x6w5v4u3t2s", + "name": "Acme Translations", + "slug": "acme-translations", + "company": "Acme Corp", + "created_at": "2023-01-10T08:00:00Z", + "updated_at": "2023-06-01T12:00:00Z", + "company_logo_url": "https://example.com/logos/acme.png" + }, + "parent": { + "id": "ijkl9012mnop3456ijkl9012", + "name": "home.hero.title", + "plural": false, + "use_ordinal_rules": false, + "data_type": "string", + "tags": [ + "ui", + "homepage" + ] + }, + "children": [ + { + "id": "ijkl9012mnop3456ijkl9012mnop3456", + "name": "home.hero.title_short", + "plural": false, + "use_ordinal_rules": false, + "data_type": "string", + "tags": [ + "ui", + "homepage" + ] + }, + { + "id": "abcd1234efgh5678abcd1234efgh5678", + "name": "home.hero.title_long", + "plural": false, + "use_ordinal_rules": false, + "data_type": "string", + "tags": [ + "ui", + "homepage" + ] + } + ] } } } }, "400": { - "$ref": "#/components/responses/400" + "$ref": "#/components/responses/400", + "description": "key_links_bad_request: The request body is malformed or a required parameter is missing." }, "401": { - "$ref": "#/components/responses/401" + "$ref": "#/components/responses/401", + "description": "key_links_unauthorized: The access token is missing or invalid." }, "403": { "$ref": "#/components/responses/403", - "description": "Forbidden. Returned when the access token lacks the `write` scope or when the requesting user is not allowed to link this key." + "description": "key_links_forbidden: The access token lacks the write scope, the user does not have write permission on key links, or the parent key belongs to a branch project." }, "404": { - "$ref": "#/components/responses/404" + "$ref": "#/components/responses/404", + "description": "key_links_not_found: The parent key does not exist in the specified project." }, "422": { - "$ref": "#/components/responses/422" + "$ref": "#/components/responses/422", + "description": "key_links_unprocessable: The link could not be created. See the errors array for a specific code: PARENT_IS_ALREADY_CHILD, PARENT_IS_SAME_AS_CHILD, CHILD_IS_ALREADY_LINKED, CHILD_IS_ON_BRANCH, PARENT_IS_NOT_PLURAL, PARENT_IS_PLURAL." }, "429": { - "$ref": "#/components/responses/429" + "$ref": "#/components/responses/429", + "description": "key_links_rate_limited: Too many requests. Wait until X-Rate-Limit-Reset before retrying." } - } + }, + "x-code-samples": [ + { + "lang": "Curl", + "source": "curl -X POST \"https://api.phrase.com/v2/projects/:project_id/keys/:id/key_links\" \\\n -u USERNAME_OR_ACCESS_TOKEN \\\n -H \"Content-Type: application/json\" \\\n -d '{\"child_key_ids\": [\"ijkl9012mnop3456ijkl9012mnop3456\", \"abcd1234efgh5678abcd1234efgh5678\"]}'\n\nHTTP/1.1 201 Created\n{\n \"created_at\": \"2024-03-15T10:22:00Z\",\n \"updated_at\": \"2024-03-15T10:22:00Z\",\n \"created_by\": {\n \"id\": \"usr1a2b3c4d5e6f7a8b9c\",\n \"username\": \"jane.doe\",\n \"name\": \"Jane Doe\",\n \"gravatar_uid\": \"a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4\"\n },\n \"updated_by\": {\n \"id\": \"usr1a2b3c4d5e6f7a8b9c\",\n \"username\": \"jane.doe\",\n \"name\": \"Jane Doe\",\n \"gravatar_uid\": \"a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4\"\n },\n \"account\": {\n \"id\": \"acct9z8y7x6w5v4u3t2s\",\n \"name\": \"Acme Translations\",\n \"slug\": \"acme-translations\",\n \"company\": \"Acme Corp\",\n \"created_at\": \"2023-01-10T08:00:00Z\",\n \"updated_at\": \"2023-06-01T12:00:00Z\",\n \"company_logo_url\": \"https://example.com/logos/acme.png\"\n },\n \"parent\": {\n \"id\": \"ijkl9012mnop3456ijkl9012\",\n \"name\": \"home.hero.title\",\n \"plural\": false,\n \"use_ordinal_rules\": false,\n \"data_type\": \"string\",\n \"tags\": [\"ui\", \"homepage\"]\n },\n \"children\": [\n {\n \"id\": \"ijkl9012mnop3456ijkl9012mnop3456\",\n \"name\": \"home.hero.title_short\",\n \"plural\": false,\n \"use_ordinal_rules\": false,\n \"data_type\": \"string\",\n \"tags\": [\"ui\", \"homepage\"]\n },\n {\n \"id\": \"abcd1234efgh5678abcd1234efgh5678\",\n \"name\": \"home.hero.title_long\",\n \"plural\": false,\n \"use_ordinal_rules\": false,\n \"data_type\": \"string\",\n \"tags\": [\"ui\", \"homepage\"]\n }\n ]\n}" + } + ], + "security": [ + { + "Token": [] + }, + { + "OAuth2": [ + "write" + ] + } + ] } }, "/projects/{project_id}/keys/{id}/key_links/{child_key_id}": { diff --git a/paths/key_links/create.yaml b/paths/key_links/create.yaml index ac3303c3..9ada93af 100644 --- a/paths/key_links/create.yaml +++ b/paths/key_links/create.yaml @@ -1,6 +1,18 @@ --- summary: Link child keys to a parent key -description: Creates links between a given parent key and one or more child keys. +description: | + Designates a translation key as a parent and links one or more child keys to it. Once linked, child keys receive a special reference marker as their translation content, signalling that their translations are derived from the parent. Use this when you want to group related keys — for example, a short label and its long-form variant — so translators see them in context together. + + Pass an empty child_key_ids array to mark the key as a parent without linking any children yet. Both the parent key and every child key must belong to the main project; branch keys cannot participate in key links. A child key can have at most one parent at a time; attempting to link a child that already has a parent returns a 422 error with code CHILD_IS_ALREADY_LINKED. Parent and child key plurality must match — linking a plural child to a non-plural parent (or vice versa) also returns a 422. + + Errors: + + - key_links_bad_request (400): The request body is malformed or a required field is missing. Correct the request structure and retry. + - key_links_unauthorized (401): The access token is missing or invalid. Supply a valid token. + - key_links_forbidden (403): The access token lacks the write scope, the requesting user does not have write permission on key links, or the parent key is on a branch project. Grant the required permission or use a main-project key. + - key_links_not_found (404): The parent key does not exist in this project. Verify the project_id and id values. + - key_links_unprocessable (422): The link could not be created. Common causes: PARENT_IS_ALREADY_CHILD (the parent key is itself a child), PARENT_IS_SAME_AS_CHILD (a child key ID matches the parent), CHILD_IS_ALREADY_LINKED (a child key already has another parent), CHILD_IS_ON_BRANCH (a child key is on a branch), PARENT_IS_NOT_PLURAL / PARENT_IS_PLURAL (plurality mismatch between parent and child). Inspect the errors array in the response body for the specific code. + - key_links_rate_limited (429): Too many requests. Wait until the X-Rate-Limit-Reset time before retrying. operationId: key_links/create tags: - Linked Keys @@ -19,29 +31,145 @@ requestBody: title: key_links/create/parameters properties: child_key_ids: - description: The IDs of the child keys to link to the parent key. Can be left empty, to only mark the given translation-key as parent + description: Codes of the keys to link as children. Pass an empty array to mark the parent key without linking any children. type: array - example: ["child_key_id1", "child_key_id2"] + example: + - "ijkl9012mnop3456ijkl9012mnop3456" + - "abcd1234efgh5678abcd1234efgh5678" items: type: string + example: + child_key_ids: + - "ijkl9012mnop3456ijkl9012mnop3456" + - "abcd1234efgh5678abcd1234efgh5678" responses: '201': - description: Created + description: Key link reference created. content: application/json: schema: "$ref": "../../schemas/key_link.yaml#/key_link" + example: + created_at: "2024-03-15T10:22:00Z" + updated_at: "2024-03-15T10:22:00Z" + created_by: + id: "usr1a2b3c4d5e6f7a8b9c" + username: "jane.doe" + name: "Jane Doe" + gravatar_uid: "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4" + updated_by: + id: "usr1a2b3c4d5e6f7a8b9c" + username: "jane.doe" + name: "Jane Doe" + gravatar_uid: "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4" + account: + id: "acct9z8y7x6w5v4u3t2s" + name: "Acme Translations" + slug: "acme-translations" + company: "Acme Corp" + created_at: "2023-01-10T08:00:00Z" + updated_at: "2023-06-01T12:00:00Z" + company_logo_url: "https://example.com/logos/acme.png" + parent: + id: "ijkl9012mnop3456ijkl9012" + name: "home.hero.title" + plural: false + use_ordinal_rules: false + data_type: "string" + tags: ["ui", "homepage"] + children: + - id: "ijkl9012mnop3456ijkl9012mnop3456" + name: "home.hero.title_short" + plural: false + use_ordinal_rules: false + data_type: "string" + tags: ["ui", "homepage"] + - id: "abcd1234efgh5678abcd1234efgh5678" + name: "home.hero.title_long" + plural: false + use_ordinal_rules: false + data_type: "string" + tags: ["ui", "homepage"] '400': "$ref": "../../responses.yaml#/400" + description: "key_links_bad_request: The request body is malformed or a required parameter is missing." '401': "$ref": "../../responses.yaml#/401" + description: "key_links_unauthorized: The access token is missing or invalid." '403': "$ref": "../../responses.yaml#/403" - description: Forbidden. Returned when the access token lacks the `write` scope or when the requesting user is not allowed to link this key. + description: "key_links_forbidden: The access token lacks the write scope, the user does not have write permission on key links, or the parent key belongs to a branch project." '404': "$ref": "../../responses.yaml#/404" + description: "key_links_not_found: The parent key does not exist in the specified project." '422': "$ref": "../../responses.yaml#/422" + description: "key_links_unprocessable: The link could not be created. See the errors array for a specific code: PARENT_IS_ALREADY_CHILD, PARENT_IS_SAME_AS_CHILD, CHILD_IS_ALREADY_LINKED, CHILD_IS_ON_BRANCH, PARENT_IS_NOT_PLURAL, PARENT_IS_PLURAL." '429': "$ref": "../../responses.yaml#/429" + description: "key_links_rate_limited: Too many requests. Wait until X-Rate-Limit-Reset before retrying." +x-code-samples: +- lang: Curl + source: |- + curl -X POST "https://api.phrase.com/v2/projects/:project_id/keys/:id/key_links" \ + -u USERNAME_OR_ACCESS_TOKEN \ + -H "Content-Type: application/json" \ + -d '{"child_key_ids": ["ijkl9012mnop3456ijkl9012mnop3456", "abcd1234efgh5678abcd1234efgh5678"]}' + + HTTP/1.1 201 Created + { + "created_at": "2024-03-15T10:22:00Z", + "updated_at": "2024-03-15T10:22:00Z", + "created_by": { + "id": "usr1a2b3c4d5e6f7a8b9c", + "username": "jane.doe", + "name": "Jane Doe", + "gravatar_uid": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4" + }, + "updated_by": { + "id": "usr1a2b3c4d5e6f7a8b9c", + "username": "jane.doe", + "name": "Jane Doe", + "gravatar_uid": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4" + }, + "account": { + "id": "acct9z8y7x6w5v4u3t2s", + "name": "Acme Translations", + "slug": "acme-translations", + "company": "Acme Corp", + "created_at": "2023-01-10T08:00:00Z", + "updated_at": "2023-06-01T12:00:00Z", + "company_logo_url": "https://example.com/logos/acme.png" + }, + "parent": { + "id": "ijkl9012mnop3456ijkl9012", + "name": "home.hero.title", + "plural": false, + "use_ordinal_rules": false, + "data_type": "string", + "tags": ["ui", "homepage"] + }, + "children": [ + { + "id": "ijkl9012mnop3456ijkl9012mnop3456", + "name": "home.hero.title_short", + "plural": false, + "use_ordinal_rules": false, + "data_type": "string", + "tags": ["ui", "homepage"] + }, + { + "id": "abcd1234efgh5678abcd1234efgh5678", + "name": "home.hero.title_long", + "plural": false, + "use_ordinal_rules": false, + "data_type": "string", + "tags": ["ui", "homepage"] + } + ] + } +security: +- Token: [] +- OAuth2: + - write