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

[Stephen Lumenta (sbl)]

Improves the documentation for delete /projects/{project_id}/keys/{id}/key_links/{child_key_id}: sharper descriptions, parameter docs, error responses, and usage examples.

Drafted with AI assistance and grounded in the API implementation. Please review for technical accuracy before merging; nothing is merged automatically.

🤖 Generated with Claude Code

[github-actions]

API changelog (oasdiff)

Doc-only edits (descriptions, examples) do not appear here.

14 changes: 0 error, 3 warning, 11 info
warning	[optional-response-header-removed] at doc/compiled.json
	in API DELETE /projects/{project_id}/keys/{id}/key_links/{child_key_id}
		the optional response header `x-rate-limit-limit` removed for the status `422`

warning	[optional-response-header-removed] at doc/compiled.json
	in API DELETE /projects/{project_id}/keys/{id}/key_links/{child_key_id}
		the optional response header `x-rate-limit-remaining` removed for the status `422`

warning	[optional-response-header-removed] at doc/compiled.json
	in API DELETE /projects/{project_id}/keys/{id}/key_links/{child_key_id}
		the optional response header `x-rate-limit-reset` removed for the status `422`

info	[response-property-became-required] at doc/compiled.json
	in API GET /formats
		the response property `items/api_name` became required for the status `200`

info	[response-property-became-required] at doc/compiled.json
	in API GET /formats
		the response property `items/default_encoding` became required for the status `200`

info	[response-property-became-required] at doc/compiled.json
	in API GET /formats
		the response property `items/default_file` became required for the status `200`

info	[response-property-became-required] at doc/compiled.json
	in API GET /formats
		the response property `items/description` became required for the status `200`

info	[response-property-became-required] at doc/compiled.json
	in API GET /formats
		the response property `items/exportable` became required for the status `200`

info	[response-property-became-required] at doc/compiled.json
	in API GET /formats
		the response property `items/extension` became required for the status `200`

info	[response-property-became-required] at doc/compiled.json
	in API GET /formats
		the response property `items/importable` became required for the status `200`

info	[response-property-became-required] at doc/compiled.json
	in API GET /formats
		the response property `items/includes_locale_information` became required for the status `200`

info	[response-property-became-required] at doc/compiled.json
	in API GET /formats
		the response property `items/name` became required for the status `200`

info	[response-property-became-required] at doc/compiled.json
	in API GET /formats
		the response property `items/renders_default_locale` became required for the status `200`

info	[response-optional-property-added] at doc/compiled.json
	in API DELETE /projects/{project_id}/keys/{id}/key_links/{child_key_id}
		added the optional property `errors/items/code` to the response with the `422` status

[jablan]

if we want to merge these PRs individually, we should probably go with fix(...) instead of feat(...) in cases like this, where only the error response is being updated. otherwise we'll have huge number of minor version bumps, one for every PR. keeping them at the fix level, we could also group them in a way.

[Stephen Lumenta (sbl)]

if we want to merge these PRs individually, we should probably go with fix(...) instead of feat(...) in cases like this, where only the error response is being updated. otherwise we'll have huge number of minor version bumps, one for every PR. keeping them at the fix level, we could also group them in a way.

jablan very useful insight! so the automation here is triggered by the PR title? I'd then manually fix here and update the prompt instructions.

[Sven Dunemann (forelabs)]

jablan would you consider this as "fix" ? I'd say this is just "docs" update - wdyt?

[Stephen Lumenta (sbl)]

On the feat vs fix vs docs question (thanks jablan Sven Dunemann (@forelabs)): we've standardized the batch as follows —

• docs(API): for PRs that only change descriptions / examples and produce no compiled-API change (oasdiff reports No changes to report). These cause no version bump.
• fix(API): for PRs that do change the compiled API surface (added/removed properties, response media types, headers, etc.).

We're avoiding feat for this work so we don't get a minor bump per PR. This PR changes the 422 response (adds errors/items/code and adjusts the rate-limit headers), so it stays fix. The pure description/example PRs in the batch have been retitled to docs.

[jablan]

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.

[jablan]

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.