---
title: "Create draft script version"
method: POST
path: "/api/scripts/{handle}/{host}/{slug}/versions"
---

# Create draft script version

`POST /api/scripts/{handle}/{host}/{slug}/versions`

## Request

- Base URL: `https://reduck.ai`
- URL: `https://reduck.ai/api/scripts/{handle}/{host}/{slug}/versions`
- Auth: one of:
  - HTTP bearer
  - API key in header `X-API-Key`

Add a version to a script as a draft: it does not become the version the script runs until you promote it.

## Path parameters

- `handle` string, required: The owner a resource is addressed under: "@username" for a personal scope, or a bare slug for a project.
- `host` string, required: The site the script automates, as a hostname.
- `slug` string, required: The script's unique identifier within its host, unique per owner.

## Request body

- object
  - `content` string
  - `language` 'typescript' | 'javascript'
  - `parent_version_id` string, uuid: The version this draft continues from. It must belong to this script.
  - `note` string, required
  - `input_schema` object
  - `output_schema` object
  - `logged_in` boolean
  - `side_effects` 'none' | 'write': What running this version does to the site: `none` only reads, `write` acts on it. Declared by the author and never enforced, so treat it as a claim, not a guarantee.

## Response `201`

Created

- object
  - `id` string, required
  - `script_id` string, required
  - `version_number` number, required
  - `parent_version_id` string, nullable, required
  - `language` string, required
  - `logged_in` boolean, required
  - `side_effects` 'none' | 'undetermined' | 'write', required
  - `draft` boolean, required
  - `note` string, nullable: Why this version exists. Omitted on an official script unless you belong to the project that owns it, and never carried by the version a script listing embeds.
  - `created_by` object, nullable, required: Who saved this version. Distinct from the script's `author`, which is the OWNER (a user or a project): a project's script is edited by its members one at a time, and this names the one. Null when that account has since been deleted.
    - `handle` string, required
    - `name` string, required
  - `created_at` string, required
  - `execution_count` number, required
  - `last_run_at` string, nullable, required
  - `success_rate` number, nullable, required
  - `avg_time_ms` number, nullable, required
  - `content` string: The version's source. Omitted on an official script unless you belong to the project that owns it.
  - `input_schema` object, required
  - `output_schema` object, required
  - `libraries` string[]: The libraries the code imports, by host (`lib:<host>`). Read from the code, so withheld with it on an official script from anyone outside the project that owns it.
  - `diff` VersionDiff, required: Diff of a draft against its parent, returned alongside the version on create/patch.
    - `code` string
    - `fields` Recordstringstructure35006733139114203500673313761421350067331367142235006733122814243500673304105, required

## Other responses

- `400`: Invalid request
- `401`: Not authenticated
- `403`: Forbidden
- `404`: Not found
- `409`: The code and contract are identical to the current version, or the script is archived.

---

[API](https://skmtc.dev/reduck/apis/reduck-api.md) · [All operations](https://skmtc.dev/reduck/apis/reduck-api/llms.txt) · [OpenAPI document](https://skmtc.dev/reduck/apis/reduck-api/revisions/a573b91206d6?raw)