API Reference

API Reference

Figma API Integration

The plugin interacts with the Figma REST API v1.

Authentication

All requests use a Personal Access Token (PAT) sent via the X-Figma-Token header. The token is encrypted at rest using AES-256-CBC.

Endpoints Used

Endpoint	Method	Purpose	Cache Key
GET /v1/files/{key}	GET	Fetch file document + metadata	hello_figma_file_{key}
GET /v1/files/{key}/nodes?ids={ids}	GET	Fetch specific nodes	hello_figma_nodes_{key}_{md5}
GET /v1/files/{key}/styles	GET	Fetch local styles	hello_figma_styles_{key}
GET /v1/images/{key}?ids={ids}	GET	Get image URLs	hello_figma_images_{key}_{md5}
GET /v1/files/{key}/variables/local	GET	Fetch local variables	hello_figma_variables_{key}
POST /v1/images/{key}	POST	Get images (POST variant)	—
GET /v1/teams/{id}/styles	GET	Fetch team styles	hello_figma_team_styles_{team}

Rate Limiting

The plugin enforces Figma's rate limit (2 requests/second) with:

• Internal 0.5s minimum delay between requests (tracked via transient)
• Respect for X-RateLimit-Remaining headers (slows down when ≤2 remaining)
• Automatic retry on 429: up to 3 attempts, delay based on Retry-After header (or 5s default)
• Configurable timeout: filter hello_figma_api_timeout (default 120 seconds)

PHP Filters & Hooks

hello_figma_cache_ttl

Customize cache duration per context.

add_filter('hello_figma_cache_ttl', function(int $ttl, string $context): int {
    switch ($context) {
        case 'file':     return HOUR_IN_SECONDS;     // File data
        case 'nodes':    return HOUR_IN_SECONDS;     // Node data
        case 'styles':   return 6 * HOUR_IN_SECONDS; // Style data
        case 'images':   return 30 * MINUTE_IN_SECONDS; // Image URLs
        case 'variables': return DAY_IN_SECONDS;     // Variables
        case 'thumbnail': return DAY_IN_SECONDS;     // Thumbnails
        default:         return $ttl;
    }
}, 10, 2);

hello_figma_api_timeout

Customize API request timeout.

add_filter('hello_figma_api_timeout', function(): int {
    return 180; // 3 minutes (default is 120)
});

hello_figma_api_error

Action triggered on Figma API errors.

add_action('hello_figma_api_error', function(string $error_message, string $endpoint): void {
    // Custom error handling
    error_log("Figma API error on $endpoint: $error_message");
}, 10, 2);

JavaScript API

The admin UI exposes several global functions and AJAX endpoints.

AJAX Endpoints

All endpoints require the hello_figma_nonce nonce and manage_options capability.

Endpoint	Method	Action	Purpose
wp_ajax_hello_figma_convert	POST	hello_figma_convert	Import frame as template
wp_ajax_hello_figma_delete_template	POST	hello_figma_delete_template	Delete template
wp_ajax_hello_figma_export_template	POST	hello_figma_export_template	Export template as JSON
wp_ajax_hello_figma_fetch_preview	POST	hello_figma_fetch_preview	Get preview images
wp_ajax_hello_figma_sync_styles	POST	hello_figma_sync_styles	Sync styles
wp_ajax_hello_figma_fetch_structure	POST	hello_figma_fetch_structure	Get file structure
wp_ajax_hello_figma_fetch_frame_images	POST	hello_figma_fetch_frame_images	Get frame images
wp_ajax_hello_figma_preview_sections	POST	hello_figma_preview_sections	Preview sections
wp_ajax_hello_figma_import_progress	POST	hello_figma_import_progress	Poll import progress

Import Progress API

Used by the frontend to poll import progress:

Request:

$.post(ajaxurl, {
    action: 'hello_figma_import_progress',
    run_id: runId,
    nonce: helloFigmaNonce
});

Response:

{
    "success": true,
    "data": {
        "stage": "Downloading images from Figma...",
        "percentage": 40,
        "current": 5,
        "total": 15
    }
}

Elementor Data Structure

The plugin produces Elementor-compatible JSON that follows the standard Elementor data format:

{
    "version": "0.4",
    "title": "My Imported Design",
    "type": "page",
    "content": [
        {
            "id": "abc1234",
            "elType": "container",
            "settings": {
                "flex_direction": "column",
                "justify_content": "flex-start",
                "align_items": "stretch",
                "gap": { "unit": "px", "size": 10 },
                "padding": { "unit": "px", "top": 20, "right": 20, "bottom": 20, "left": 20, "isLinked": true }
            },
            "elements": [
                {
                    "id": "def5678",
                    "elType": "widget",
                    "widgetType": "heading",
                    "settings": {
                        "title": "Hello World",
                        "header_size": "h1",
                        "typography_font_family": "Inter",
                        "typography_font_size": { "unit": "px", "size": 32 }
                    }
                }
            ]
        }
    ],
    "page_settings": []
}

PHP Classes (Quick Reference)

Class	Namespace	Purpose
Plugin	HelloFigma\	Singleton, service container
Figma_API	HelloFigma\	REST client, rate limiting, caching
Elementor_Renderer	HelloFigma\	Figma → Elementor conversion
Admin	HelloFigma\	Admin UI, AJAX handlers
Template_Manager	HelloFigma\	Template CRUD
Image_Handler	HelloFigma\	Image download + media library
Style_Sync	HelloFigma\	Style synchronization
Logger	HelloFigma\	Debug logging
Compatibility	HelloFigma\	Dependency checks
Asset_Manager	HelloFigma\	CSS/JS enqueuing
Figma_Container	HelloFigma\Widgets\	Container widget
Figma_Button	HelloFigma\Widgets\	Button widget
Figma_Image	HelloFigma\Widgets\	Image widget
Figma_Heading	HelloFigma\Widgets\	Heading widget
Figma_Icon_Box	HelloFigma\Widgets\	Icon box widget
Figma_Section	HelloFigma\Widgets\	Section widget
Figma_Field	HelloFigma\DynamicTags\	Field dynamic tag
Figma_Text	HelloFigma\DynamicTags\	Text dynamic tag