docs(API): improve post /projects/{project_id}/keys/{id}/key_links documentation by sbl · Pull Request #1192 · phrase/strings-openapi

Stephen Lumenta (sbl) · 2026-06-15T16:22:45Z

Improves the documentation for post /projects/{project_id}/keys/{id}/key_links: 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.

Jira: DEVEX-116

🤖 Generated with Claude Code

…cumentation

github-actions · 2026-06-15T16:23:35Z

API changelog (oasdiff)

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

47 changes: 10 error, 0 warning, 37 info
error	[response-property-became-nullable] at doc/compiled.json
	in API GET /accounts/{account_id}/repo_syncs
		the response property `items/last_export_at` became nullable for the status `200`

error	[response-property-became-nullable] at doc/compiled.json
	in API GET /accounts/{account_id}/repo_syncs
		the response property `items/last_import_at` became nullable for the status `200`

error	[response-property-became-nullable] at doc/compiled.json
	in API POST /accounts/{account_id}/repo_syncs
		the response property `last_export_at` became nullable for the status `201`

error	[response-property-became-nullable] at doc/compiled.json
	in API POST /accounts/{account_id}/repo_syncs
		the response property `last_import_at` became nullable for the status `201`

error	[response-property-became-nullable] at doc/compiled.json
	in API GET /accounts/{account_id}/repo_syncs/{id}
		the response property `last_export_at` became nullable for the status `200`

error	[response-property-became-nullable] at doc/compiled.json
	in API GET /accounts/{account_id}/repo_syncs/{id}
		the response property `last_import_at` became nullable for the status `200`

error	[response-property-became-nullable] at doc/compiled.json
	in API POST /accounts/{account_id}/repo_syncs/{id}/activate
		the response property `last_export_at` became nullable for the status `200`

error	[response-property-became-nullable] at doc/compiled.json
	in API POST /accounts/{account_id}/repo_syncs/{id}/activate
		the response property `last_import_at` became nullable for the status `200`

error	[response-property-became-nullable] at doc/compiled.json
	in API POST /accounts/{account_id}/repo_syncs/{id}/deactivate
		the response property `last_export_at` became nullable for the status `200`

error	[response-property-became-nullable] at doc/compiled.json
	in API POST /accounts/{account_id}/repo_syncs/{id}/deactivate
		the response property `last_import_at` became nullable for the status `200`

info	[response-optional-property-added] at doc/compiled.json
	in API GET /accounts/{account_id}/jobs
		added the optional property `items/review_due_date` to the response with the `200` status

info	[response-optional-property-added] at doc/compiled.json
	in API GET /accounts/{account_id}/repo_syncs
		added the optional property `items/name` to the response with the `200` status

info	[new-optional-request-property] at doc/compiled.json
	in API POST /accounts/{account_id}/repo_syncs
		added the new optional request property `name`

info	[response-optional-property-added] at doc/compiled.json
	in API POST /accounts/{account_id}/repo_syncs
		added the optional property `name` to the response with the `201` status

info	[response-optional-property-added] at doc/compiled.json
	in API GET /accounts/{account_id}/repo_syncs/{id}
		added the optional property `name` to the response with the `200` status

info	[response-optional-property-added] at doc/compiled.json
	in API POST /accounts/{account_id}/repo_syncs/{id}/activate
		added the optional property `name` to the response with the `200` status

info	[response-optional-property-added] at doc/compiled.json
	in API POST /accounts/{account_id}/repo_syncs/{id}/deactivate
		added the optional property `name` to the response with the `200` status

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-media-type-added] at doc/compiled.json
	in API GET /projects/{project_id}/branches/{name}/compare
		added the media type `application/json` for the response with the status `200`

info	[response-optional-property-added] at doc/compiled.json
	in API GET /projects/{project_id}/jobs
		added the optional property `items/review_due_date` to the response with the `200` status

info	[response-optional-property-added] at doc/compiled.json
	in API POST /projects/{project_id}/jobs
		added the optional property `allOf[subschema #1: job]/review_due_date` to the response with the `201` status

info	[response-optional-property-added] at doc/compiled.json
	in API POST /projects/{project_id}/jobs
		added the optional property `allOf[subschema #2: job_details]/review_due_date` to the response with the `201` status

info	[response-optional-property-added] at doc/compiled.json
	in API GET /projects/{project_id}/jobs/{id}
		added the optional property `allOf[subschema #1: job]/review_due_date` to the response with the `200` status

info	[response-optional-property-added] at doc/compiled.json
	in API GET /projects/{project_id}/jobs/{id}
		added the optional property `allOf[subschema #2: job_details]/review_due_date` to the response with the `200` status

info	[response-optional-property-added] at doc/compiled.json
	in API PATCH /projects/{project_id}/jobs/{id}
		added the optional property `allOf[subschema #1: job]/review_due_date` to the response with the `200` status

info	[response-optional-property-added] at doc/compiled.json
	in API PATCH /projects/{project_id}/jobs/{id}
		added the optional property `allOf[subschema #2: job_details]/review_due_date` to the response with the `200` status

info	[response-optional-property-added] at doc/compiled.json
	in API POST /projects/{project_id}/jobs/{id}/complete
		added the optional property `allOf[subschema #1: job]/review_due_date` to the response with the `200` status

info	[response-optional-property-added] at doc/compiled.json
	in API POST /projects/{project_id}/jobs/{id}/complete
		added the optional property `allOf[subschema #2: job_details]/review_due_date` to the response with the `200` status

info	[response-optional-property-added] at doc/compiled.json
	in API POST /projects/{project_id}/jobs/{id}/keys
		added the optional property `allOf[subschema #1: job]/review_due_date` to the response with the `200` status

info	[response-optional-property-added] at doc/compiled.json
	in API POST /projects/{project_id}/jobs/{id}/keys
		added the optional property `allOf[subschema #2: job_details]/review_due_date` to the response with the `200` status

info	[response-optional-property-added] at doc/compiled.json
	in API POST /projects/{project_id}/jobs/{id}/lock
		added the optional property `allOf[subschema #1: job]/review_due_date` to the response with the `200` status

info	[response-optional-property-added] at doc/compiled.json
	in API POST /projects/{project_id}/jobs/{id}/lock
		added the optional property `allOf[subschema #2: job_details]/review_due_date` to the response with the `200` status

info	[response-optional-property-added] at doc/compiled.json
	in API POST /projects/{project_id}/jobs/{id}/reopen
		added the optional property `allOf[subschema #1: job]/review_due_date` to the response with the `200` status

info	[response-optional-property-added] at doc/compiled.json
	in API POST /projects/{project_id}/jobs/{id}/reopen
		added the optional property `allOf[subschema #2: job_details]/review_due_date` to the response with the `200` status

info	[response-optional-property-added] at doc/compiled.json
	in API POST /projects/{project_id}/jobs/{id}/start
		added the optional property `allOf[subschema #1: job]/review_due_date` to the response with the `200` status

info	[response-optional-property-added] at doc/compiled.json
	in API POST /projects/{project_id}/jobs/{id}/start
		added the optional property `allOf[subschema #2: job_details]/review_due_date` to the response with the `200` status

info	[response-optional-property-added] at doc/compiled.json
	in API POST /projects/{project_id}/jobs/{id}/unlock
		added the optional property `allOf[subschema #1: job]/review_due_date` to the response with the `200` status

info	[response-optional-property-added] at doc/compiled.json
	in API POST /projects/{project_id}/jobs/{id}/unlock
		added the optional property `allOf[subschema #2: job_details]/review_due_date` to the response with the `200` status

Apply the same review conventions landed on the reviewed PRs in this batch: - Remove the 'Errors:' enumeration from the top-level description; each status code already carries its own description on the response object. - Drop the 'HTTP/1.1 201 Created' response trailer from the curl sample. - Remove the endpoint-level security block (was overriding the global Token/Basic security with OAuth2 on just this operation, which oasdiff flagged and theSoenke flagged on the sibling screenshots PR). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Review feedback: error response descriptions should stay in the shared responses.yaml for consistency, not be re-authored inline per operation. Under OpenAPI 3.0 a description sibling of $ref is ignored anyway, so the inline text never rendered. Strip the inline $ref-sibling response descriptions (now bare $refs); the shared response owns the wording. Genuinely custom (non-$ref) response bodies are left intact. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

feat(API): improve post /projects/{project_id}/keys/{id}/key_links do…

b50e22b

…cumentation

Stephen Lumenta (sbl) added the developer-hub-api-quality API doc quality fix from the API Grader label Jun 15, 2026

Stephen Lumenta (sbl) changed the title ~~feat(API): improve post /projects/{project_id}/keys/{id}/key_links documentation~~ fix(API): improve post /projects/{project_id}/keys/{id}/key_links documentation Jun 17, 2026

Stephen Lumenta (sbl) changed the title ~~fix(API): improve post /projects/{project_id}/keys/{id}/key_links documentation~~ docs(API): improve post /projects/{project_id}/keys/{id}/key_links documentation Jun 17, 2026

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs(API): improve post /projects/{project_id}/keys/{id}/key_links documentation#1192

docs(API): improve post /projects/{project_id}/keys/{id}/key_links documentation#1192
Stephen Lumenta (sbl) wants to merge 3 commits into
mainfrom
devex-116-linked-keys-link-child-keys-to-a-parent-key-v2

Stephen Lumenta (sbl) commented Jun 15, 2026

Uh oh!

github-actions Bot commented Jun 15, 2026 •

edited

Loading

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Conversation

Stephen Lumenta (sbl) commented Jun 15, 2026

Uh oh!

github-actions Bot commented Jun 15, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

API changelog (oasdiff)

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

github-actions Bot commented Jun 15, 2026 •

edited

Loading