diff --git a/doc/compiled.json b/doc/compiled.json index afba5090..5e021d7e 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", "operationId": "key_links/create", "tags": [ "Linked Keys" @@ -30969,52 +30969,129 @@ "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\"]}'" + } + ] } }, "/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..b5e4e688 100644 --- a/paths/key_links/create.yaml +++ b/paths/key_links/create.yaml @@ -1,6 +1,9 @@ --- 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. operationId: key_links/create tags: - Linked Keys @@ -19,29 +22,88 @@ 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"]}'