Create Map - Plugixa Image Map

POST /plugixa-image-map/v1/maps

Create a map, empty or with its picture and hotspots.

Any signed-in user with the plugixa_image_map_create capability. Administrators have every Plugixa Image Map capability; see Roles and permissions.

Note. The cleaning is lenient on purpose: a hotspot with an unknown type, or a polygon with fewer than 3 points, is dropped and the request still succeeds. Check meta.warnings after every write.

Request

POST https://your-site.example/wp-json/plugixa-image-map/v1/maps

Request body

Content type: application/json

{
  "title": "Ground floor",
  "status": "draft",
  "doc": {
    "image": {
      "attachment_id": 58
    },
    "objects": [
      {
        "type": "spot",
        "name": "Reception",
        "geometry": {
          "x": 42.5,
          "y": 61.25
        },
        "tooltip": {
          "content": "<p>Reception desk, open 8:00 to 18:00.</p>"
        }
      }
    ]
  }
}

The map document

doc is the whole map. Every part of it is optional: what you leave out takes its default, so the example above is a complete request.

Each hotspot in objects:

The document is cleaned the same way the editor’s save is: unknown keys are dropped, numbers are clamped into their range, a value of the wrong kind takes its default, a link with a scheme that is not allowed turns the action into none, and tooltip HTML is filtered. None of that fails the request. Each change is reported in meta.warnings instead. An empty hover, or an empty ext, comes back as [].

Responses

201 Created. data is the new map, document included.

{
  "success": true,
  "data": {
    "id": 12,
    "uid": "9b2f6c1e-4d7a-4f3b-9a51-2c8e7d0f6a13",
    "title": "Ground floor",
    "status": "draft",
    "image_id": 58,
    "doc": {
      "schema": 1,
      "image": {
        "attachment_id": 58,
        "width": 1600,
        "height": 1000,
        "alt": "Ground floor plan"
      },
      "settings": {
        "general": {
          "responsive": true
        },
        "tooltips": {
          "enabled": true,
          "trigger": "hover",
          "sticky": false,
          "constrain": true,
          "animation": "fade"
        },
        "effects": {
          "pageload": "none"
        },
        "zoom": {
          "enabled": false,
          "max": 4.0,
          "buttons": true,
          "wheel": "ctrl",
          "fullscreen": false
        },
        "list": {
          "enabled": false,
          "position": "right",
          "search": true,
          "title": ""
        }
      },
      "objects": [
        {
          "id": "o_3f9a1c2e",
          "type": "spot",
          "name": "Reception",
          "geometry": {
            "x": 42.5,
            "y": 61.25,
            "w": 3.0
          },
          "style": {
            "default": {
              "fill": "#1976d2",
              "fill_opacity": 0.4,
              "stroke": "#ffffff",
              "stroke_opacity": 1.0,
              "stroke_width": 0.0,
              "radius": 4.0,
              "opacity": 1.0,
              "icon": "",
              "icon_color": "#ffffff",
              "shadow": false
            },
            "hover": []
          },
          "action": {
            "type": "none",
            "new_tab": false,
            "url": "",
            "event": ""
          },
          "tooltip": {
            "enabled": true,
            "position": "auto",
            "width": 260,
            "offset_x": 0.0,
            "offset_y": 0.0,
            "content": "<p>Reception desk, open 8:00 to 18:00.</p>"
          },
          "a11y": {
            "label": "",
            "description": ""
          },
          "visible": true,
          "locked": false,
          "group": "",
          "ext": []
        }
      ],
      "groups": [],
      "ext": []
    },
    "doc_version": 1,
    "trusted_html": true,
    "object_count": 1,
    "rev": 1,
    "created_by": 1,
    "modified_by": 1,
    "created_at": "2026-11-12 09:30:00",
    "modified_at": "2026-11-12 09:30:00",
    "deleted_at": null,
    "doc_error": false,
    "image_url": "https://your-site.example/wp-content/uploads/2026/11/ground-floor.png",
    "shortcode": "[plugixa_image_map id=\"12\"]",
    "thumbnail_url": "https://your-site.example/wp-content/uploads/2026/11/ground-floor-150x150.png"
  },
  "meta": {
    "warnings": [
      {
        "path": "objects.0.id",
        "code": "id_replaced"
      }
    ]
  }
}

The example hotspot was sent without an id, so it was given one and the change is reported.

Errors

Plus the errors every endpoint can return.

Examples

curl -s -X POST "https://your-site.example/wp-json/plugixa-image-map/v1/maps" \
  -u "admin:$WP_APP_PASSWORD" \
  -H "Content-Type: application/json" \
  -d '{"title":"Ground floor","status":"draft","doc":{"image":{"attachment_id":58},"objects":[{"type":"spot","name":"Reception","geometry":{"x":42.5,"y":61.25},"tooltip":{"content":"<p>Reception desk, open 8:00 to 18:00.</p>"}}]}}'

<?php
$ch = curl_init('https://your-site.example/wp-json/plugixa-image-map/v1/maps');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST  => 'POST',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_USERPWD        => 'admin:' . getenv('WP_APP_PASSWORD'),
    CURLOPT_HTTPHEADER     => ['Content-Type: application/json'],
    CURLOPT_POSTFIELDS     => json_encode([
        'title'  => 'Ground floor',
        'status' => 'draft',
        'doc'    => [
            'image'   => [
                'attachment_id' => 58,
            ],
            'objects' => [
                [
                    'type'     => 'spot',
                    'name'     => 'Reception',
                    'geometry' => [
                        'x' => 42.5,
                        'y' => 61.25,
                    ],
                    'tooltip'  => [
                        'content' => '<p>Reception desk, open 8:00 to 18:00.</p>',
                    ],
                ],
            ],
        ],
    ]),
]);
$response = json_decode(curl_exec($ch), true);
curl_close($ch);

const response = await fetch('https://your-site.example/wp-json/plugixa-image-map/v1/maps', {
  method: 'POST',
  headers: {
    'Authorization': 'Basic ' + btoa(`admin:${process.env.WP_APP_PASSWORD}`),
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    title: 'Ground floor',
    status: 'draft',
    doc: {
      image: {
        attachment_id: 58,
      },
      objects: [
        {
          type: 'spot',
          name: 'Reception',
          geometry: {
            x: 42.5,
            y: 61.25,
          },
          tooltip: {
            content: '<p>Reception desk, open 8:00 to 18:00.</p>',
          },
        },
      ],
    },
  }),
});
const { data } = await response.json();