api-reference.mdx

title	description
API Reference	Complete REST API reference for Respira for WordPress, including v1 and v2 endpoints for pages, posts, builders, snapshots, and more.

Overview

Respira for WordPress exposes a comprehensive REST API for managing your WordPress site with duplicate-first safety, builder-aware updates, and fidelity workflows.

This REST API underpins multiple Respira surfaces:

• the standalone Respira MCP server
• the official WordPress Abilities + MCP Adapter integration
• built-in Browser AI/WebMCP
• the curated Elementor Angie bridge

Base URLs

Respira currently exposes two namespaces:

https://your-site.com/wp-json/respira/v1/
https://your-site.com/wp-json/respira/v2/

• v1: broad compatibility endpoints used across older and mixed environments
• v2: capability negotiation, fidelity/snapshot flows, and builder patch operations

Browser-auth Angie endpoints use a separate namespace:

https://your-site.com/wp-json/respira/browser/v1/

See Elementor Angie for the browser-auth flow, and WordPress AI Stack Compatibility for the official Abilities/MCP Adapter path.

Capability status endpoint (v2)

Use this endpoint to detect v2 feature support:

GET /wp-json/respira/v2/status

Authentication

Include your API key with every request:

X-Respira-API-Key: respira_your-api-key-here

Site Context

Get site context

Returns comprehensive information about the WordPress site including version, theme, plugins, and detected page builders.

GET /context/site-info

Get theme docs

Returns theme documentation and available template files.

GET /context/theme-docs

Get builder info

Returns information about the active page builder including available modules/widgets.

GET /context/builder-info

Snapshots and fidelity (v2)

Snapshot endpoints support safer compare/restore flows:

GET /snapshots
GET /snapshots/{uuid}
POST /snapshots/diff
POST /snapshots/restore

Builder patch endpoint:

POST /builder/{builder}/patch/{post_id}

Pages

List pages

List all pages with optional filtering.

GET /pages

Query parameters:

• status - Filter by status (publish, draft, pending)
• search - Search term
• page - Page number for pagination
• perPage - Items per page

Read page

Get full content of a specific page including meta data and builder information.

GET /pages/{id}

Create page duplicate

Create a duplicate of an existing page for safe editing.

POST /pages/{id}/duplicate

Always use this before making changes to an original page. Edit the duplicate, then approve in WordPress admin (Respira → Approve Edits).

Update page

Update a page. Respira automatically creates a duplicate for safety.

PUT /pages/{id}

Body parameters:

• title - New page title
• content - New page content (HTML)
• status - Page status (publish, draft, pending)
• meta - Post meta data

Delete page

Delete a page. Only works on Respira-created duplicates by default.

DELETE /pages/{id}

Posts

List posts

List all blog posts with optional filtering.

GET /posts

Read post

Get full content of a specific post.

GET /posts/{id}

Create post duplicate

Create a duplicate of an existing post for safe editing.

POST /posts/{id}/duplicate

Update post

Update a post. Respira automatically creates a duplicate for safety.

PUT /posts/{id}

Delete post

Delete a post. Only works on Respira-created duplicates by default.

DELETE /posts/{id}

Custom Post Types

List post types

List all registered post types.

GET /post-types

Get post type

Get post type details.

GET /post-types/{type}

List custom posts

List posts of a custom post type.

GET /post-types/{type}/posts

Get custom post

Get custom post details.

GET /post-types/{type}/posts/{id}

Create custom post

Create a new custom post.

POST /post-types/{type}/posts

Update custom post

Update a custom post.

PUT /post-types/{type}/posts/{id}

Delete custom post

Delete a custom post.

DELETE /post-types/{type}/posts/{id}

Page Builder Tools

Extract builder content

Extract structured content from a page builder (Divi, Elementor, Bricks, etc.).

GET /builder/{builder}/pages/{id}/content

Inject builder content

Inject structured content into a page builder.

POST /builder/{builder}/pages/{id}/content

Update module

Update a specific module within a page builder page. Supports finding modules by admin_label, path, or type.

PUT /builder/{builder}/pages/{id}/module

Body parameters:

• moduleIdentifier - Object with admin_label, path, or type
• updates - Object with content and/or attributes

Media

List media

List all media files (images, videos, etc.).

GET /media

Get media

Get single media item details.

GET /media/{id}

Upload media

Upload a media file to WordPress.

POST /media

Body parameters:

• file - File content as base64 string, URL, or file path
• filename - Filename for the uploaded file
• mimeType - MIME type (e.g., image/jpeg)
• alt - Alt text for images
• title - Media title
• caption - Media caption

Update media

Update media metadata (title, alt text, caption).

PUT /media/{id}

Delete media

Delete a media file.

DELETE /media/{id}

Menus

List menus

List all navigation menus.

GET /menus

Get menu

Get menu with all items and hierarchy.

GET /menus/{id}

Get menu locations

Get all registered menu locations.

GET /menus/locations

Create menu

Create a new navigation menu.

POST /menus

Update menu

Update a menu.

PUT /menus/{id}

Delete menu

Delete a menu.

DELETE /menus/{id}

Create menu item

Add an item to a menu.

POST /menus/{id}/items

Update menu item

Update a menu item.

PUT /menus/{id}/items/{item_id}

Delete menu item

Delete a menu item.

DELETE /menus/{id}/items/{item_id}

Assign menu location

Assign a menu to a theme location.

POST /menus/{id}/location

Taxonomies

List taxonomies

List all registered taxonomies.

GET /taxonomies

Get taxonomy

Get taxonomy details.

GET /taxonomies/{taxonomy}

List terms

List terms in a taxonomy.

GET /taxonomies/{taxonomy}/terms

Get term

Get term details.

GET /taxonomies/{taxonomy}/terms/{id}

Create term

Create a new term.

POST /taxonomies/{taxonomy}/terms

Update term

Update a term.

PUT /taxonomies/{taxonomy}/terms/{id}

Delete term

Delete a term.

DELETE /taxonomies/{taxonomy}/terms/{id}

Users

List users

List all users with optional filtering.

GET /users

Get user

Get user details by ID.

GET /users/{id}

Create user

Create a new user.

POST /users

Update user

Update user information.

PUT /users/{id}

Delete user

Delete a user.

DELETE /users/{id}

Comments

List comments

List all comments with optional filtering.

GET /comments

Get comment

Get comment details.

GET /comments/{id}

Create comment

Create a new comment.

POST /comments

Update comment

Update a comment.

PUT /comments/{id}

Delete comment

Delete a comment.

DELETE /comments/{id}

Options

List options

List WordPress options (with optional search filter).

GET /options

Get option

Get option value by name.

GET /options/{option}

Update option

Update an option value.

PUT /options/{option}

Delete option

Delete an option.

DELETE /options/{option}

Performance Analysis

Analyze performance

Analyze page performance including load time, images, CSS/JS, caching, and plugin impact.

GET /analyze/performance/{page_id}

Get Core Web Vitals

Get Core Web Vitals metrics (LCP, FID, CLS) for a page.

GET /analyze/core-web-vitals/{page_id}

Analyze images

Analyze image optimization opportunities including missing alt text and large files.

GET /analyze/images/{page_id}

SEO Analysis

Analyze SEO

Comprehensive SEO analysis including meta tags, headings, image alt text, internal linking, and schema markup.

GET /analyze/seo/{page_id}

Check SEO issues

Quick check for common SEO issues with recommendations.

GET /analyze/seo-issues/{page_id}

Analyze readability

Analyze content readability including Flesch Reading Ease score and paragraph structure.

GET /analyze/readability/{page_id}

AI Engine Optimization (AEO)

Analyze AEO

Analyze content for AI search engine optimization (Perplexity, ChatGPT). Checks structured data, content clarity, and semantic HTML.

GET /analyze/aeo/{page_id}

Check structured data

Check schema markup and structured data (JSON-LD, microdata) for AI parsing.

GET /analyze/structured-data/{page_id}

Security

Validate security

Validate content for security issues before saving.

POST /security/validate

Plugin Management (Experimental)

Plugin management is experimental and disabled by default. Enable in Respira settings before use.

List plugins

List all installed plugins with status and update availability.

GET /plugins

Install plugin

Install a plugin from WordPress.org or ZIP URL.

POST /plugins/install

Activate plugin

Activate a plugin.

POST /plugins/{slug}/activate

Deactivate plugin

Deactivate a plugin.

POST /plugins/{slug}/deactivate

Update plugin

Update a plugin to latest version.

POST /plugins/{slug}/update

Delete plugin

Delete a plugin (must be deactivated first).

DELETE /plugins/{slug}

Multi-Site

Switch site

Switch to a different WordPress site (for multi-site setups).

POST /sites/switch

Response Format

All responses follow this structure:

Success:

{
  "success": true,
  "data": { ... }
}

Error:

{
  "success": false,
  "message": "Error message"
}

Related Documentation

• Configuration
• Installation
• Troubleshooting