# Rewrite a block with AI

> Scale plan. Improves, shortens, lengthens, fixes or changes the tone of one block. The block keeps its id, type, style and links; only the words change.

Source: https://docs.pidgely.com/api-reference/template-builder/ai-rewrite/

`POST https://api.pidgely.com/template-builder/ai/rewrite`

Scale plan. Improves, shortens, lengthens, fixes or changes the tone of one block. The block keeps its id, type, style and links; only the words change.

The block keeps its id, type, style and links; only words and emphasis change. Scale plan.

**Authorization:** `Bearer pdg_…`. An API key with `full_access`. A `sending_access` key gets `401 restricted_api_key`.

## Body parameters

JSON object.

| Name | Type | Required | Description |
|---|---|---|---|
| `block` | object | Yes | One row of the e-mail. Fields per type: heading (level, text), text and quote (runs), button (label, href, full_width), image (src, alt, href, width), divider (thickness), spacer (height), columns (2-3 columns of blocks, not nested), list (ordered, items), code (text), social (links), footer (runs, unsubscribe, unsubscribe_label, unsubscribe_url). |
| `block.id` | string | No | Unique id (UUID). |
| `block.type` | string | Yes | One of `heading`, `text`, `button`, `image`, `divider`, `spacer`, `columns`, `list`, `quote`, `code`, `social`, `footer`. |
| `block.style` | object | No | — |
| `block.style.align` | string | No | One of `left`, `center`, `right`. |
| `block.style.color` | string | No | — |
| `block.style.background` | string | No | — |
| `block.style.font_size` | integer | No | Between 10 and 64. |
| `block.style.padding` | object | No | — |
| `block.style.padding.top` | integer | Yes | — |
| `block.style.padding.right` | integer | Yes | — |
| `block.style.padding.bottom` | integer | Yes | — |
| `block.style.padding.left` | integer | Yes | — |
| `block.level` | integer | No | One of `1`, `2`, `3`. |
| `block.text` | string | No | — |
| `block.runs` | object[] | No | — |
| `block.runs[].text` | string | Yes | — |
| `block.runs[].bold` | boolean | No | — |
| `block.runs[].italic` | boolean | No | — |
| `block.runs[].href` | string | No | — |
| `block.label` | string | No | — |
| `block.href` | string | No | — |
| `block.full_width` | boolean | No | — |
| `block.src` | string | No | — |
| `block.alt` | string | No | — |
| `block.width` | integer | No | — |
| `block.height` | integer | No | — |
| `block.thickness` | integer | No | — |
| `block.columns` | object[] | No | — |
| `block.columns[].blocks` | object[] | Yes | — |
| `block.columns[].blocks[].id` | string | No | Unique id (UUID). |
| `block.columns[].blocks[].type` | string | Yes | One of `heading`, `text`, `button`, `image`, `divider`, `spacer`, `columns`, `list`, `quote`, `code`, `social`, `footer`. |
| `block.columns[].blocks[].style` | object | No | — |
| `block.columns[].blocks[].level` | integer | No | One of `1`, `2`, `3`. |
| `block.columns[].blocks[].text` | string | No | — |
| `block.columns[].blocks[].runs` | object[] | No | — |
| `block.columns[].blocks[].label` | string | No | — |
| `block.columns[].blocks[].href` | string | No | — |
| `block.columns[].blocks[].full_width` | boolean | No | — |
| `block.columns[].blocks[].src` | string | No | — |
| `block.columns[].blocks[].alt` | string | No | — |
| `block.columns[].blocks[].width` | integer | No | — |
| `block.columns[].blocks[].height` | integer | No | — |
| `block.columns[].blocks[].thickness` | integer | No | — |
| `block.columns[].blocks[].columns` | object[] | No | — |
| `block.columns[].blocks[].ordered` | boolean | No | — |
| `block.columns[].blocks[].items` | object[][] | No | — |
| `block.columns[].blocks[].links` | object[] | No | — |
| `block.columns[].blocks[].unsubscribe` | boolean | No | — |
| `block.columns[].blocks[].unsubscribe_label` | string | No | — |
| `block.columns[].blocks[].unsubscribe_url` | string | No | Default `{{{PIDGELY_UNSUBSCRIBE_URL}}}` (filled per recipient by broadcasts; pass it as a variable on API sends). |
| `block.ordered` | boolean | No | — |
| `block.items` | object[][] | No | — |
| `block.links` | object[] | No | — |
| `block.links[].network` | string | Yes | One of `x`, `linkedin`, `instagram`, `facebook`, `youtube`, `github`, `tiktok`, `discord`, `website`. |
| `block.links[].url` | string | Yes | Public `https` URL that receives the events. |
| `block.unsubscribe` | boolean | No | — |
| `block.unsubscribe_label` | string | No | — |
| `block.unsubscribe_url` | string | No | Default `{{{PIDGELY_UNSUBSCRIBE_URL}}}` (filled per recipient by broadcasts; pass it as a variable on API sends). |
| `action` | string | Yes | One of `improve`, `shorten`, `lengthen`, `fix`, `tone`. |
| `tone` | string | No | One of `friendly`, `professional`, `playful`, `persuasive`, `formal`, `casual`, `empathetic`, `urgent`. |
| `language` | string | No | — |
| `variables` | string[] | No | Typed variables (up to 50). `FIRST_NAME`, `LAST_NAME`, `EMAIL` and `UNSUBSCRIBE_URL` are reserved. |
| `template_id` | string | No | UUID. |

## Request

This endpoint is in the Node.js SDK; the other [SDKs](https://docs.pidgely.com/sdks/) don't cover it yet, so call it over HTTP from them.

```js tab="Node.js"
import { Pidgely } from 'pidgely';

const pidgely = new Pidgely(process.env.PIDGELY_API_KEY);

const { data, error } = await pidgely.templateBuilder.ai.rewrite({
  block: {
    type: 'text',
    runs: [
      {
        text: 'Thanks for signing up. We are glad you are here.',
      },
    ],
  },
  action: 'tone',
  tone: 'friendly',
});
console.log(data ?? error);
```

```bash tab="cURL"
curl -X POST 'https://api.pidgely.com/template-builder/ai/rewrite' \
  -H "Authorization: Bearer $PIDGELY_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "block": {
    "type": "text",
    "runs": [
      {
        "text": "Thanks for signing up. We are glad you are here."
      }
    ]
  },
  "action": "tone",
  "tone": "friendly"
}'
```

## Response

`200 OK`

```json
{
  "object": "template_builder",
  "block": {
    "id": "0199d8a2-6f3c-7c51-9e2a-3b1f0c6d4e21",
    "type": "heading",
    "style": {
      "align": "left",
      "color": "color",
      "background": "background",
      "font_size": 10,
      "padding": {
        "top": 1,
        "right": 1,
        "bottom": 1,
        "left": 1
      }
    },
    "level": 1,
    "text": "Hello!",
    "runs": [
      {
        "text": "Hello!",
        "bold": false,
        "italic": false,
        "href": "href"
      }
    ],
    "label": "label",
    "href": "href",
    "full_width": false,
    "src": "src",
    "alt": "alt",
    "width": 1,
    "height": 1,
    "thickness": 1,
    "columns": [
      {
        "blocks": [
          {
            "id": "0199d8a2-6f3c-7c51-9e2a-3b1f0c6d4e21",
            "type": "heading",
            "style": {
              "align": null,
              "color": null,
              "background": null,
              "font_size": null,
              "padding": null
            },
            "level": 1,
            "text": "Hello!",
            "runs": [
              null
            ],
            "label": "label",
            "href": "href",
            "full_width": false,
            "src": "src",
            "alt": "alt",
            "width": 1,
            "height": 1,
            "thickness": 1,
            "columns": [
              null
            ],
            "ordered": false,
            "items": [
              null
            ],
            "links": [
              null
            ],
            "unsubscribe": false,
            "unsubscribe_label": "unsubscribe_label",
            "unsubscribe_url": "unsubscribe_url"
          }
        ]
      }
    ],
    "ordered": false,
    "items": [
      [
        {
          "text": "Hello!",
          "bold": false,
          "italic": false,
          "href": "href"
        }
      ]
    ],
    "links": [
      {
        "network": "x",
        "url": "https://acme.com/webhooks/pidgely"
      }
    ],
    "unsubscribe": false,
    "unsubscribe_label": "unsubscribe_label",
    "unsubscribe_url": "unsubscribe_url"
  }
}
```

### Response fields

| Name | Type | Required | Description |
|---|---|---|---|
| `object` | string | Yes | Object type. One of `template_ai_block`. |
| `block` | object | Yes | One row of the e-mail. Fields per type: heading (level, text), text and quote (runs), button (label, href, full_width), image (src, alt, href, width), divider (thickness), spacer (height), columns (2-3 columns of blocks, not nested), list (ordered, items), code (text), social (links), footer (runs, unsubscribe, unsubscribe_label, unsubscribe_url). |
| `block.id` | string | No | Unique id (UUID). |
| `block.type` | string | Yes | One of `heading`, `text`, `button`, `image`, `divider`, `spacer`, `columns`, `list`, `quote`, `code`, `social`, `footer`. |
| `block.style` | object | No | — |
| `block.style.align` | string | No | One of `left`, `center`, `right`. |
| `block.style.color` | string | No | — |
| `block.style.background` | string | No | — |
| `block.style.font_size` | integer | No | Between 10 and 64. |
| `block.style.padding` | object | No | — |
| `block.style.padding.top` | integer | Yes | — |
| `block.style.padding.right` | integer | Yes | — |
| `block.style.padding.bottom` | integer | Yes | — |
| `block.style.padding.left` | integer | Yes | — |
| `block.level` | integer | No | One of `1`, `2`, `3`. |
| `block.text` | string | No | — |
| `block.runs` | object[] | No | — |
| `block.runs[].text` | string | Yes | — |
| `block.runs[].bold` | boolean | No | — |
| `block.runs[].italic` | boolean | No | — |
| `block.runs[].href` | string | No | — |
| `block.label` | string | No | — |
| `block.href` | string | No | — |
| `block.full_width` | boolean | No | — |
| `block.src` | string | No | — |
| `block.alt` | string | No | — |
| `block.width` | integer | No | — |
| `block.height` | integer | No | — |
| `block.thickness` | integer | No | — |
| `block.columns` | object[] | No | — |
| `block.columns[].blocks` | object[] | Yes | — |
| `block.columns[].blocks[].id` | string | No | Unique id (UUID). |
| `block.columns[].blocks[].type` | string | Yes | One of `heading`, `text`, `button`, `image`, `divider`, `spacer`, `columns`, `list`, `quote`, `code`, `social`, `footer`. |
| `block.columns[].blocks[].style` | object | No | — |
| `block.columns[].blocks[].level` | integer | No | One of `1`, `2`, `3`. |
| `block.columns[].blocks[].text` | string | No | — |
| `block.columns[].blocks[].runs` | object[] | No | — |
| `block.columns[].blocks[].label` | string | No | — |
| `block.columns[].blocks[].href` | string | No | — |
| `block.columns[].blocks[].full_width` | boolean | No | — |
| `block.columns[].blocks[].src` | string | No | — |
| `block.columns[].blocks[].alt` | string | No | — |
| `block.columns[].blocks[].width` | integer | No | — |
| `block.columns[].blocks[].height` | integer | No | — |
| `block.columns[].blocks[].thickness` | integer | No | — |
| `block.columns[].blocks[].columns` | object[] | No | — |
| `block.columns[].blocks[].ordered` | boolean | No | — |
| `block.columns[].blocks[].items` | object[][] | No | — |
| `block.columns[].blocks[].links` | object[] | No | — |
| `block.columns[].blocks[].unsubscribe` | boolean | No | — |
| `block.columns[].blocks[].unsubscribe_label` | string | No | — |
| `block.columns[].blocks[].unsubscribe_url` | string | No | Default `{{{PIDGELY_UNSUBSCRIBE_URL}}}` (filled per recipient by broadcasts; pass it as a variable on API sends). |
| `block.ordered` | boolean | No | — |
| `block.items` | object[][] | No | — |
| `block.links` | object[] | No | — |
| `block.links[].network` | string | Yes | One of `x`, `linkedin`, `instagram`, `facebook`, `youtube`, `github`, `tiktok`, `discord`, `website`. |
| `block.links[].url` | string | Yes | Public `https` URL that receives the events. |
| `block.unsubscribe` | boolean | No | — |
| `block.unsubscribe_label` | string | No | — |
| `block.unsubscribe_url` | string | No | Default `{{{PIDGELY_UNSUBSCRIBE_URL}}}` (filled per recipient by broadcasts; pass it as a variable on API sends). |

## Errors

Errors have the shape `{"statusCode", "name", "message"}`. See [Errors](https://docs.pidgely.com/errors/) for the full list.

| Status | Name | When |
|---|---|---|
| 401 | `missing_api_key`, `restricted_api_key` | No `Authorization: Bearer` header, or a `sending_access` key called an endpoint that needs `full_access`. |
| 403 | `invalid_api_key`, `validation_error` | The API key is invalid or revoked, or the request is not allowed for this account (unverified domain, plan limit, paused account). |
| 422 | `validation_error` | A field is missing or invalid; `message` names it. |
| 429 | `rate_limit_exceeded` | Too many requests per second. Wait for `Retry-After` seconds. |
| 502 | — | The AI service failed or returned an unusable answer (ai_unavailable, ai_busy, ai_timeout, ai_invalid_output) |