REST API

The plugin registers all routes under /wp-json/agent-bricks/v1/. Every request must include the X-ATB-Key header (see Authentication).

Rate limiting currently applies to repeated failed authentication attempts. A site-wide per-key request limit is not currently enforced across all endpoints.

Site

GET /site/info

Returns Bricks version, WordPress version, PHP version, plugin version, registered element types, and breakpoints.

curl -s https://your-site.com/wp-json/agent-bricks/v1/site/info \
  -H "X-ATB-Key: atb_abc123..."

{
  "bricksVersion": "1.11.1",
  "contentMetaKey": "_bricks_page_content_2",
  "elementTypes": ["section", "container", "heading", "text-basic", "image", "button"],
  "breakpoints": { "desktop": 1280, "tablet": 1024, "mobile": 768 },
  "pluginVersion": "1.2.0",
  "phpVersion": "8.2.27",
  "wpVersion": "6.7.2"
}

GET /site/frameworks

Detects CSS frameworks installed on the site. Returns ACSS tokens, color palette, spacing scale, and typography settings when Automatic.css is active.

curl -s https://your-site.com/wp-json/agent-bricks/v1/site/frameworks \
  -H "X-ATB-Key: atb_abc123..."

{
  "frameworks": {
    "acss": {
      "name": "Automatic.css",
      "active": true,
      "version": "3.0",
      "classCount": 247,
      "colors": {
        "primary": "#2563eb",
        "secondary": "#7c3aed",
        "accent": "#f59e0b"
      },
      "spacing": {
        "scale": "1.5",
        "sectionPadding": "var(--section-space-m)"
      },
      "typography": {
        "rootFontSize": "62.5%",
        "textFontFamily": "Inter, sans-serif",
        "headingFontFamily": "Poppins, sans-serif"
      }
    }
  }
}

GET /site/element-types

Returns all registered Bricks element types with labels, categories, and icons.

Query parameters:

Param	Type	Description
`include_controls`	boolean	Include control definitions for each element type
`category`	string	Filter by category (e.g., `general`, `media`, `layout`)

curl -s "https://your-site.com/wp-json/agent-bricks/v1/site/element-types?category=general" \
  -H "X-ATB-Key: atb_abc123..."

{
  "elementTypes": [
    { "name": "heading", "label": "Heading", "category": "general", "icon": "ti-text" },
    { "name": "text-basic", "label": "Basic Text", "category": "general", "icon": "ti-align-left" }
  ],
  "count": 2
}

GET /site/features

Returns a machine-readable summary of the site’s Bricks, framework, query, Abilities, and WooCommerce capabilities.

curl -s https://your-site.com/wp-json/agent-bricks/v1/site/features \
  -H "X-ATB-Key: atb_abc123..."

{
  "bricks": { "active": true, "version": "1.12.2" },
  "wordpress": { "version": "6.9" },
  "plugin": { "version": "2.1.0" },
  "abilities": { "available": true },
  "frameworks": ["acss", "frames"],
  "queryElements": ["accordion", "carousel", "posts"],
  "queryElementCount": 3,
  "woocommerce": {
    "active": true,
    "version": "9.8.1",
    "productPostType": true,
    "elementTypeCount": 2
  }
}

GET /site/query-elements

Returns only the Bricks element types that expose a query control.

Query parameters:

Param	Type	Description
`include_controls`	boolean	Include control definitions for each query-capable element type

curl -s "https://your-site.com/wp-json/agent-bricks/v1/site/query-elements?include_controls=1" \
  -H "X-ATB-Key: atb_abc123..."

GET /site/woocommerce

Returns WooCommerce availability, taxonomy support, HPOS status, and any Woo-specific Bricks element types exposed by the current Bricks install.

curl -s https://your-site.com/wp-json/agent-bricks/v1/site/woocommerce \
  -H "X-ATB-Key: atb_abc123..."

GET /pages

Lists pages on the site. Useful for browsing available pages before pulling or pushing elements.

Query parameters:

Param	Type	Description
`search`	string	Search pages by title
`per_page`	integer	Results per page (default 20, max 50)

curl -s "https://your-site.com/wp-json/agent-bricks/v1/pages?search=home" \
  -H "X-ATB-Key: atb_abc123..."

[
  { "id": 42, "title": "Homepage", "slug": "homepage", "status": "publish", "modified": "2026-02-25T14:30:00" },
  { "id": 78, "title": "Home v2", "slug": "home-v2", "status": "draft", "modified": "2026-02-20T10:15:00" }
]

Convert

POST /convert

Convert raw HTML (and optional CSS) to Bricks elements. Optionally push the result directly to a page. This is the server-side equivalent of bricks convert html.

Parameters:

Parameter	Type	Required	Description
`html`	string	Yes	Raw HTML to convert
`css`	string	No	Optional CSS string (reserved for future use)
`postId`	integer	No	Target page ID (required if mode is not `return`)
`mode`	string	No	`return` (default), `append`, or `replace`
`createGlobalClasses`	boolean	No	Create global classes from CSS class names (default: false)

curl -s -X POST https://your-site.com/wp-json/agent-bricks/v1/convert \
  -H "X-ATB-Key: atb_abc123..." \
  -H "Content-Type: application/json" \
  -d '{
    "html": "<section style=\"padding: var(--section-space-m)\"><div><h2>Hello</h2><p>World</p></div></section>"
  }'

{
  "success": true,
  "elements": [
    {
      "id": "a1b2c3",
      "name": "section",
      "parent": "0",
      "children": ["d4e5f6"],
      "settings": {
        "_padding": { "top": "var(--section-space-m)", "right": "var(--section-space-m)", "bottom": "var(--section-space-m)", "left": "var(--section-space-m)" }
      },
      "label": "Section"
    }
  ],
  "stats": {
    "htmlTags": 4,
    "bricksElements": 4,
    "skippedTags": 0,
    "stylesExtracted": 0
  },
  "warnings": []
}

Convert and push to a page:

curl -s -X POST https://your-site.com/wp-json/agent-bricks/v1/convert \
  -H "X-ATB-Key: atb_abc123..." \
  -H "Content-Type: application/json" \
  -d '{
    "html": "<section><h1>New Page</h1></section>",
    "postId": 1338,
    "mode": "replace"
  }'

When mode is replace, a snapshot is automatically created before overwriting. The response includes stats.pushed, stats.postId, stats.mode, and stats.contentHash.

Conversion features:

HTML tags mapped to native Bricks elements (section, heading, text-basic, button, image, etc.)
Inline styles parsed to Bricks settings (_padding, _typography, _background, etc.)
CSS shorthand expanded (e.g., padding: 10px 20px → top/right/bottom/left)
CSS class names resolved against the Bricks global class registry
CSS variables (var(--primary)) preserved as-is in Bricks settings
data-* attributes preserved as custom attributes

Pages / Elements

All element endpoints use optimistic locking. Write operations require an If-Match header containing the contentHash from your last GET. If someone else modified the page in between, you’ll get a 409 Conflict with the current hash so you can retry.

GET /pages/{id}/elements

Fetches all elements on a page.

curl -s https://your-site.com/wp-json/agent-bricks/v1/pages/42/elements \
  -H "X-ATB-Key: atb_abc123..."

{
  "elements": [
    {
      "id": "abc123",
      "name": "section",
      "parent": 0,
      "children": ["def456"],
      "settings": {
        "_cssGlobalClasses": ["acss_import_section-l"],
        "tag": "section"
      }
    }
  ],
  "contentHash": "e3b0c44298fc1c14...",
  "count": 12,
  "metaKey": "_bricks_page_content_2"
}

POST /pages/{id}/elements

Appends elements to a page. Optionally specify a parent or insertion point.

Headers: If-Match: <contentHash>

Body:

{
  "elements": [
    {
      "id": "new001",
      "name": "heading",
      "parent": "abc123",
      "children": [],
      "settings": { "tag": "h2", "text": "Hello world" }
    }
  ],
  "parentId": "abc123",
  "insertAfter": "def456"
}

curl -X POST https://your-site.com/wp-json/agent-bricks/v1/pages/42/elements \
  -H "X-ATB-Key: atb_abc123..." \
  -H "If-Match: e3b0c44298fc1c14..." \
  -H "Content-Type: application/json" \
  -d '{"elements": [{"id":"new001","name":"heading","parent":"abc123","children":[],"settings":{"tag":"h2","text":"Hello world"}}]}'

Response (201):

{
  "success": true,
  "contentHash": "a1b2c3d4e5f6...",
  "added": ["new001"],
  "count": 13
}

PUT /pages/{id}/elements

Full replacement of all page elements. The plugin auto-creates a snapshot before overwriting.

Headers: If-Match: <contentHash>

curl -X PUT https://your-site.com/wp-json/agent-bricks/v1/pages/42/elements \
  -H "X-ATB-Key: atb_abc123..." \
  -H "If-Match: e3b0c44298fc1c14..." \
  -H "Content-Type: application/json" \
  -d '{"elements": [...]}'

{
  "success": true,
  "contentHash": "f6e5d4c3b2a1...",
  "count": 8
}

PATCH /pages/{id}/elements

Delta-patch individual elements by ID. Settings are merged (not replaced). Set a key to null to remove it.

Headers: If-Match: <contentHash>

Body:

{
  "patches": [
    {
      "id": "abc123",
      "settings": {
        "text": "Updated heading text",
        "_margin": null
      }
    }
  ]
}

{
  "success": true,
  "contentHash": "d4e5f6a1b2c3...",
  "patched": ["abc123"],
  "count": 1
}

DELETE /pages/{id}/elements

Removes elements by ID. Also cleans up references in parent children arrays.

Headers: If-Match: <contentHash>

curl -X DELETE https://your-site.com/wp-json/agent-bricks/v1/pages/42/elements \
  -H "X-ATB-Key: atb_abc123..." \
  -H "If-Match: e3b0c44298fc1c14..." \
  -H "Content-Type: application/json" \
  -d '{"ids": ["abc123", "def456"]}'

{
  "success": true,
  "contentHash": "b2c3d4e5f6a1...",
  "deleted": ["abc123", "def456"],
  "count": 10
}

POST /pages/{id}/elements/batch

Execute multiple operations in a single atomic write. All operations apply to the same element array in sequence, then the result is saved once.

Headers: If-Match: <contentHash>

Supported operations: append, patch, delete.

{
  "operations": [
    {
      "op": "delete",
      "ids": ["old001"]
    },
    {
      "op": "append",
      "elements": [
        { "id": "new001", "name": "heading", "parent": "abc123", "children": [], "settings": { "tag": "h2", "text": "New section" } }
      ]
    },
    {
      "op": "patch",
      "patches": [
        { "id": "abc123", "settings": { "text": "Updated text" } }
      ]
    }
  ]
}

{
  "success": true,
  "contentHash": "c3d4e5f6a1b2...",
  "operations": [
    { "op": "delete", "deleted": 1 },
    { "op": "append", "added": 1 },
    { "op": "patch", "patched": 1 }
  ],
  "count": 12
}

Snapshots

GET /pages/{id}/snapshots

Lists all snapshots for a page (up to 10, FIFO). Does not include element data in the listing.

curl -s https://your-site.com/wp-json/agent-bricks/v1/pages/42/snapshots \
  -H "X-ATB-Key: atb_abc123..."

{
  "snapshots": [
    {
      "snapshotId": "snap_a1b2c3d4e5f6",
      "contentHash": "e3b0c44298fc1c14...",
      "elementCount": 12,
      "timestamp": "2026-02-25 14:30:00",
      "label": "Before hero redesign"
    }
  ]
}

POST /pages/{id}/snapshots

Creates a snapshot of the page’s current state.

curl -X POST https://your-site.com/wp-json/agent-bricks/v1/pages/42/snapshots \
  -H "X-ATB-Key: atb_abc123..." \
  -H "Content-Type: application/json" \
  -d '{"label": "Before hero redesign"}'

{
  "snapshotId": "snap_a1b2c3d4e5f6",
  "contentHash": "e3b0c44298fc1c14...",
  "elementCount": 12,
  "timestamp": "2026-02-25 14:30:00"
}

POST /pages/{id}/snapshots/{snapshot_id}/rollback

Restores a page to a previous snapshot. Auto-creates a new snapshot of the current state before restoring, so you can always undo a rollback.

curl -X POST https://your-site.com/wp-json/agent-bricks/v1/pages/42/snapshots/snap_a1b2c3d4e5f6/rollback \
  -H "X-ATB-Key: atb_abc123..."

{
  "contentHash": "f6e5d4c3b2a1...",
  "count": 12,
  "restoredFrom": "snap_a1b2c3d4e5f6"
}

Global classes

GET /classes

Lists all global CSS classes. Optionally filter by framework.

Query parameters:

Param	Type	Description
`framework`	string	Filter by `acss` or `custom`

curl -s "https://your-site.com/wp-json/agent-bricks/v1/classes?framework=acss" \
  -H "X-ATB-Key: atb_abc123..."

{
  "classes": [
    {
      "id": "acss_import_section-l",
      "name": "section--l",
      "settings": {},
      "framework": "acss"
    }
  ],
  "count": 147,
  "total": 312
}

POST /classes

Creates a new global class. Returns 409 if the name already exists.

curl -X POST https://your-site.com/wp-json/agent-bricks/v1/classes \
  -H "X-ATB-Key: atb_abc123..." \
  -H "Content-Type: application/json" \
  -d '{"name": "card--featured", "label": "Featured card", "settings": {"_background": {"color": "var(--primary)"}}}'

GET /classes/{id}

Returns a single class by ID.

PATCH /classes/{id}

Updates a class. ACSS-imported classes cannot be modified (returns 403).

DELETE /classes/{id}

Deletes a class. ACSS-imported classes cannot be deleted (returns 403).

Templates

GET /templates

Lists all Bricks templates.

Query parameters:

Param	Type	Description
`type`	string	Filter by template type: `header`, `footer`, `section`, `content`, `archive`

curl -s "https://your-site.com/wp-json/agent-bricks/v1/templates?type=section" \
  -H "X-ATB-Key: atb_abc123..."

{
  "templates": [
    {
      "id": 105,
      "title": "Hero - Centered",
      "type": "section",
      "status": "publish",
      "elementCount": 8,
      "modified": "2026-02-20 09:15:00"
    }
  ],
  "count": 3
}

POST /templates

Creates a new Bricks template from element JSON.

{
  "title": "CTA - Two Column",
  "type": "section",
  "elements": [...],
  "status": "publish"
}

GET /templates/{id}

Returns a template with its full element content and content hash.

PATCH /templates/{id}

Updates a template’s title, type, elements, or settings.

DELETE /templates/{id}

Permanently deletes a template.

Components

Components are section-type templates. The /components endpoints give a filtered view of templates where _bricks_template_type is section.

GET /components

Lists all section components.

GET /components/{id}

Returns a component with its elements and content hash. Returns 404 if the template exists but is not a section type.

Search

GET /search/elements

Searches elements across all pages, posts, and templates on the site.

Query parameters:

Param	Type	Description
`element_type`	string	Filter by element type (e.g., `heading`, `image`)
`setting_key`	string	Filter by settings key presence
`setting_value`	string	Filter by settings value (case-insensitive substring match)
`global_class`	string	Filter by global class name or ID
`post_type`	string	Filter by post type (`page`, `post`, `bricks_template`)
`has_query`	boolean	Only return elements that expose Bricks query data
`query_object_type`	string	Filter by Bricks query object type
`query_post_type`	string	Filter by queried post type
`query_taxonomy`	string	Filter by queried taxonomy
`per_page`	integer	Results per page (max 100, default 50)
`page`	integer	Page number (default 1)

curl -s "https://your-site.com/wp-json/agent-bricks/v1/search/elements?element_type=heading&setting_value=pricing" \
  -H "X-ATB-Key: atb_abc123..."

{
  "results": [
    {
      "postId": 42,
      "postTitle": "Pricing Page",
      "postType": "page",
      "elementId": "abc123",
      "elementType": "heading",
      "elementLabel": "",
      "settings": { "tag": "h2", "text": "Simple pricing for everyone" },
      "parentId": "xyz789",
      "hasQuery": false,
      "queryObjectType": "",
      "queryPostTypes": [],
      "queryTaxonomies": [],
      "queryRaw": {}
    }
  ],
  "total": 3,
  "page": 1,
  "perPage": 50,
  "totalPages": 1
}

WooCommerce

GET /woo/products

Lists WooCommerce products for discovery, autocomplete, and query-building flows.

Query parameters:

Param	Type	Description
`search`	string	Search products by title
`per_page`	integer	Results per page (default 20, max 50)
`page`	integer	Page number (default 1)

GET /woo/product-categories

Lists WooCommerce product categories.

Query parameters:

Param	Type	Description
`search`	string	Search categories by name
`per_page`	integer	Results per page (default 20, max 50)

GET /woo/product-tags

Lists WooCommerce product tags.

Query parameters:

Param	Type	Description
`search`	string	Search tags by name
`per_page`	integer	Results per page (default 20, max 50)

Media

GET /media

Lists media library items. Most recent first, 50 per request.

Query parameters:

Param	Type	Description
`search`	string	Search by filename or title

curl -s "https://your-site.com/wp-json/agent-bricks/v1/media?search=hero" \
  -H "X-ATB-Key: atb_abc123..."

{
  "media": [
    {
      "id": 201,
      "title": "hero-background",
      "url": "https://your-site.com/wp-content/uploads/2026/02/hero-background.webp",
      "mimeType": "image/webp",
      "date": "2026-02-15 10:00:00",
      "filesize": 142580
    }
  ],
  "count": 1
}

POST /media/upload

Uploads a file to the WordPress media library. Send as multipart form data with a file field.

curl -X POST https://your-site.com/wp-json/agent-bricks/v1/media/upload \
  -H "X-ATB-Key: atb_abc123..." \
  -F "file=@hero-image.webp"

{
  "id": 202,
  "url": "https://your-site.com/wp-content/uploads/2026/02/hero-image.webp",
  "mimeType": "image/webp",
  "filename": "hero-image.webp",
  "filesize": 98432
}

Styles

GET /styles

Returns Bricks theme styles, color palette, and global settings.

curl -s https://your-site.com/wp-json/agent-bricks/v1/styles \
  -H "X-ATB-Key: atb_abc123..."

{
  "themeStyles": [
    {
      "key": "default",
      "label": "Default",
      "settings": {
        "typography": { "font-family": "Inter, sans-serif" },
        "colors": { "heading": "#1a1a2e", "text": "#4a4a68" }
      }
    }
  ],
  "colorPalette": [
    { "id": "cp1", "color": { "hex": "#2563eb" }, "name": "Primary" }
  ],
  "globalSettings": {}
}

GET /variables

Returns CSS custom properties defined in Bricks, plus any variables extracted from theme style custom CSS blocks.

curl -s https://your-site.com/wp-json/agent-bricks/v1/variables \
  -H "X-ATB-Key: atb_abc123..."

{
  "variables": [],
  "extractedFromCSS": [
    { "name": "--card-radius", "value": "8px", "source": "default" },
    { "name": "--section-max-width", "value": "1200px", "source": "default" }
  ]
}

Error responses

All errors follow the same shape:

{
  "error": "Human-readable error message.",
  "code": "optional_error_code"
}

Common status codes:

Code	Meaning
400	Bad request (missing fields, invalid data)
401	Invalid or missing API key
403	Forbidden (e.g., trying to modify an ACSS class)
404	Resource not found
409	Conflict (contentHash mismatch; someone else wrote first)
428	If-Match header required but missing
429	Too many failed authentication attempts