WordBlocks API Free

Complete reference for public WordBlocks REST endpoints, authentication expectations, request schemas, and response examples.

View API endpoints Back to all features

API overview

Namespace and endpoint map

Global capability: Every WordBlocks block can be locked in the editor to protect layouts and can be globally styled from WordBlocks Basic Styling for consistent typography, spacing, and color across pages.

The WordBlocks plugin currently exposes four API routes across three endpoint groups. Use the route matrix first, then follow the detailed endpoint sections below.

Endpoint	Purpose	Auth
POST /wp-json/wordblocks/v1/serialize_blocks	Compile semantic block payloads into Gutenberg-compatible serialized block markup.	Public (permission callback allows unauthenticated access)
GET /wp-json/wp/v2/block-types/wordblocks	Discover registered WordBlocks block metadata, attributes, and supports.	Core endpoint permissions apply
GET /wp-json/wordblocks/v1/upload-mime-types	Read current optional upload MIME settings and supported MIME keys.	Requires manage_options capability
POST\|PUT\|PATCH /wp-json/wordblocks/v1/upload-mime-types	Update optional upload MIME settings; partial payloads are merged with saved values.	Requires manage_options capability

Base namespace

https://your-site.com/wp-json/wordblocks/v1

Content type

application/json

Endpoint: Serialize Blocks

Back to API top

Field	Value
Route	POST /wp-json/wordblocks/v1/serialize_blocks
Permission	Public endpoint (permission callback is __return_true)
Accepted payload	Either { “blocks”: […] } or a top-level block array […]
Notable behavior	Incoming styleId values are ignored for wordblocks/* blocks and regenerated server-side.

Request payload

{
  "blocks": [
    {
      "blockName": "wordblocks/heading",
      "attrs": {
        "level": 2,
        "content": "Imported API Heading",
        "textAlign": "left",
        "fontWeight": "700"
      }
    },
    {
      "blockName": "wordblocks/paragraph",
      "attrs": {
        "content": "This paragraph was imported via the WordBlocks API.",
        "fontSize": "1rem",
        "lineHeight": "1.6"
      }
    },
    {
      "blockName": "wordblocks/list",
      "attrs": {
        "listType": "ul",
        "iconType": "check",
        "items": [
          "First imported item",
          "Second imported item",
          "Third imported item"
        ]
      }
    }
  ]
}

Success response

{
  "serialized": "...serialized block markup...",
  "blockCount": 3
}

Error responses

invalid_blocks_payload (400)
invalid_block (400)
missing_block_name (400)
unsupported_wordblocks_block (400)

cURL example

curl -X POST "https://your-site.com/wp-json/wordblocks/v1/serialize_blocks" \
  -H "Content-Type: application/json" \
  --data '{"blocks":[{"blockName":"wordblocks/paragraph","attrs":{"content":"Imported paragraph from external API"}}]}'

Endpoint: Block Types Metadata

Back to API top

Field	Value
Route	GET /wp-json/wp/v2/block-types/wordblocks
Permission	WordPress core endpoint permissions apply
Primary use	Discover block attributes/supports before constructing import payloads.

Success response (sample item)

[
  {
    "name": "wordblocks/paragraph",
    "api_version": 3,
    "title": "Paragraph",
    "category": "wordblocks",
    "attributes": {
      "content": { "type": "rich-text" },
      "styleId": { "type": "string" }
    },
    "supports": {
      "anchor": true,
      "className": true
    }
  }
]

cURL example

curl "https://your-site.com/wp-json/wp/v2/block-types/wordblocks"

Endpoint: Upload MIME Types

Back to API top

Field	Value
Route	/wp-json/wordblocks/v1/upload-mime-types
Methods	GET, POST, PUT, PATCH
Permission	Requires manage_options
Primary use	Read and automate optional upload MIME toggle settings.

GET success response

{
  "enabled": true,
  "mimes": {
    "svg": true,
    "pdf": true,
    "docx": false
  },
  "supported": {
    "svg": {
      "label": "SVG (.svg)",
      "description": "Scalable vector graphics. Only enable if you trust uploaded files.",
      "ext": "svg",
      "mime": "image/svg+xml"
    }
  }
}

Update request payload

{
  "enabled": true,
  "mimes": {
    "svg": true,
    "pdf": true,
    "docx": false
  }
}

Update success response

{
  "saved": true,
  "settings": {
    "enabled": true,
    "mimes": {
      "svg": true,
      "pdf": true,
      "docx": false
    }
  }
}

Error responses

rest_forbidden (401/403)
invalid_upload_mime_types_payload (400)
invalid_upload_mime_types_mimes (400)

cURL example (GET)

curl "https://your-site.com/wp-json/wordblocks/v1/upload-mime-types" \
  -H "X-WP-Nonce: YOUR_NONCE" \
  -H "Cookie: wordpress_logged_in=..."

cURL example (Update)

curl -X POST "https://your-site.com/wp-json/wordblocks/v1/upload-mime-types" \
  -H "Content-Type: application/json" \
  -H "X-WP-Nonce: YOUR_NONCE" \
  -H "Cookie: wordpress_logged_in=..." \
  --data '{"enabled":true,"mimes":{"svg":true,"pdf":true}}'

Recommended workflow

Back to API top

Step	Guidance
1	Call block-types metadata first to validate attribute names and schema.
2	Build semantic payloads without styleId and submit them to serialize_blocks.
3	Store the serialized response directly as post_content.
4	For MIME automation, read upload-mime-types then send partial update payloads with only changed keys.
5	Use nonce/cookie auth for wp-admin contexts or another authenticated REST method when required by site policy.

Need block control documentation too?

Use the controls reference template for per-block inspector options and landing page links.

Open block controls docs View all blocks