Scripting API Migration Guide#

This guide is for anyone calling the prototype Scripting endpoints under /prototype/platform/scripts and moving to the supported public Scripting API.

The public Scripting API is generally available in the 2026-01-01 version. All the prototype endpoints will work until the prototype sunset in October 2027, so you can migrate one call at a time. Every prototype operation has a public equivalent, so nothing you use will be discontinued.

High-Level Changes#

  • The /prototype/platform prefix is gone. /prototype/platform/scripts becomes /scripts.

  • Send X-Version: 2026-01-01 on every request. Prototype requests sent without an X-Version header were served by 2022-01-01; the public API requires the header.

  • Creating a script no longer creates __main__.py. Create __main__.py, the script entry point, as the first source in every new script. A run without it fails with can't find '__main__' module in '/mnt/'.

  • Starting a run returns a link to an operation, not to the run. Poll the operation once, read the run URL from resourceUrl, then continue polling until the operation finishes.

  • python-failed is no longer a run status. Failures report status: failed plus failureReason and a structured termination object.

  • Script names can now be changed with a replace operation targeting /name.

  • python3.9 can no longer be set. Only python3.13 is accepted when creating or patching a script’s runtime; python3.9 is deprecated and appears only in responses for scripts that already had it.

  • Scripting now has its own scopes. Request script:read, script:write, and script:execute instead of file:read and file:write. See Scopes.

  • The default page size drops from 100 to 50. If you read one page without following @nextLink, you now get fewer results. See The default page size is smaller.

  • Pagination parameters, JSON Patch replace semantics, environment variable handling, and run log and output downloads are unchanged. See Appendix A.

Endpoint Map#

The public API uses new scopes. See Scopes for which scope each operation needs.

Scripts#

Operation

Prototype

Public

Change

List

GET /prototype/platform/scripts

GET /scripts

default page size is 50 instead of 100

Create

POST /prototype/platform/scripts

POST /scripts

no default __main__.py source is created, so you will have to create it first; if you use container (optional), this places the script in a folder; response adds resourceLimits; runtime only accepts python3.13

Get

GET /prototype/platform/scripts/{scriptId}

GET /scripts/{scriptId}

response adds resourceLimits

Patch

PATCH /prototype/platform/scripts/{scriptId}

PATCH /scripts/{scriptId}

adds /name; /description and /runtime remain patchable, but /runtime only accepts python3.13; still one replace operation per request

Sources#

Operation

Prototype

Public

Change

List

GET .../{scriptId}/sources

GET .../{scriptId}/sources

default page size is 50 instead of 100

Create

POST .../{scriptId}/sources

POST .../{scriptId}/sources

response adds created and type

Get

GET .../sources/{sourceId}

GET .../sources/{sourceId}

response adds created and type

Patch

PATCH .../sources/{sourceId}

PATCH .../sources/{sourceId}

none; /path remains the only patchable path

Delete

DELETE .../sources/{sourceId}

DELETE .../sources/{sourceId}

none

Content download

POST .../contentDownload

POST .../contentDownload

adds 204 No Content when the source has no content

Content upload

POST .../contentUpload

POST .../contentUpload

none

Push a source tree

not available

POST .../sources/sync

new

Pull a source tree

not available

POST .../sources/export

new

Runs#

Operation

Prototype

Public

Change

Execute

POST .../{scriptId}/execution

POST .../{scriptId}/execution

breaking: changes response contract. Location now points at an operation, not the run. See Polling operations

List

GET .../{scriptId}/runs

GET .../{scriptId}/runs

adds type, $filter on started.dateTime and type, and dependency runs in the same collection; default page size is 50 instead of 100

Get

GET .../runs/{runId}

GET .../runs/{runId}

python-failed removed from status; adds type, termination, resourceUsage, resourceLimits, dependencyState, and duration fields

Cancel

POST .../runs/{runId}/cancellation

POST .../runs/{runId}/cancellation

none

Logs download

POST .../runs/{runId}/logsDownload

POST .../runs/{runId}/logsDownload

none

Output download

POST .../runs/{runId}/outputDownload

POST .../runs/{runId}/outputDownload

none

Dependencies#

Dependency management was never exposed in the prototype API. It is new, and dependency generation produces a run in the same collection as your script runs, distinguished by type: dependency.

Operation

Public

Generate a bundle

POST /scripts/{scriptId}/dependencies/generation

Read a dependency run

GET /scripts/{scriptId}/runs/{runId}

Cancel a dependency run

POST /scripts/{scriptId}/runs/{runId}/cancellation

Read dependency generation logs

POST /scripts/{scriptId}/runs/{runId}/logsDownload

Permissions#

Operation

Prototype

Public

Change

Get permissions

GET .../{scriptId}/permissions

GET .../{scriptId}/permissions

none

Modify permissions

POST .../{scriptId}/permissions/modification

POST .../{scriptId}/permissions/modification

none

Behavior Changes#

The Python examples use requests and assume this setup:

import os
import time

import requests

API_BASE = "https://api.app.wdesk.com"
AUTH_HEADERS = {"Authorization": f"Bearer {os.environ['TOKEN']}"}
PUBLIC_HEADERS = {
    **AUTH_HEADERS,
    "X-Version": "2026-01-01",
}

Paths and the version header#

Migration Steps#

  1. Remove the /prototype/platform prefix from every Scripting request path.

  2. Add X-Version: 2026-01-01 to every request, including your token request.

Examples#

curl#

Prototype

curl -X GET "https://api.app.wdesk.com/prototype/platform/scripts" \
  -H "Authorization: Bearer ${TOKEN}"

Public

curl -X GET "https://api.app.wdesk.com/scripts" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "X-Version: 2026-01-01"
Python#

Prototype

response = requests.get(
    f"{API_BASE}/prototype/platform/scripts",
    headers=AUTH_HEADERS,
    timeout=30,
)
response.raise_for_status()

Public

response = requests.get(
    f"{API_BASE}/scripts",
    headers=PUBLIC_HEADERS,
    timeout=30,
)
response.raise_for_status()

Scopes#

The prototype endpoints accepted file:read and file:write. The public Scripting endpoints require dedicated script scopes, and a token with only file:read or file:write receives 401 Unauthorized.

Prototype scope

Public scope

Operations

file:read

script:read

List and get scripts, sources, and runs; content download; source export; logs and output download; get permissions

file:write

script:write

Create and patch scripts; create, patch, and delete sources; content upload; source sync; modify permissions

file:write

script:execute

Execute; cancel a run; generate dependencies

script:execute also accepts the read endpoints needed to run a script and get its output: list and get scripts and runs, and download run logs and output. These endpoints still accept script:read. script:execute does not grant access to source or permissions endpoints.

Migration Steps#

  1. Ask your account administrator to add script:read, script:write, and script:execute, as needed, to your OAuth grant.

  2. If you pass scope when calling POST /oauth2/token, replace file:read and file:write with the script scopes. If you omit scope, the token carries every scope in your grant.

Examples#

curl#
curl -X POST "https://api.app.wdesk.com/oauth2/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -H "X-Version: 2026-01-01" \
  -d "client_id=${CLIENT_ID}" \
  -d "client_secret=${CLIENT_SECRET}" \
  -d "grant_type=client_credentials" \
  --data-urlencode "scope=script:read script:write script:execute"

Polling operations instead of the run#

This is the change that affects the most code. In the prototype API, starting a run returned a Location header pointing straight at the new run, so you had the run ID immediately. The public API returns a link to an operation instead. Poll it once to get the run URL from resourceUrl. The URL is available while the run is queued or started, so you can monitor or cancel the run before the operation finishes.

Scripting uses the standard Workiva GET /operations/{operationId} endpoint for polling. Poll the URL returned by the Scripting response and continue sending X-Version: 2026-01-01.

Dependency generation also exposes its run URL before completion. Source upload and sync expose resources that already exist; source export exposes its generated ZIP URL only when the operation completes.

Migration Steps#

  1. Read operationLocation from the 202 response body, or the Location header, instead of treating Location as a run URL.

  2. Poll that URL and take the run URL from resourceUrl as soon as it appears.

  3. Use that URL to read or cancel the run, and continue polling the operation until status is completed, failed, or cancelled, honoring Retry-After between attempts.

Examples#

curl#

Prototype. The run URL arrives in the first response

curl -i -X POST "https://api.app.wdesk.com/prototype/platform/scripts/${SCRIPT_ID}/execution" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{"apiKey": "Az86pm34xyz"}'

HTTP/1.1 202 Accepted
Location: https://api.app.wdesk.com/prototype/platform/scripts/{scriptId}/runs/{runId}
Retry-After: 5

Public. The first response points at an operation

curl -i -X POST "https://api.app.wdesk.com/scripts/${SCRIPT_ID}/execution" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -H "X-Version: 2026-01-01" \
  -d '{"apiKey": "Az86pm34xyz"}'

HTTP/1.1 202 Accepted
Location: https://api.app.wdesk.com/operations/128f274395254cf17eda6b3eb3d021b9
Retry-After: 5

{
  "operationLocation": "https://api.app.wdesk.com/operations/128f274395254cf17eda6b3eb3d021b9"
}

Poll it once and read the run URL from resourceUrl

curl -X GET "https://api.app.wdesk.com/operations/128f274395254cf17eda6b3eb3d021b9" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "X-Version: 2026-01-01"

{
  "id": "128f274395254cf17eda6b3eb3d021b9",
  "status": "started",
  "resourceUrl": "/scripts/ae82b647-8e43-44c3-a4e7-2aa3294c87ac/runs/8e1f2c90-3d4b-4a11-9c77-1b2a3c4d5e6f"
}

Keep polling the operation until it reaches a terminal status. Poll the URL you were given rather than assembling one from an ID.

Python#

Prototype

started = requests.post(
    f"{API_BASE}/prototype/platform/scripts/{os.environ['SCRIPT_ID']}/execution",
    headers=AUTH_HEADERS,
    json={"apiKey": "Az86pm34xyz"},
    timeout=30,
)
started.raise_for_status()
run_url = started.headers["Location"]

Public

started = requests.post(
    f"{API_BASE}/scripts/{os.environ['SCRIPT_ID']}/execution",
    headers=PUBLIC_HEADERS,
    json={"apiKey": "Az86pm34xyz"},
    timeout=30,
)
started.raise_for_status()
operation_url = started.json()["operationLocation"]

run_url = None
while True:
    polled = requests.get(operation_url, headers=PUBLIC_HEADERS, timeout=30)
    polled.raise_for_status()
    operation = polled.json()
    run_url = operation.get("resourceUrl", run_url)
    if operation["status"] in {"completed", "failed", "cancelled"}:
        break
    time.sleep(int(polled.headers.get("Retry-After", "5")))

The default page size is smaller#

List operations now return 50 items per page by default instead of 100. $maxpagesize still accepts 1 to 1000.

Migration Steps#

  1. Follow @nextLink until it is absent, or send $maxpagesize explicitly if you rely on a fixed page size.

Examples#

curl#
curl -G "https://api.app.wdesk.com/scripts" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "X-Version: 2026-01-01" \
  --data-urlencode '$maxpagesize=100'

The run status vocabulary is narrower#

python-failed has been removed. A Python error now reports status: failed with failureReason: "Python failure". When a run ends abnormally, for example by hitting a memory, disk, or time limit, it also carries a structured termination object that the prototype status enum could not express.

Migration Steps#

  1. Remove any branch that tests for python-failed.

  2. Branch on the six remaining values: acknowledged, queued, started, completed, cancelled, failed.

  3. Read failureReason for failure detail. termination is present only when the run terminated abnormally; when it is, use termination.type and termination.reason for logic. failureReason is human-readable.

Examples#

Response comparison#

Prototype

{
  "id": "8e1f2c90-3d4b-4a11-9c77-1b2a3c4d5e6f",
  "status": "python-failed",
  "failureReason": "Python failure"
}

Public, for a Python error

{
  "id": "8e1f2c90-3d4b-4a11-9c77-1b2a3c4d5e6f",
  "type": "script",
  "status": "failed",
  "failureReason": "Python failure"
}

Public, for a run that exceeded its time limit

{
  "id": "8e1f2c90-3d4b-4a11-9c77-1b2a3c4d5e6f",
  "type": "script",
  "status": "failed",
  "failureReason": "Timed out",
  "termination": {
    "type": "resource_limit_exceeded",
    "reason": "allocated_time_exceeded",
    "signal": "SIGTERM",
    "code": "TIMEOUT[SIGTERM]",
    "message": "Script exceeded allocation time limit.",
    "gracePeriodSeconds": 15
  }
}
Python#

Prototype

if run["status"] == "python-failed":
    handle_failure(run["failureReason"])

Public

if run["status"] == "failed":
    termination = run.get("termination", {})
    handle_failure(
        run.get("failureReason"),
        termination.get("type"),
        termination.get("reason"),
    )

Dependency generation is explicit#

If you manage requirements.txt through the source endpoints, note that nothing regenerates the dependency bundle for you. After changing requirements.txt or a script’s runtime, call POST /scripts/{scriptId}/dependencies/generation, or the next run uses a stale dependencies.zip.

Migration Steps#

  1. Call dependency generation after any change to requirements.txt or runtime.

  2. Poll the returned operation and read the dependency run from resourceUrl as soon as it appears; continue polling until the operation finishes.

  3. Check dependencyState.requirementsInSync and dependencyState.runtimeInSync on a run to confirm it used a current bundle.

Example#

There is no example for this using curl.

Python#

Prototype runtime patches started dependency generation implicitly

requests.patch(
    f"{API_BASE}/prototype/platform/scripts/{os.environ['SCRIPT_ID']}",
    headers=AUTH_HEADERS,
    json=[{"op": "replace", "path": "/runtime", "value": "python3.13"}],
    timeout=30,
).raise_for_status()

Public clients must make the generation request explicitly

requests.patch(
    f"{API_BASE}/scripts/{os.environ['SCRIPT_ID']}",
    headers=PUBLIC_HEADERS,
    json=[{"op": "replace", "path": "/runtime", "value": "python3.13"}],
    timeout=30,
).raise_for_status()

generation = requests.post(
    f"{API_BASE}/scripts/{os.environ['SCRIPT_ID']}/dependencies/generation",
    headers=PUBLIC_HEADERS,
    timeout=30,
)
generation.raise_for_status()
operation_url = generation.json()["operationLocation"]

Rate limiting#

429 Too Many Requests is a documented response on every Scripting operation. Add retry with backoff, and honor Retry-After. Polling an operation can be limited to one request per second.

Migration Checklist#

  1. Remove the /prototype/platform prefix from all Scripting paths.

  2. Add X-Version: 2026-01-01 to every request.

  3. Add script:read, script:write, and script:execute to your OAuth grant and to any scope you send to POST /oauth2/token.

  4. After creating a script, create __main__.py as its first source.

  5. Replace run-URL handling on execution with operation polling, and take the run URL from resourceUrl as soon as it appears.

  6. Follow @nextLink, or send $maxpagesize, wherever you relied on the default page size of 100.

  7. Remove python-failed handling; branch on the six statuses and read failureReason, plus termination when present, for detail.

  8. Call dependency generation explicitly after changing requirements.txt or runtime.

  9. Add retry with backoff for 429.

  10. Stop creating or patching scripts with runtime: python3.9; only python3.13 is accepted.

  11. Optional: replace per-file source loops with sources/sync and sources/export.

  12. Optional: pass container on create to place new scripts in a folder.

  13. Optional: use $filter on started.dateTime or type when listing runs instead of paging through full history.

Appendix A: What Has Not Changed From the Prototype API#

If you use the prototype endpoints, you can keep this code as it is.

Authentication

OAuth 2.0 client credentials from POST /oauth2/token, sent as Authorization: Bearer {token}.

Base URLs

https://api.app.wdesk.com, plus the eu, apac, and ca equivalents.

Pagination

Requests take $maxpagesize and $next; responses carry data and @nextLink. $maxpagesize still accepts 1 to 1000, and @nextLink is still absent on the last page. The default page size changed; see The default page size is smaller.

Cancellation

POST .../runs/{runId}/cancellation still returns 204 No Content.

Run download responses

logsDownload and outputDownload still return 200 OK with {"downloadUrl": "..."}, and still return 204 No Content when there is nothing to download. Presigned URLs are still short-lived.

Content upload

Still 202 Accepted with uploadUrl in the body and an operation to poll in the Location header.

JSON Patch

Still one replace operation per request. /description and /runtime remain patchable on a script, and /path remains patchable on a source.

Execution parameters

Request body properties still become environment variables in capitalized snake case, so apiKey becomes API_KEY. Values must be strings.

Output capture

print("::set-output ...") still populates run output.

Script state

Still active, trashed, or purged, and still read-only. There was no way to delete or trash a script through the prototype API and there is none in the public API.

Error body

{"code", "message", "target", "details"} with the same codes.

Limits

Request payloads are still capped at 10 MB, which is why content moves through presigned URLs.