Upload an explicitly selected frame image

Local development Figma integration. Current session, membership and scoped permissions are checked. No SDK key or provider secret grants management access.

PUT /api/v1/figma/keys/{key}/images/{id}/file

Operation: uploadFigmaImage · Download OpenAPI

Access

This operation does not use the panel session as its authentication mechanism. Follow the operation-specific checks described above.

plugin

{
  "type": "http",
  "scheme": "bearer",
  "description": "Ephemeral delegated credential held in plugin memory; current parent session and scope remain authoritative."
}

Parameters

Name	Location	Required	Description
key	path	Yes	See constraints below.
id	path	Yes	See constraints below.
X-Localisync-Figma-Protocol	header	Yes	See constraints below.
Origin	header	Yes	Must equal the configured panel origin.

key

{
  "type": "string",
  "format": "uuid"
}

id

{
  "type": "string",
  "format": "uuid"
}

X-Localisync-Figma-Protocol

{
  "type": "string",
  "enum": [
    "1"
  ]
}

Origin

{
  "type": "string"
}

Request body

Required: Yes.

multipart/form-data

Schema reference: WImageUpload.

Field	Type	Required	Constraints / description
file	string	Yes	—

{
  "$ref": "#/components/schemas/WImageUpload"
}

Responses

200

Authorized result.

Content type: application/json Schema reference: WImageQueued.

Field	Type	Required	Constraints / description
id	string	Yes	format: "uuid"; pattern: "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
state	string	Yes	—

{
  "$ref": "#/components/schemas/WImageQueued"
}

400

Safe failure; preserve drafts and inspect the existing operation before retrying.

Content type: application/json Schema reference: Error.

Field	Type	Required	Constraints / description
error	string	Yes	—
message	string	Yes	—
requestId	string	No	format: "uuid"; pattern: "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"

{
  "$ref": "#/components/schemas/Error"
}

401

Safe failure; preserve drafts and inspect the existing operation before retrying.

Content type: application/json Schema reference: Error.

Field	Type	Required	Constraints / description
error	string	Yes	—
message	string	Yes	—
requestId	string	No	format: "uuid"; pattern: "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"

{
  "$ref": "#/components/schemas/Error"
}

403

Safe failure; preserve drafts and inspect the existing operation before retrying.

Content type: application/json Schema reference: Error.

Field	Type	Required	Constraints / description
error	string	Yes	—
message	string	Yes	—
requestId	string	No	format: "uuid"; pattern: "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"

{
  "$ref": "#/components/schemas/Error"
}

404

Safe failure; preserve drafts and inspect the existing operation before retrying.

Content type: application/json Schema reference: Error.

Field	Type	Required	Constraints / description
error	string	Yes	—
message	string	Yes	—
requestId	string	No	format: "uuid"; pattern: "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"

{
  "$ref": "#/components/schemas/Error"
}

409

Safe failure; preserve drafts and inspect the existing operation before retrying.

Content type: application/json Schema reference: Error.

Field	Type	Required	Constraints / description
error	string	Yes	—
message	string	Yes	—
requestId	string	No	format: "uuid"; pattern: "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"

{
  "$ref": "#/components/schemas/Error"
}

413

Safe failure; preserve drafts and inspect the existing operation before retrying.

Content type: application/json Schema reference: Error.

Field	Type	Required	Constraints / description
error	string	Yes	—
message	string	Yes	—
requestId	string	No	format: "uuid"; pattern: "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"

{
  "$ref": "#/components/schemas/Error"
}

429

Safe failure; preserve drafts and inspect the existing operation before retrying.

Content type: application/json Schema reference: Error.

Field	Type	Required	Constraints / description
error	string	Yes	—
message	string	Yes	—
requestId	string	No	format: "uuid"; pattern: "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"

{
  "$ref": "#/components/schemas/Error"
}

500

Safe failure; preserve drafts and inspect the existing operation before retrying.

Content type: application/json Schema reference: Error.

Field	Type	Required	Constraints / description
error	string	Yes	—
message	string	Yes	—
requestId	string	No	format: "uuid"; pattern: "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"

{
  "$ref": "#/components/schemas/Error"
}

503

Safe failure; preserve drafts and inspect the existing operation before retrying.

Content type: application/json Schema reference: Error.

Field	Type	Required	Constraints / description
error	string	Yes	—
message	string	Yes	—
requestId	string	No	format: "uuid"; pattern: "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"

{
  "$ref": "#/components/schemas/Error"
}

Related guidance

Request errors and safe retries · Troubleshooting