---
title: REST API
description: REST route inventory for CartBay capture, analytics, licensing, tests, and protected AI-agent endpoints.
---

All REST routes register under the namespace `cartbay/v1`.

## Public Capture

```http
POST /wp-json/cartbay/v1/capture
```

Purpose: create, update, or delete a consented checkout capture.

Permission: public.

Protection: `RateLimiter::check('capture')` before capture work.

Arguments:

| Argument | Type | Notes |
|---|---|---|
| `email` | string | Sanitized and validated email. |
| `consent` | boolean | `true` captures; `false` withdraws and deletes active capture. |
| `cart` | object/array | Restore-safe client cart fallback. |
| `source` | string | `classic` or `block`. |
| `session_id` | string | Optional existing CartBay session ID. |

## Admin Analytics

```http
GET /wp-json/cartbay/v1/analytics?days=30
```

Permission: `manage_woocommerce`.

Allowed `days`: `7`, `30`, `90`.

Returns analytics generated by `AnalyticsService`.

## License Routes

All require `manage_woocommerce`.

| Method | Path | Purpose |
|---|---|---|
| `POST` | `/wp-json/cartbay/v1/license/activate` | Activate a WPAnchorBay license key. |
| `GET` | `/wp-json/cartbay/v1/license/status` | Read local/current license status. |
| `POST` | `/wp-json/cartbay/v1/license/deactivate` | Remove/deactivate local license state. |

## Test Routes

All require `manage_woocommerce`.

| Method | Path | Purpose |
|---|---|---|
| `POST` | `/wp-json/cartbay/v1/test/trigger` | Requires Test Mode; creates a dummy abandoned session and near-term email job. |
| `POST` | `/wp-json/cartbay/v1/test/email` | Sends a basic test email or recovery email preview by step. |

## Agent Routes

Agent routes live under:

```http
/wp-json/cartbay/v1/agent
```

They require `cartbay_settings['agent_access_enabled']` and `cartbay_settings['agent_rest_enabled']`.

Authentication can be:

- Normal WordPress authentication, including Application Passwords.
- CartBay Bearer token accepted only on CartBay agent routes.

Route inventory:

| Method | Path | Purpose |
|---|---|---|
| `GET` | `/agent/manifest` | Capabilities and surface metadata. |
| `GET` | `/agent/sessions` | List CartBay sessions. |
| `GET` | `/agent/sessions/{id}` | Read one CartBay session. |
| `POST` | `/agent/sessions/{id}/actions` | Run session action. |
| `GET` | `/agent/analytics` | Read analytics. |
| `GET`, `PATCH` | `/agent/settings` | Read or update safe settings. |
| `GET`, `PATCH` | `/agent/campaign` | Read or update campaign settings. |
| `GET`, `POST` | `/agent/tokens` | List or create CartBay Bearer tokens. |
| `DELETE` | `/agent/tokens/{public_id}` | Revoke a CartBay Bearer token. |
| `GET` | `/agent/audit-log` | Read redacted agent audit log. |

## Query-Arg Recovery Endpoints

Restore and unsubscribe are intentionally not REST routes.

| Query arg | Handler | Purpose |
|---|---|---|
| `?cartbay_restore={token}` | `template_redirect` | Restore cart and redirect to checkout. |
| `?cartbay_unsubscribe={token}` | `init` | Suppress email and cancel future work. |

## Integration Notes

- Public capture protection is rate limiting and strict validation, not authentication.
- Admin routes must use real WordPress capabilities; nonce checks are not authorization.
- Agent routes centralize permission decisions through `AgentService` and `PermissionService`.
- Do not expose CartBay Bearer tokens to non-CartBay endpoints.