> ## 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.

# Post Plus Abilities

> List and read post and page drafts saved with MainWP Post Plus, with accessible target sites and a masked plain-text excerpt.

> [!NOTE]
>
> These abilities require a Post Plus release that includes Abilities API support. Earlier builds do not register them. Check ability discovery on your Dashboard before using these examples.

The Abilities-enabled Post Plus release registers two read-only abilities in the `mainwp-post-plus` category. Both use the `mainwp/` namespace on your MainWP Dashboard.

Use them to review drafts saved with the **Save as Draft** button before you publish them, for example from an AI assistant or a script. They do not create, edit, publish, or delete drafts.

## What You'll Learn

* List saved drafts with pagination and an optional post or page filter
* Read one saved draft with its slug and a short plain-text excerpt
* Interpret target sites, hidden sites, client targets, and masked text

## Prerequisites

* WordPress 6.9 or later on the MainWP Dashboard site
* MainWP Dashboard with Abilities API support; use version 6.2 or later for the `input_json` examples below
* A Post Plus build that registers these abilities, active on MainWP Dashboard
* An authenticated user with `manage_options` and access to the Post Plus Add-on

Use an [Application Password](https://docs.mainwp.com/api-reference/rest-api/application-passwords.md) or the [authentication methods in the Abilities API overview](https://docs.mainwp.com/api-reference/abilities-api/overview.md#authentication). The examples use an Application Password.

Team Control restrictions apply to target sites. A response names only the sites you can access. Other selected sites are counted in `hidden_site_count`.

## Available Abilities

| Ability | Method | Purpose |
| - | - | - |
| `mainwp/list-post-plus-drafts-v1` | GET | List a page of saved post and page drafts |
| `mainwp/get-post-plus-draft-v1` | GET | Read one saved draft with its slug and a masked excerpt |

Discover the abilities and their schemas:

```bash theme={null}
curl -u 'USERNAME:APPLICATION_PASSWORD' \
  'https://your-dashboard.com/wp-json/wp-abilities/v1/abilities?category=mainwp-post-plus'
```

Both abilities are marked `readonly: true`, `destructive: false`, and `idempotent: true`. They reject extra input properties.

***

## List Saved Drafts

**Ability:** `mainwp/list-post-plus-drafts-v1`\

**Method:** GET

All parameters are optional. Omit the input to get the first 20 drafts of both types.

| Parameter | Type | Required | Default | Description |
| - | - | - | - | - |
| `page` | integer | No | `1` | Page number, starting at `1` |
| `per_page` | integer | No | `20` | Drafts per page, from `1` to `100` |
| `type` | string | No | Both | `post` for post drafts or `page` for page drafts |

```bash theme={null}
curl -G -u 'USERNAME:APPLICATION_PASSWORD' \
  --data-urlencode 'input_json={"page":1,"per_page":20,"type":"post"}' \
  'https://your-dashboard.com/wp-json/wp-abilities/v1/abilities/mainwp/list-post-plus-drafts-v1/run'
```

**Example response:**

```json theme={null}
{
  "drafts": [
    {
      "id": 412,
      "title": "Holiday opening hours",
      "type": "post",
      "categories": "News",
      "tags": "holidays, hours",
      "modified": "2026-11-02T09:30:00Z",
      "target_by": "site",
      "sites": [
        { "site_id": 3, "name": "Client Site One" }
      ],
      "client_ids": [],
      "hidden_site_count": 1,
      "group_count": 0
    }
  ],
  "total": 1,
  "page": 1,
  "per_page": 20
}
```

Drafts are sorted by last modified time, newest first. `total` is the number of saved drafts that match the `type` filter.

## Get One Saved Draft

**Ability:** `mainwp/get-post-plus-draft-v1`\

**Method:** GET

The only input is the required `id`: the draft's positive integer ID in MainWP Dashboard. Use an `id` from the list response.

```bash theme={null}
curl -G -u 'USERNAME:APPLICATION_PASSWORD' \
  --data-urlencode 'input_json={"id":412}' \
  'https://your-dashboard.com/wp-json/wp-abilities/v1/abilities/mainwp/get-post-plus-draft-v1/run'
```

The response contains the same fields as a list item, plus `slug` and `excerpt`:

```json theme={null}
{
  "id": 412,
  "title": "Holiday opening hours",
  "type": "post",
  "categories": "News",
  "tags": "holidays, hours",
  "modified": "2026-11-02T09:30:00Z",
  "target_by": "client",
  "sites": [],
  "client_ids": [7, 9],
  "hidden_site_count": 0,
  "group_count": 0,
  "slug": "holiday-opening-hours",
  "excerpt": "Our offices close early on December 24 and reopen on January 2."
}
```

The ability reads only drafts saved with Post Plus. Published posts, unsaved drafts, and other Dashboard content return `mainwp_post_not_found`, even when the ID exists.

***

## Response Fields

| Field | Meaning |
| - | - |
| `id` | Draft ID in MainWP Dashboard |
| `title` | Plain-text draft title |
| `type` | `post` or `page` |
| `categories` | Saved categories, or an empty string |
| `tags` | Saved tags, or an empty string |
| `modified` | Last modified time in ISO 8601 UTC, or an empty string when unavailable |
| `target_by` | How the draft selects its targets: `site`, `group`, or `client` |
| `sites` | Selected sites you can access, with `site_id` and `name` |
| `client_ids` | Selected client IDs when `target_by` is `client`; otherwise empty |
| `hidden_site_count` | Number of selected sites you cannot access |
| `group_count` | Number of selected site tags (groups) |
| `slug` | Get only. Saved post slug, or an empty string |
| `excerpt` | Get only. Plain-text excerpt of up to 300 characters |

When `target_by` is `group`, `sites` and `hidden_site_count` cover the sites in the selected tags. The IDs and names of hidden sites are not returned.

When `target_by` is `client`, Post Plus returns the saved `client_ids` without expanding them to sites. `sites` is empty and `hidden_site_count` is `0`. Use the [Clients Abilities](https://docs.mainwp.com/api-reference/abilities-api/clients.md) to look up those clients.

## Excerpts and Masked Text

The excerpt is built from the saved draft body. Shortcodes and HTML are removed before the text is shortened to 300 characters. The response never includes the full body, HTML, or raw metadata.

Before returning any text field, including site names, Post Plus replaces sensitive-looking values with `[redacted]`:

* URLs, file paths, and email addresses
* API keys, tokens, private keys, and `key=value` or `key: value` credentials
* `Bearer` followed by a token
* `Basic` followed by a value that decodes to `user:password` credentials

Ordinary text such as "Basic Principles of Gardening" stays readable. A few phrases can still be masked because they look like credentials, such as "Basic Overview" or text that follows a word like `password:`. Unregistered shortcodes can remain in the excerpt as literal text. Open the draft in the **Drafts** page to review its full content.

> [!NOTE]
>
> These abilities read stored data on MainWP Dashboard only. They do not contact Child sites or change posts, metadata, or settings.

## Error Handling

Standard authentication, schema, and method errors follow the [Abilities API error reference](https://docs.mainwp.com/api-reference/abilities-api/overview.md#error-reference). Post Plus can also return:

| Code | HTTP | Meaning |
| - | - | - |
| `mainwp_post_plus_invalid_input` | 400 | Input has unknown properties or invalid pagination, type, or ID values |
| `mainwp_permission_denied` | 403 | The user lacks `manage_options` or access to Post Plus |
| `mainwp_post_not_found` | 404 | No saved Post Plus draft has this ID |
| `mainwp_post_plus_read_failed` | 500 | Post Plus could not read the saved draft data |

Unauthenticated requests return HTTP 401 from MainWP Dashboard before the ability runs.

## Related Resources

* [Post Plus](https://docs.mainwp.com/add-ons/posts-pages/post-plus-extension.md) - Save, edit, publish, and delete drafts
* [Abilities API Overview](https://docs.mainwp.com/api-reference/abilities-api/overview.md) - Authentication, input formats, discovery, and errors
* [Sites Abilities](https://docs.mainwp.com/api-reference/abilities-api/sites.md) - Look up site IDs returned in `sites`


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.