Skip to content

fix(API): improve post /projects/{project_id}/figma_attachments/{figma_attachment_id}/keys documentation#1184

Open
Stephen Lumenta (sbl) wants to merge 2 commits into
mainfrom
devex-118-keys-figma-attachments-attach-figma-key-v2
Open

fix(API): improve post /projects/{project_id}/figma_attachments/{figma_attachment_id}/keys documentation#1184
Stephen Lumenta (sbl) wants to merge 2 commits into
mainfrom
devex-118-keys-figma-attachments-attach-figma-key-v2

Conversation

@sbl

@sbl Stephen Lumenta (sbl) commented Jun 15, 2026

Copy link
Copy Markdown
Contributor

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

Closes DEVEX-118

🤖 Generated with Claude Code

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

github-actions Bot commented Jun 15, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

API changelog (oasdiff)

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

15 changes: 1 error, 1 warning, 13 info
error	[request-body-added-required] at doc/compiled.json
	in API POST /projects/{project_id}/figma_attachments/{figma_attachment_id}/keys
		added required request body

warning	[request-parameter-removed] at doc/compiled.json
	in API POST /projects/{project_id}/figma_attachments/{figma_attachment_id}/keys
		deleted the `path` request parameter `id`
		This is a warning because some clients may return an error when receiving an unexpected parameter. It is recommended to deprecate the parameter first.

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-non-success-status-added] at doc/compiled.json
	in API POST /projects/{project_id}/figma_attachments/{figma_attachment_id}/keys
		added the non-success response with the status `401`

info	[response-non-success-status-added] at doc/compiled.json
	in API POST /projects/{project_id}/figma_attachments/{figma_attachment_id}/keys
		added the non-success response with the status `403`

info	[response-non-success-status-added] at doc/compiled.json
	in API POST /projects/{project_id}/figma_attachments/{figma_attachment_id}/keys
		added the non-success response with the status `422`

@sbl Stephen Lumenta (sbl) changed the title feat(API): improve post /projects/{project_id}/figma_attachments/{figma_attachment_id}/keys documentation fix(API): improve post /projects/{project_id}/figma_attachments/{figma_attachment_id}/keys documentation Jun 17, 2026
theSoenke
Sönke Behrendt (theSoenke) reviewed Jun 17, 2026
View reviewed changes
Comment thread paths/figma_attachment_keys/create.yaml Outdated
Comment thread paths/figma_attachment_keys/create.yaml Outdated
Comment thread paths/figma_attachment_keys/create.yaml Outdated
@sbl @claude
fix(API): address review on post .../figma_attachments/{figma_attachm…
bb59c1e 
…ent_id}/keys

- Move the per-status prose out of the top-level description and onto the
  response objects (the pattern from #1182), removing the 'Errors:' block
  and the inline 'Returns 422 ...' sentence. (theSoenke)
- Normalize the branch parameter (query + body) to 'specify the branch to
  use', matching the wording used across the rest of the API rather than a
  bespoke 'When omitted, the main (default) branch is used.' (theSoenke)
- Fix the CLI v2 command: 'phrase figma_attachments create', not the
  non-existent 'phrase figma_attachment attach_to_key'. (theSoenke)

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@theSoenke Sönke Behrendt (theSoenke) theSoenke left review comments

At least 1 approving review is required to merge this pull request.

Assignees

No one assigned

Labels

developer-hub-api-quality API doc quality fix from the API Grader

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

2 participants

@sbl @theSoenke