Skip to content

fix(API): improve delete /projects/{project_id}/keys/{id}/key_links/{child_key_id} documentation #1194

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
Stephen Lumenta (sbl) wants to merge 2 commits into
base: main
Choose a base branch
from
Open

fix(API): improve delete /projects/{project_id}/keys/{id}/key_links/{child_key_id} documentation #1194

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
530fe41
feat(API): improve delete /projects/{project_id}/keys/{id}/key_links/…
sbl Jun 15, 2026
6ae7592
fix(API): clean up delete .../key_links/{child_key_id}
sbl Jun 17, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
90 changes: 82 additions & 8 deletions doc/compiled.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -31020,7 +31020,7 @@
"/projects/{project_id}/keys/{id}/key_links/{child_key_id}": {
"delete": {
"summary": "Unlink a child key from a parent key",
"description": "Unlinks a single child key from a given parent key.",
"description": "Removes a single child key from a parent key's link group. A link group is the relationship model that keeps child keys synchronized with a parent: while linked, a child key's translations are derived from the parent's content. When you call this endpoint, the child key leaves the group and becomes independent — its existing translations are updated with the parent's current content and then marked unverified, signalling that reviewers should confirm the content is still appropriate for the child's context.\n\nUse this endpoint when you need to detach one specific child key while keeping other children linked. To detach multiple children at once, use the batch unlink endpoint. This operation is only available on main projects.\n\nWhen the operation fails, the response body includes an errors array. Each error object carries a code field using UPPER_SNAKE_CASE stable identifiers (for example, KEY_IS_NOT_LINKED) that you can match programmatically to distinguish error conditions.\n",
"operationId": "key_links/destroy",
"tags": [
"Linked Keys"
Expand All @@ -31038,37 +31038,111 @@
{
"in": "path",
"name": "child_key_id",
"description": "The ID of the child translation key to unlink from the parent.",
"required": true,
"description": "The ID of the child key to unlink.",
"schema": {
"type": "string"
"type": "string",
"example": "1234abcd1234cdef1234abcd1234cdef"
}
}
],
"responses": {
"200": {
"description": "OK"
"description": "The child key was successfully unlinked from the parent key. The response body is empty.",
"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"
}
},
"content": {}
},
"400": {
"description": "Bad request. Returned when the request is malformed, such as unparseable JSON in the request body. Fix the request format and retry.\n",
"$ref": "#/components/responses/400"
},
"401": {
"description": "Unauthorized. The access token is missing or invalid. Provide a valid token with the write scope and retry.\n",
"$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 unlink this key."
"description": "Forbidden. Returned when the access token lacks the write scope, when the requester does not have write permission on translation key links, or when the project is a branch rather than a main project. Verify scope and project type before retrying.\n",
"$ref": "#/components/responses/403"
},
"404": {
"description": "Not found. Returned when the parent key does not exist in the project. Check that the project_id and id path parameters reference existing resources.\n",
"$ref": "#/components/responses/404"
},
"422": {
"$ref": "#/components/responses/422"
"description": "Unprocessable entity. Returned when the child key is not currently linked to the specified parent key, or when a translation update fails during the unlink process. The errors array contains a code field with a stable UPPER_SNAKE_CASE identifier — KEY_IS_NOT_LINKED indicates the child is not in this key link group. Verify the child_key_id is linked to this parent before retrying.\n",
"content": {
"application/json": {
"schema": {
"type": "object",
"title": "key_links/destroy/error",
"properties": {
"message": {
"type": "string",
"description": "A human-readable description of the error."
},
"errors": {
"type": "array",
"items": {
"type": "object",
"title": "key_links/destroy/error/item",
"properties": {
"resource": {
"type": "string",
"description": "The resource type the error applies to."
},
"field": {
"type": "string",
"description": "The field the error applies to."
},
"message": {
"type": "string",
"description": "A human-readable description of the validation error."
},
"code": {
"type": "string",
"description": "A stable UPPER_SNAKE_CASE machine-readable code identifying this error condition.",
"example": "KEY_IS_NOT_LINKED"
}
}
}
}
}
},
"example": {
"message": "Child key 1234abcd1234cdef1234abcd1234cdef is not linked to this parent key.",
"errors": [
{
"resource": "base",
"field": "base",
"message": "Child key 1234abcd1234cdef1234abcd1234cdef is not linked to this parent key.",
"code": "KEY_IS_NOT_LINKED"
}
]
}
}
}
},
"429": {
"description": "Too many requests. You have exceeded the rate limit. Wait until the time indicated in X-Rate-Limit-Reset before retrying.\n",
"$ref": "#/components/responses/429"
}
}
},
"x-code-samples": [
{
"lang": "Curl",
"source": "curl -i \"https://api.phrase.com/v2/projects/:project_id/keys/:id/key_links/1234abcd1234cdef1234abcd1234cdef\" \\\n -u USERNAME_OR_ACCESS_TOKEN \\\n -X DELETE"
}
]
}
},
"/accounts/{account_id}/automations": {
Expand Down
76 changes: 70 additions & 6 deletions paths/key_links/destroy.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,11 @@
---
summary: Unlink a child key from a parent key
description: Unlinks a single child key from a given parent key.
description: |
Removes a single child key from a parent key's link group. A link group is the relationship model that keeps child keys synchronized with a parent: while linked, a child key's translations are derived from the parent's content. When you call this endpoint, the child key leaves the group and becomes independent — its existing translations are updated with the parent's current content and then marked unverified, signalling that reviewers should confirm the content is still appropriate for the child's context.

Use this endpoint when you need to detach one specific child key while keeping other children linked. To detach multiple children at once, use the batch unlink endpoint. This operation is only available on main projects.

When the operation fails, the response body includes an errors array. Each error object carries a code field using UPPER_SNAKE_CASE stable identifiers (for example, KEY_IS_NOT_LINKED) that you can match programmatically to distinguish error conditions.
operationId: key_links/destroy
tags:
- Linked Keys
Expand All @@ -10,24 +15,83 @@ parameters:
- "$ref": "../../parameters.yaml#/key_id_as_id"
- in: path
name: child_key_id
description: The ID of the child translation key to unlink from the parent.
required: true
description: The ID of the child key to unlink.
schema:
type: string

example: 1234abcd1234cdef1234abcd1234cdef
responses:
'200':
description: OK
description: The child key was successfully unlinked from the parent key. The response body is empty.
headers:
X-Rate-Limit-Limit:
"$ref": "../../headers.yaml#/X-Rate-Limit-Limit"
X-Rate-Limit-Remaining:
"$ref": "../../headers.yaml#/X-Rate-Limit-Remaining"
X-Rate-Limit-Reset:
"$ref": "../../headers.yaml#/X-Rate-Limit-Reset"
content: {}
'400':
description: |
Bad request. Returned when the request is malformed, such as unparseable JSON in the request body. Fix the request format and retry.
"$ref": "../../responses.yaml#/400"
'401':
description: |

@jablan jablan Jun 19, 2026

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

same as for 429 error below, try to find a generic formulation and update responses.yml#401 with it. if there are more than one generic case, we could separate it to 401_write and 401_read for example and use the appropriate reference where needed.

Unauthorized. The access token is missing or invalid. Provide a valid token with the write scope and retry.
"$ref": "../../responses.yaml#/401"
'403':
description: |
Forbidden. Returned when the access token lacks the write scope, when the requester does not have write permission on translation key links, or when the project is a branch rather than a main project. Verify scope and project type before retrying.
"$ref": "../../responses.yaml#/403"
description: Forbidden. Returned when the access token lacks the `write` scope or when the requesting user is not allowed to unlink this key.
'404':
description: |
Not found. Returned when the parent key does not exist in the project. Check that the project_id and id path parameters reference existing resources.
"$ref": "../../responses.yaml#/404"
'422':
"$ref": "../../responses.yaml#/422"
description: |
Unprocessable entity. Returned when the child key is not currently linked to the specified parent key, or when a translation update fails during the unlink process. The errors array contains a code field with a stable UPPER_SNAKE_CASE identifier — KEY_IS_NOT_LINKED indicates the child is not in this key link group. Verify the child_key_id is linked to this parent before retrying.
content:
application/json:
schema:
type: object
title: key_links/destroy/error
properties:
message:
type: string
description: A human-readable description of the error.
errors:
type: array
items:
type: object
title: key_links/destroy/error/item
properties:
resource:
type: string
description: The resource type the error applies to.
field:
type: string
description: The field the error applies to.
message:
type: string
description: A human-readable description of the validation error.
code:
type: string
description: A stable UPPER_SNAKE_CASE machine-readable code identifying this error condition.
example: KEY_IS_NOT_LINKED
example:
message: Child key 1234abcd1234cdef1234abcd1234cdef is not linked to this parent key.
errors:
- resource: base
field: base
message: Child key 1234abcd1234cdef1234abcd1234cdef is not linked to this parent key.
code: KEY_IS_NOT_LINKED
'429':
description: |
Too many requests. You have exceeded the rate limit. Wait until the time indicated in X-Rate-Limit-Reset before retrying.

@jablan jablan Jun 19, 2026

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

As this is a generic universal response for 429, it should live in responses.yaml#429. We should try to keep the error section as generic as possible to avoid duplicating the same or very similar content.

"$ref": "../../responses.yaml#/429"
x-code-samples:
- lang: Curl
source: |-
curl -i "https://api.phrase.com/v2/projects/:project_id/keys/:id/key_links/1234abcd1234cdef1234abcd1234cdef" \
-u USERNAME_OR_ACCESS_TOKEN \
-X DELETE
Loading