---
title: "Save a numscript"
method: PUT
path: "/v3/{ledgerName}/numscripts/{name}"
tags: ["Numscript Library"]
---

# Save a numscript

`PUT /v3/{ledgerName}/numscripts/{name}`

## Request

- Base URL: `http://localhost:9000`
- URL: `http://localhost:9000/v3/{ledgerName}/numscripts/{name}`
- Auth: one of:
  - HTTP bearer
  - none

Appends an immutable version to a ledger's numscript library. The `version`
field must be an explicit full semver (e.g. "1.0.0"); it creates a new
version and fails if that version already exists. The per-name latest is
always the greatest stored semver.

## Path parameters

- `ledgerName` string, required
- `name` string, required

## Request body

- SaveNumscriptRequest
  - `content` string, required: The numscript source code
  - `version` string, required: Explicit full semver (e.g. "1.0.0"). Appends a new immutable version; fails if that version already exists. "latest" and partial selectors are not accepted for save.

## Response `201`

Numscript saved successfully

- GetNumscriptResponse
  - `data` NumscriptInfo, required
    - `name` string, required: Name of the numscript
    - `content` string: The numscript source code
    - `version` string: Semver version string (e.g. "1.0.0")
    - `createdAt` string, date-time: Creation/update timestamp (ISO 8601 format)
    - `ledger` string: Ledger name this numscript belongs to

## Other responses

- `400`: Bad request (version not an explicit full semver, parse error, etc.)
- `401`: Authentication required (missing or invalid JWT token)
- `403`: Insufficient permissions (missing required scope)
- `405`: Method not allowed
- `409`: The version already exists (`NUMSCRIPT_VERSION_ALREADY_EXISTS`) — stored versions are immutable and cannot be overwritten — or the ledger has been deleted (`LEDGER_DELETED`).
- `429`: Resource exhausted. Write admission can reject with `WRITES_BLOCKED_DISK_FULL` while disk pressure blocks writes; `SEQUENCE_EXHAUSTED` means an authoritative identifier allocator cannot allocate another identifier and is permanent for that allocator. Inspect `errorCode` before deciding whether to retry. No retry interval is supplied, and retrying cannot resolve sequence exhaustion.
- `500`: Internal server error
- `503`: Service unavailable — the server cannot serve the request right now but an immediate retry can succeed. The `errorCode` field discriminates the cause: `NO_LEADER` (no elected Raft leader), `CACHE_HORIZON_EXCEEDED` (admission snapshot too old, retry against a fresh one), `UNAVAILABLE` (an internal forwarded stream was torn down mid-transfer), or the reason of any domain error of the unavailable kind (e.g. `INDEX_BUILDING`).

## Changes

- **2026-11-03** `f5e817eca038`: 1 info
  - api operation id `saveNumscript` removed and replaced with `v3SaveNumscript`
- **2026-10-08** `3da23d327316`: 4 info
  - the endpoint scheme security `BearerAuth` was added to the API
  - added the non-success response with the status `401`
  - added the non-success response with the status `403`
  - added the non-success response with the status `429`
- **2026-09-30** `b747efd5cd77`: 1 info
  - endpoint added
- **2026-09-29** `6ff73ac9a6bd`: 1 breaking
  - api path removed without deprecation
- **2026-09-01** `4d28c76b4328`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/formancehq/apis/ledger-api/changes/v3/:ledgerName/numscripts/:name/put.md)

---

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