diff --git a/doc/compiled.json b/doc/compiled.json index cbe42593c..70a5b964c 100644 --- a/doc/compiled.json +++ b/doc/compiled.json @@ -31209,7 +31209,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" @@ -31237,28 +31237,94 @@ "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" + ] + } + ] } } } @@ -31270,8 +31336,7 @@ "$ref": "#/components/responses/401" }, "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." + "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" @@ -31282,7 +31347,13 @@ "429": { "$ref": "#/components/responses/429" } - } + }, + "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 ac3303c3c..0d1cc7701 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,82 @@ 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" '401': "$ref": "../../responses.yaml#/401" '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. '404': "$ref": "../../responses.yaml#/404" '422': "$ref": "../../responses.yaml#/422" '429': "$ref": "../../responses.yaml#/429" +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"]}'