> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.meetgail.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.meetgail.com/_mcp/server.

# Scripts V2

> Create, edit and publish scripts with drafts and version history, and move an integration from the V1 scripts endpoints.

Scripts V2 gives every script a draft and a version history. You edit a draft without changing live calls, then publish it when it's ready. Calls and messages always use the latest **published** revision.

> **Note**
>
> New organizations start on Scripts V2. Existing organizations move when they upgrade, which an admin can do from the Gail portal once the upgrade is offered to them. The upgrade is permanent. If you have questions, contact [support@meetgail.com](mailto:support@meetgail.com).

The endpoints are listed under **Scripts V2** in the API Reference. They use the same `X-API-Key` authentication as the rest of the API.

## How scripts work in V2

* **Id.** Each script has one id that never changes across revisions.
* **Revisions.** Every save is stored as a numbered revision, starting at `1`. Revisions are never edited after they're published.
* **Revision state.** A revision is either `draft` or `published`. A script has at most one draft at a time, and it's always the newest revision.
* **What calls use.** Calls and messages use the latest published revision, never the draft.
* **Actions belong to the script.** A phone script's actions (use cases) and data extraction fields are part of the script itself. Editing one script never changes another.

| You want to                                  | Call                                                                         |
| -------------------------------------------- | ---------------------------------------------------------------------------- |
| Create a script                              | `POST /v2/scripts` (publishes revision 1)                                    |
| Read the newest revision, draft or published | `GET /v2/scripts/{scriptId}`                                                 |
| Save changes as a draft                      | `PUT /v2/scripts/{scriptId}`                                                 |
| Make the draft live                          | `POST /v2/scripts/{scriptId}/publish`                                        |
| See the history                              | `GET /v2/scripts/{scriptId}/revisions`                                       |
| Read one revision                            | `GET /v2/scripts/{scriptId}/revisions/{revision}`                            |
| List scripts                                 | `GET /v2/scripts`                                                            |
| Archive or restore                           | `POST /v2/scripts/{scriptId}/archive`, `POST /v2/scripts/{scriptId}/restore` |

## Create a script

Send the whole script. `type`, `name` and `direction` are required for every type. The new script is published right away as revision 1, and the response has status `201`.

```bash
curl -X POST https://api.meetgail.com/v2/scripts \
  -H "X-API-Key: your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "phone",
    "name": "Policy renewal reminder",
    "direction": "outbound",
    "agentName": "Gail",
    "greeting": "Hi, this is Gail calling from {Organization Name}.",
    "goodbye": "Thanks for your time. Have a great day.",
    "useCases": [
      {
        "order": 1,
        "status": "active",
        "title": "Confirm renewal",
        "description": "Use this when the customer is ready to talk about their renewal.",
        "actions": [
          { "type": "default", "description": "Confirm the policy number and renewal date." }
        ]
      }
    ]
  }'
```

The response includes the fields you need for the next edit:

```json
{
  "type": "phone",
  "id": "01a1f00e-f9e3-7c11-9d2a-5b6e8f7a9c10",
  "revision": 1,
  "revisionState": "published",
  "concurrencyVersion": 1,
  "publishedAt": "2026-11-19T15:04:05Z",
  "archived": false,
  "...": "..."
}
```

### Script types

| `type`    | Required fields                    | Use it for                          |
| --------- | ---------------------------------- | ----------------------------------- |
| `phone`   | `agentName`, `goodbye`, `useCases` | AI phone calls, inbound or outbound |
| `text`    | `message`                          | Text messages                       |
| `email`   | `subject`, `body`                  | Emails                              |
| `blaster` | `message`                          | Pre-recorded phone messages         |

Phone scripts also accept FAQs, knowledge base settings, voice settings, post-call scripts and `dataExtractionFields`. See the request schema in the API Reference for every field.

## Edit and publish

1. **Read the script** with `GET /v2/scripts/{scriptId}`. Keep its `revision` and `concurrencyVersion`.
2. **Save a draft** with `PUT /v2/scripts/{scriptId}`, sending the whole script, not just the fields you changed.
   * If the newest revision is published, the save starts a new draft revision.
   * If a draft already exists, the save replaces its content and keeps its revision number.
3. **Publish** with `POST /v2/scripts/{scriptId}/publish`. The draft becomes the live revision for new calls and messages.

```bash
# Save a draft, refusing the save if someone changed the script since you read it
curl -X PUT "https://api.meetgail.com/v2/scripts/$SCRIPT_ID?expectedRevision=1&expectedConcurrencyVersion=1" \
  -H "X-API-Key: your-api-key-here" \
  -H "Content-Type: application/json" \
  -d @script.json

# Publish the draft you just saved (use the revision and concurrencyVersion the save returned)
curl -X POST "https://api.meetgail.com/v2/scripts/$SCRIPT_ID/publish?expectedRevision=2&expectedConcurrencyVersion=1" \
  -H "X-API-Key: your-api-key-here"
```

Only a draft can be published. Publishing when the newest revision is already published returns `400` with `ERR_SCRIPT_NOT_DRAFT`.

### Avoid overwriting someone else's changes

`PUT` and `publish` accept `expectedRevision` and `expectedConcurrencyVersion` as query parameters. Send the values from the response you last read:

* If someone else saved or published since then, the request returns `409` with `ERR_SCRIPT_CHANGED`, and nothing is changed. Read the script again and reapply your edit.
* Send both values or neither. Sending only one returns `400`.
* Without them, the last write wins. If two writes land at the same moment, one of them can get a `409` with no body. Read the script again and retry.

`concurrencyVersion` starts at `1` for each revision and changes on every save, publish and archive, so always use the value from your most recent response.

## Archive and restore

`POST /v2/scripts/{scriptId}/archive` stops a script from being edited. Restoring it with `POST /v2/scripts/{scriptId}/restore` makes it editable again.

* Archiving doesn't break anything already using the script. Campaigns, sequences, inbound routing and tools that reference it keep working.
* An archived script can't be saved or published until it's restored. Those requests return `409` with `ERR_SCRIPT_ARCHIVED`.
* A save that adds or keeps a reference to an archived script is refused with `ERR_SCRIPT_ARCHIVED_REFERENCE`, and the error names the script.
* Both calls are safe to repeat. Archiving an archived script, or restoring an active one, returns `200`.

## List scripts

`GET /v2/scripts` returns the newest revision of each script, 50 at most per page.

| Parameter          | Description                                 |
| ------------------ | ------------------------------------------- |
| `limit`            | Page size, 1 to 50. Default 50.             |
| `after` / `before` | Cursor: a script id from the previous page. |
| `order`            | `asc` or `desc` by id. Default `desc`.      |
| `direction`        | `inbound` or `outbound`.                    |
| `status`           | `active` or `archived`.                     |

## Move an integration from V1

### What changes when an organization is on Scripts V2

**Writes go to V2.** For an organization on Scripts V2, every V1 script write returns `409` with the code `SCRIPTS_API_V2_REQUIRED`. That includes creating, updating and deleting scripts under `/v1/scripts`, and changing data extraction fields under `/v1/data_extraction`. Use the V2 endpoints instead. Data extraction fields go in the script body as `dataExtractionFields`.

**Reads keep working.** `GET /v1/scripts` and `GET /v1/scripts/{scriptId}` return the published V2 scripts.

**Script ids change once, at the upgrade.** When an existing organization upgrades, each script gets a new id. The old id still works for reads and for starting calls, but not for edits:

* `GET /v1/scripts/{scriptId}` and `GET /v2/scripts/{scriptId}` accept the old id or the new one. Responses always carry the new id.
* Starting calls, outreaches and sequences accept either id.
* Archive and restore accept either id.
* **Saving (`PUT /v2/scripts/{scriptId}`) and publishing need the new id.** Sent the old id, they return `404`.
* `GET /v2/scripts/{scriptId}/revisions` and `.../revisions/{revision}` need the new id.

If your integration stored script ids before the upgrade, read each script with `GET /v2/scripts/{scriptId}` and use the `id` it returns for every save and publish.

**Webhooks and call data use the new id.** After the upgrade, `call_information.script_id` in call webhooks and in the calls API is the new id. `call_information.script_revision_number` tells you which revision the call ran.

> **Note**
>
> If your integration compares `script_id` against ids it saved earlier, for example to route calls in a CRM or to filter a report, update those saved ids after the upgrade. The easiest way is to look each saved id up with `GET /v2/scripts/{scriptId}` and store the `id` it returns.

### Checklist

1. Switch script creates and edits to `POST` and `PUT /v2/scripts`, and add a `publish` call when the change should go live. Save and publish with the new id.
2. Move data extraction field changes into the script body.
3. Handle `409 SCRIPTS_API_V2_REQUIRED` from any V1 write you haven't moved yet.
4. Update stored script ids that you compare against webhook or call data.
5. Check the HTTP status before reading an error body. A `409` can come back with no body (see [Errors](#errors)).

## Errors

Most errors use the standard error response: an `errors` array whose entries carry a `code`, a `title` and a `detail`. Some `409` responses have no body, so check the HTTP status first and only read `errors` when the response has a JSON body.

| Status | Code                            | Meaning                                                                                                                                                                                                                     |
| ------ | ------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `400`  | `ERR_SCRIPT_NOT_DRAFT`          | Publish was called, but the newest revision is already published.                                                                                                                                                           |
| `400`  | `ERR_PUBLISH_TOOLS_INVALID`     | The draft references tools that are archived or missing. Remove them and publish again.                                                                                                                                     |
| `400`  | `ERR_SCRIPT_ARCHIVED_REFERENCE` | The save references an archived script, which the error names.                                                                                                                                                              |
| `400`  | —                               | The body is invalid, or only one of `expectedRevision` and `expectedConcurrencyVersion` was sent.                                                                                                                           |
| `404`  | —                               | No script with that id in your organization, or a save or publish was sent the old id from before the upgrade.                                                                                                              |
| `409`  | `ERR_SCRIPT_ARCHIVED`           | The script is archived. Restore it before saving or publishing.                                                                                                                                                             |
| `409`  | `ERR_SCRIPT_CHANGED`            | Someone saved or published the script since you read it.                                                                                                                                                                    |
| `409`  | `SCRIPTS_API_V2_REQUIRED`       | A V1 script write for an organization on Scripts V2.                                                                                                                                                                        |
| `409`  | (no body)                       | Another write to the same script happened at the same moment. This can happen on save and publish without `expectedRevision` and `expectedConcurrencyVersion`, and on archive and restore. Read the script again and retry. |

Questions about moving to Scripts V2? Contact [support@meetgail.com](mailto:support@meetgail.com).