> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mainwp.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Termageddon Abilities

> Read Termageddon connection, policy, and page state, and safely change credentials, site mappings, or policy pages through the Abilities API.

Termageddon for MainWP registers ten abilities in the `mainwp-termageddon` category. These are additional to the abilities supplied by MainWP Dashboard. For installation and everyday use, see the [Termageddon Add-on guide](/add-ons/posts-pages/termageddon-for-mainwp-extension).

## Prerequisites

* Meet the [Abilities API prerequisites and authentication requirements](/api-reference/abilities-api/overview).
* Activate a version of Termageddon for MainWP that registers these abilities. Older versions do not expose them.
* Complete the [Termageddon storage upgrade](/add-ons/posts-pages/termageddon-for-mainwp-extension#upgrade-termageddon-storage) when prompted.
* Authenticate as a Dashboard user with access to the Add-on, the required operation permissions, and any targeted Child Site.

Use discovery to check availability and retrieve the complete input and output schemas:

```http theme={null}
GET /wp-json/wp-abilities/v1/abilities?category=mainwp-termageddon
GET /wp-json/wp-abilities/v1/abilities/mainwp/get-termageddon-connection-v1
```

## Endpoints and Permissions

Append the ability name and `/run` to `/wp-json/wp-abilities/v1/abilities/`. Every name below starts with `mainwp/`.

| Ability name                                | Method | Required operation permission                                  |
| ------------------------------------------- | ------ | -------------------------------------------------------------- |
| `mainwp/get-termageddon-connection-v1`      | GET    | `view_termageddon_connection`                                  |
| `mainwp/get-termageddon-policy-sets-v1`     | GET    | `view_termageddon_policy_sets`                                 |
| `mainwp/replace-termageddon-credential-v1`  | DELETE | `manage_termageddon_connection` and WordPress `manage_options` |
| `mainwp/disconnect-termageddon-v1`          | DELETE | `manage_termageddon_connection` and WordPress `manage_options` |
| `mainwp/get-termageddon-site-policy-v1`     | GET    | `view_termageddon_site_policy`                                 |
| `mainwp/replace-termageddon-site-policy-v1` | DELETE | `manage_termageddon_site_policy`                               |
| `mainwp/list-termageddon-pages-v1`          | GET    | `view_termageddon_pages`                                       |
| `mainwp/get-termageddon-page-v1`            | GET    | `view_termageddon_pages`                                       |
| `mainwp/remove-termageddon-page-v1`         | DELETE | `delete_termageddon_pages`                                     |
| `mainwp/get-termageddon-operation-v1`       | GET    | View permission for the operation's resource                   |

The four write abilities use **DELETE**, including their previews, because their registered annotations are `readonly: false`, `destructive: true`, and `idempotent: true`. The method alone does not mean a Child Site page will be deleted.

Team Control grants supplement Add-on access. They do not bypass site restrictions or the WordPress `manage_options` requirement for credential changes. See [Team Control permissions](/add-ons/posts-pages/termageddon-for-mainwp-extension#team-control-permissions).

## Input Conventions

All fields listed for an ability are required, including fields whose value may be `null`. Extra properties are rejected.

* Site and Policy Set IDs are positive integers.
* Generations, page references, and operation references are opaque, 64-character lowercase hexadecimal strings. Copy returned values without modifying them.
* GET requests can send the input object as the URL-encoded `input_json` query parameter.
* DELETE requests send a JSON body containing `{"input": {...}}`. Send API keys in the body, never in a URL.

For example, read a site's Policy Set mapping:

```bash theme={null}
curl --get -u "USERNAME:APPLICATION_PASSWORD" \
  --data-urlencode 'input_json={"site_id":123}' \
  "https://your-dashboard.com/wp-json/wp-abilities/v1/abilities/mainwp/get-termageddon-site-policy-v1/run"
```

## Read Connection and Policy Sets

### Get Connection

`mainwp/get-termageddon-connection-v1` takes an empty input object, `{}`.

Returns `connection_state`, `account_generation`, `mapping_count`, and `observed_at`. Connection states are `configured`, `not_configured`, `unavailable`, or `reconciliation_required`. The remaining fields can be `null`; a missing observation is not proof of an empty account.

### Get Policy Sets

`mainwp/get-termageddon-policy-sets-v1` takes:

| Field                 | Value                                          |
| --------------------- | ---------------------------------------------- |
| `limit`               | Integer from 1 to 100                          |
| `after_policy_set_id` | Positive integer, or `null` for the first page |

Returns `observation` (`available`, `unavailable`, or `not_configured`), `account_generation`, `records`, `next_after_policy_set_id`, and `observed_at`. Each record contains `policy_set_id`, `name`, and `status: "active"`. Only active Policy Sets are listed.

Pass `next_after_policy_set_id` as the next request's cursor until it is `null`. If `records` is `null`, inspect `observation` rather than treating the result as an empty list.

## Read Site Policy and Pages

### Get Site Policy

`mainwp/get-termageddon-site-policy-v1` takes `site_id`.

Returns `site_id`, `mapping_state`, `policy_set_id`, `policy_set_name`, `provider_state`, `account_generation`, `mapping_generation`, and `observed_at`.

Mapping states are `linked`, `unlinked`, `stale`, `unavailable`, or `revalidation_required`. Provider states are `active`, `inactive`, `incomplete`, `pending_invite`, `update_required`, or `unknown`; the provider state can also be `null`. Keep `mapping_generation` for a subsequent mapping change.

### List Pages

`mainwp/list-termageddon-pages-v1` takes:

| Field       | Value                                        |
| ----------- | -------------------------------------------- |
| `site_id`   | Child Site ID                                |
| `limit`     | Integer from 1 to 100                        |
| `after_ref` | Page reference, or `null` for the first page |

Returns `pages`, `next_after_ref`, and `truncated`. Each page includes `page_ref`, `type`, `mapping_state`, `deployment_state`, `child_post_ref`, `updated_at`, and `generation`. Continue with `next_after_ref` when the result is truncated.

Page types are `privacy`, `terms`, `disclaimer`, and `cookie-consent`. Mapping states are `mapped`, `unmapped`, or `stale`.

### Get Page

`mainwp/get-termageddon-page-v1` takes `site_id` and `page_ref`.

Returns `page_ref`, `site_id`, `type`, `deployment_state`, `child_post_ref`, `content_generation`, `account_generation`, `mapping_generation`, `generation`, and `observed_at`. Use this page's `generation` as `if_match` for removal; do not substitute its account or mapping generation.

Deployment states are `draft`, `queued`, `created`, `updated`, `failed`, `delete_pending`, `deleted`, `unknown`, or `reconciliation_required`. Page references identify stored records; they are not WordPress post IDs or URLs.

## Preview and Confirm Changes

Every write requires these fields in addition to its operation-specific input:

| Field           | Purpose                                                 |
| --------------- | ------------------------------------------------------- |
| `if_match`      | Current generation from the relevant read ability       |
| `request_id`    | UUID identifying this logical request                   |
| `dry_run`       | `true` for preview; `false` for confirmation            |
| `confirm`       | `false` for preview; `true` for confirmation            |
| `preview_token` | `null` for preview; the returned token for confirmation |

1. Read the current resource and copy its generation.
2. Submit a preview with `dry_run: true`, `confirm: false`, and `preview_token: null`. Inspect the proposed effect and affected counts.
3. Submit the same target values, generation, and `request_id`, with `dry_run: false`, `confirm: true`, and the returned `preview_token`.
4. Read the returned `operation_ref` with `mainwp/get-termageddon-operation-v1` and inspect the resource again before reporting success.

Reuse the same `request_id` and unchanged confirmed input when retrying that request. Do not reuse it for a different target or effect. If the generation changes or the preview expires, read the resource again and prepare a new preview.

Responses contain `mode` (`dry_run` or `queued`), `request_id`, `operation_ref`, `state` (`ready` or `queued`), and `preview_token`, plus the operation-specific fields below. A `queued` response does not establish completion.

### Replace or Revalidate a Credential

`mainwp/replace-termageddon-credential-v1` additionally requires `api_key`, a string from 1 to 4096 characters. Set `if_match` to the current `account_generation`, including `null` when the connection read returns no generation.

The preview returns `target_account_generation`, `policy_set_count`, and `mappings_to_revalidate`. Replacement verifies the candidate credential with Termageddon and establishes a new account generation. Existing mappings need revalidation against that account.

Use this flow after migrating a legacy credential when the connection reports `reconciliation_required` with a `null` account generation. Supply the intended account's valid API key, preview the affected mappings, and confirm. Then read the connection, list the account's Policy Sets, and revalidate each site mapping with the mapping replacement ability.

### Disconnect

`mainwp/disconnect-termageddon-v1` needs only the common write fields. Its `if_match` must be the current, non-null `account_generation`.

The preview returns `mappings_to_invalidate` and `pages_to_mark_stale`. Disconnect removes the connection and invalidates dependent mappings. It does not delete policy pages from Child Sites.

### Replace or Unlink a Site Policy

`mainwp/replace-termageddon-site-policy-v1` additionally requires `site_id` and `policy_set_id`. Use an active Policy Set ID to link or replace the mapping, or `null` to unlink it. Set `if_match` to the site's current `mapping_generation`.

Returns `action` (`link`, `replace`, `unlink`, or `no_change`) and `target_mapping_generation` in addition to the common response fields. This changes the site's Policy Set association; it does not create policy page content.

### Remove a Page

`mainwp/remove-termageddon-page-v1` additionally requires `site_id`, `page_ref`, and `deletion_mode`. Set `if_match` to the page's current `generation`.

| Deletion mode             | Effect                                                             |
| ------------------------- | ------------------------------------------------------------------ |
| `unlink_local`            | Remove the local mapping and leave the Child Site page in place    |
| `delete_child_and_unlink` | Delete the verified Child Site page, then remove its local mapping |

The preview returns `deletion_mode`, `child_effect`, and `target_generation`. Review `child_effect` before confirming.

Remote deletion requires a MainWP Child version that supports the Termageddon v2 page read/delete contract. The Add-on checks the target's identity and content and verifies its absence after deletion. An older or incompatible Child response does not fall back to an unchecked delete. Update the Child before retrying an unsupported operation. If the target changed, read it again and review a fresh preview.

## Read Operation Status

`mainwp/get-termageddon-operation-v1` takes `operation_ref` and returns `operation_ref`, `kind`, `state`, `site_id`, `result_generation`, `error_code`, and `updated_at`.

| Operation kind                     | Required view permission       |
| ---------------------------------- | ------------------------------ |
| `credential_replace`, `disconnect` | `view_termageddon_connection`  |
| `mapping_replace`                  | `view_termageddon_site_policy` |
| `page_remove`                      | `view_termageddon_pages`       |

States are `queued`, `running`, `succeeded`, `failed`, `unknown`, or `reconciliation_required`. This endpoint reads stored status; polling it does not execute or resume an operation. For `unknown` or `reconciliation_required`, inspect the connection, mapping, or Child Site page before deciding what to retry.

The nullable `error_code` can identify `provider_unavailable`, `provider_rejected`, `child_unavailable`, `target_drift`, `rollback_failed`, or `lease_expired`.

## Handle Errors

| HTTP status | Next step                                                                                           |
| ----------- | --------------------------------------------------------------------------------------------------- |
| 400         | Check required fields, types, bounds, and extra properties against the discovered schema            |
| 403         | Check Add-on access, operation grants, and credential-change authority                              |
| 404         | Check the reference and site access; an inaccessible target can appear absent                       |
| 409         | Check for a conflicting request or changed resource; do not reuse a request ID with different input |
| 410         | Generate a new preview because the confirmation token expired                                       |
| 412         | Read the current generation and preview the change again                                            |
| 422         | Review mismatched confirmation or target changes before retrying                                    |
| 429         | Wait before retrying a provider request                                                             |
| 502         | Check Termageddon or Child Site availability and response compatibility                             |
| 503         | Check Add-on runtime and storage readiness, including the storage upgrade                           |

Inspect the returned error code and message as well as the HTTP status. Keep uncertain outcomes separate from confirmed failures, especially when deleting a Child Site page.