{"openapi":"3.1.0","info":{"title":"Figma (BYOK) API","version":"0.1.0","description":"Figma (BYOK) lets an AI assistant read your own Figma data through the Figma API with a key you supply (personal access token). Read-only: 10 tools (get_current_user, get_file_metadata, get_file_outline, list_file_comments, list_file_versions, list_team_folders, list_folder_files, list_folder_subfolders, list_file_components, list_file_styles). The BYOK key travels with each request, is used for...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-figma.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-figma/docs"},"termsOfService":"https://connectorbay.com/byok-figma/terms"},"servers":[{"url":"https://byok-figma.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-figma/docs"},"security":[{"upstreamKey":[]}],"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"Optional. A Pro API key raises rate limits; no credentials are required."},"upstreamKey":{"type":"apiKey","in":"header","name":"X-Upstream-Key","description":"Your own key for the service this connector wraps (bring your own key). Used for that one call only; never stored, logged or cached."}},"schemas":{"Error":{"type":"object","properties":{"ok":{"const":false},"error":{"type":"object"}}}}},"paths":{"/v1/tools/get_current_user":{"post":{"operationId":"get_current_user","summary":"Show the Figma user the token belongs to: id, handle and email. Use for \"Which Figma account is my token connected to\".","description":"Show the Figma user the token belongs to: id, handle and email. Use for \"Which Figma account is my token connected to\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"get_current_userArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_file_metadata":{"post":{"operationId":"get_file_metadata","summary":"Get a file's name, folder, creator, last editor, last touched time, editor type, your role, link access and URL without ","description":"Get a file's name, folder, creator, last editor, last touched time, editor type, your role, link access and URL without its contents. Use for \"Who last edited Figma file abc123XYZ and when\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"file_key":{"description":"File key: the part after /file/ or /design/ in a Figma file URL, for example 'abc123XYZ'.","maxLength":200,"title":"File Key","type":"string"}},"required":["file_key"],"title":"get_file_metadataArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_file_outline":{"post":{"operationId":"get_file_outline","summary":"Get a file's name, last modified time and version plus its document tree down to a depth (1 returns just the pages, 2 ad","description":"Get a file's name, last modified time and version plus its document tree down to a depth (1 returns just the pages, 2 adds top-level frames). Large files at deeper depths are cut off. Use for \"What pages does Figma file abc123XYZ have\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"file_key":{"description":"File key: the part after /file/ or /design/ in a Figma file URL, for example 'abc123XYZ'.","maxLength":200,"title":"File Key","type":"string"},"depth":{"anyOf":[{"maximum":3,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"How many levels of the document tree to return (1 = pages only, 2 = pages and top-level frames).","title":"Depth"}},"required":["file_key"],"title":"get_file_outlineArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_file_comments":{"post":{"operationId":"list_file_comments","summary":"List the comments of a file with author, text, time, resolved time and parent comment id for replies. Use for \"What comm","description":"List the comments of a file with author, text, time, resolved time and parent comment id for replies. Use for \"What comments are on Figma file abc123XYZ\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"file_key":{"description":"File key: the part after /file/ or /design/ in a Figma file URL, for example 'abc123XYZ'.","maxLength":200,"title":"File Key","type":"string"},"as_md":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":false,"description":"True to get comment text as markdown where applicable.","title":"As Md"}},"required":["file_key"],"title":"list_file_commentsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_file_versions":{"post":{"operationId":"list_file_versions","summary":"List the saved version history of a file with label, description, author and time (page size up to 50). Use for \"What na","description":"List the saved version history of a file with label, description, author and time (page size up to 50). Use for \"What named versions does Figma file abc123XYZ have\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"file_key":{"description":"File key: the part after /file/ or /design/ in a Figma file URL, for example 'abc123XYZ'.","maxLength":200,"title":"File Key","type":"string"},"page_size":{"anyOf":[{"maximum":50,"minimum":1,"type":"integer"},{"type":"null"}],"default":30,"description":"Versions per page (1 to 50, default 30).","title":"Page Size"},"before":{"anyOf":[{"maximum":9999999999999999,"minimum":0,"type":"integer"},{"type":"null"}],"default":null,"description":"A version id: return versions before it (for paging back).","title":"Before"}},"required":["file_key"],"title":"list_file_versionsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_team_folders":{"post":{"operationId":"list_team_folders","summary":"List the top-level folders of a team with id, name and creation time. The team id is the number in a Figma team URL. Use","description":"List the top-level folders of a team with id, name and creation time. The team id is the number in a Figma team URL. Use for \"What folders does Figma team 1234567890 have\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"team_id":{"description":"Team id, the number in the team page URL.","maxLength":200,"title":"Team Id","type":"string"}},"required":["team_id"],"title":"list_team_foldersArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_folder_files":{"post":{"operationId":"list_folder_files","summary":"List the files inside a folder with file key, name, last modified time and thumbnail. Use for \"Which files are in Figma ","description":"List the files inside a folder with file key, name, last modified time and thumbnail. Use for \"Which files are in Figma folder 55555\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"folder_id":{"description":"Folder id returned by list_team_folders.","maxLength":200,"title":"Folder Id","type":"string"}},"required":["folder_id"],"title":"list_folder_filesArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_folder_subfolders":{"post":{"operationId":"list_folder_subfolders","summary":"List the subfolders of a folder with id, name and creation time. Use for \"What subfolders are in Figma folder 55555\".","description":"List the subfolders of a folder with id, name and creation time. Use for \"What subfolders are in Figma folder 55555\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"folder_id":{"description":"Folder id returned by list_team_folders.","maxLength":200,"title":"Folder Id","type":"string"}},"required":["folder_id"],"title":"list_folder_subfoldersArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_file_components":{"post":{"operationId":"list_file_components","summary":"List the published components of a library file (a main file, not a branch) with name, description, node id and update t","description":"List the published components of a library file (a main file, not a branch) with name, description, node id and update time. Use for \"Which components are published from Figma file abc123XYZ\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"file_key":{"description":"File key: the part after /file/ or /design/ in a Figma file URL, for example 'abc123XYZ'.","maxLength":200,"title":"File Key","type":"string"}},"required":["file_key"],"title":"list_file_componentsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_file_styles":{"post":{"operationId":"list_file_styles","summary":"List the published styles of a library file (a main file, not a branch) with type (FILL, TEXT, EFFECT, GRID), name and d","description":"List the published styles of a library file (a main file, not a branch) with type (FILL, TEXT, EFFECT, GRID), name and description. Use for \"Which color and text styles does Figma file abc123XYZ publish\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"file_key":{"description":"File key: the part after /file/ or /design/ in a Figma file URL, for example 'abc123XYZ'.","maxLength":200,"title":"File Key","type":"string"}},"required":["file_key"],"title":"list_file_stylesArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}}}}