# IM-Press AI Agent Guide

IM-Press is agent-first. Every feature is available via REST API. This guide teaches what the API itself can't — how to authenticate, how to discover endpoints on your own, what workflows exist, and which patterns will break a site.

The WordPress REST API is self-documenting. **Read it before asking for more docs.**

## Quick Start

**1. Authenticate with a WordPress Application Password.**

- Log in to `https://yoursite.com/wp-admin`, go to **Users → Profile → Application Passwords**.
- Generate a password labeled for your agent.
- Send requests with HTTP Basic Auth:

```http
Authorization: Basic base64(username:app_password)
```

**2. Discover every endpoint on the site.**

```http
GET https://yoursite.com/wp-json/
```

Returns every registered namespace and every route with its args. Filter to `imp-*` and `impress/*` namespaces — those are IM-Press.

**3. Inspect a single endpoint's schema.**

```http
OPTIONS https://yoursite.com/wp-json/imp-seo-workspace/v1/keywords
```

Returns the full arg schema (types, required flags, defaults, enums).

**4. Get the full machine-readable spec.**

```http
GET https://yoursite.com/wp-json/imp-openapi/v1/spec
```

Returns an **OpenAPI 3.0** document with every namespace, path, parameter, tier requirement, and security scheme. Public — no auth required. Cached server-side 1h. This is your menu.

## Namespace Map

One line per namespace. Use the OpenAPI spec for full endpoint details.

| Namespace | What it does |
|-----------|--------------|
| `impress/v1` | Core: pages, blocks, templates, brand, AI prompt-to-page |
| `imp-openapi/v1` | OpenAPI 3.0 spec of this API (public) |
| `imp-health/v1` | Site health monitoring (public ping + full check) |
| `imp-config/v1` | Per-site configuration (branding, templates, skip rules) |
| `imp-deploy/v1` | Safe Deploy — bypasses WP content sanitization |
| `imp-sitemap/v1` | XML sitemap generation |
| `imp-redirects/v1` | 301/302 redirect rules |
| `imp-analytics/v1` | GA4 / tracking script configuration |
| `imp-seo/v1` | SEO meta, Open Graph, schema markup |
| `imp-seo-v2/v1` | Bulk SEO audit, schema generation |
| `imp-seo-analysis/v1` | Focus keyphrase scoring, readability, internal link suggestions |
| `imp-seo-workspace/v1` | Strategy: keywords, competitors, agent task queue, content pipeline |
| `imp-breadcrumbs/v1` | Breadcrumb trail for any page/post |
| `imp-faq-schema/v1` | FAQPage JSON-LD auto-detection |
| `imp-products/v1` | Product catalog with multi-affiliate links |
| `imp-affiliate/v1` | Affiliate program registry + click tracking |
| `imp-email/v1` | SMTP, contact forms, newsletter, downloads |
| `imp-email/v2` | Email automation workflows, A/B testing |
| `imp-images/v1` | Unsplash auto-fetch for featured images |
| `imp-bookings/v1` | Legacy booking schema adapter |
| `imp-bookings/v2` | Resource bookings, availability, waitlist |
| `imp-custom-code/v1` | Global + per-page CSS/JS injection |
| `imp-responsive/v1` | Responsive breakpoints + utility classes |
| `imp-articles/v1` | Article templates: TOC, reading time, related posts |
| `imp-lightbox/v1` | Gallery lightbox settings |
| `imp-antispam/v1` | Spam block statistics |
| `imp-recaptcha/v1` | reCAPTCHA v3 configuration |
| `imp-embed/v1` | Secure iframe embeds (10 provider auto-detect) |
| `imp-templates/v1` | Reusable page templates with `{{field}}` placeholders |
| `imp-perf/v1` | Page cache, critical CSS, Core Web Vitals |
| `imp-license/v2` | License validation + activation |
| `imp-dashboard/v1` | Admin dashboard data + module config drawers |
| `imp-prompt-studio/v1` | AI prompt-to-page history |

## Workflow: Agent Task Queue (SEO Workspace)

The SEO Workspace is where users hand strategic SEO work to agents. **IM-Press is the workspace, not the brain** — bring your own tools for research, analysis, and writing.

1. **Poll** for work:
   ```http
   GET /wp-json/imp-seo-workspace/v1/tasks/pending
   ```
2. **Claim** a task (atomic — another agent can't claim it after you):
   ```http
   POST /wp-json/imp-seo-workspace/v1/tasks/{id}/claim
   Body: { "agent_name": "my-agent" }
   ```
3. **Do the work** using your own capabilities — web search, competitor analysis, content writing, whatever you have. IM-Press doesn't care how you produce results.
4. **Complete** and submit output:
   ```http
   POST /wp-json/imp-seo-workspace/v1/tasks/{id}/complete
   Body: { "output_data": { ... whatever structure the task expects ... } }
   ```

**Task types:** `analyze_gaps`, `generate_content`, `audit_page`, `research_competitor`, `keyword_research`. Each has its own input/output conventions — see the OpenAPI spec for schemas.

If you fail, report it — don't leave tasks stuck:
```http
POST /wp-json/imp-seo-workspace/v1/tasks/{id}/fail
Body: { "error_message": "..." }
```

## Workflow: Safe Deploy (styled HTML)

Never `PUT /wp/v2/pages/{id}` or call `wp_update_post()` on pages with inline `<style>`, `<script>`, or `<svg>`. WordPress's `wp_kses_post` sanitization strips those tags and will destroy your page silently.

Use Safe Deploy instead — it writes directly to `wp_posts` via `$wpdb->update()` and preserves everything:

```http
POST /wp-json/imp-deploy/v1/safe-update
Body: {
  "page_id": 123,
  "content": "<!DOCTYPE html>...<style>...</style>..."
}
```

Safe Deploy also records a revision snapshot in `_imp_deploy_history` post meta so [revision history](imp-deploy/v1/pages-with-history) can roll back if needed.

## Workflow: Content Pipeline

End-to-end: research → draft → review → deploy.

1. **Agent generates a content draft**:
   ```http
   POST /wp-json/imp-seo-workspace/v1/content
   Body: { "title", "slug", "content", "meta_description", "featured_image", "task_id", "keyword_id" }
   ```
   IM-Press auto-scores the draft via `imp-seo-analysis` on insert.
2. **User reviews in WP admin** — IM-Press → SEO Workspace → Content tab.
3. **User approves or rejects**:
   - `POST /wp-json/imp-seo-workspace/v1/content/{id}/approve`
   - `POST /wp-json/imp-seo-workspace/v1/content/{id}/reject`
4. **Deploy the approved draft** as a new WP page (uses Safe Deploy internally):
   ```http
   POST /wp-json/imp-seo-workspace/v1/content/{id}/deploy
   Body: { "post_status": "publish" }
   ```

Image Fetcher auto-pulls an Unsplash photo if the draft has no `featured_image`. The target keyword is saved as `_imp_focus_keyphrase` on the deployed page so SEO Analysis can score it.

## Anti-Patterns

Things that will break sites:

- **Never** `wp_update_post()` or `PUT /wp/v2/pages/{id}` on pages with inline `<style>`/`<script>`. Use Safe Deploy.
- **Never** use JavaScript arrow functions (`=>`) in content stored in `post_content`. WordPress HTML-encodes `=>` to `=&gt;` inside `<script>` blocks, breaking every handler. Use `function()` syntax.
- **Never** put `<Directory>` directives in `.htaccess` — only `httpd.conf` accepts them. Use `<FilesMatch>` for per-directory rules.
- **On shared hosting (Hostgator, etc.)** PHP OPcache must be cleared via an HTTP request — `touch` and CLI `opcache_reset()` don't touch the web-server opcode cache. Drop a temp PHP file that calls `opcache_reset(); unlink(__FILE__);` and `curl` it.
- **ModSecurity** may reject REST POSTs with HTML in the body. Send a browser User-Agent header and add 5–6s between requests if you hit 406s.
- **Never** commit the plugin's source from `~/pagedeploy/` — that directory is stale. Canonical source is the GitHub repo and the hosted ZIP.

## Licensing Tiers

| Tier | Price | What you get |
|------|-------|--------------|
| **Starter** | Free | 25 blocks + Antispam, basic SEO, sitemap, forms, contact, license check |
| **Pro** | $49/yr or $149 lifetime | All 100 blocks + SEO Analysis, SEO Workspace (keywords/overview), Image Fetcher, Article Templates, Custom Code, Responsive, Products, Affiliate, Analytics, reCAPTCHA, Lightbox, Embed, FAQ, Breadcrumbs, Health Monitor, Redirects, Email V2, Forms V2, Bookings, Performance |
| **Agency** | $149/yr or $449 lifetime | Everything + AI endpoints (`impress/v1/ai/*`), SEO Workspace task queue + content pipeline + competitors, White-label, Page Templates, Migrator |

Check current tier:
```http
GET /wp-json/imp-health/v1/ping
```
Returns version + license status. The **OpenAPI spec is public on all tiers** — free users see everything in the menu, but endpoints enforce their own tier check when hit.

## Tips

- The spec is cached 1h. To refresh: `POST /wp-json/imp-openapi/v1/refresh` (admin-only) or activate/update any plugin.
- `x-im-press-tier` on each OpenAPI path tells you the minimum tier. Read this before you try a request to avoid 403s.
- Most endpoints return `{ success: true, ... }` on success and `{ code, message, data: { status } }` on error (WP_REST_Response standard).
- Health monitor exposes a public heartbeat at `/imp-health/v1/ping` — good for uptime checks.
