--- title: "List all numscripts" method: GET path: "/v3/{ledgerName}/numscripts" tags: ["Numscript Library"] --- # List all numscripts `GET /v3/{ledgerName}/numscripts` ## Request - Base URL: `http://localhost:9000` - URL: `http://localhost:9000/v3/{ledgerName}/numscripts` - Auth: one of: - HTTP bearer - none Lists every numscript of a ledger at its greatest stored version, paged by name (ascending unless `reverse=true`). ## Path parameters - `ledgerName` string, required ## Query parameters - `pageSize` integer - `cursor` string: Page token of a paged list. Clients normally pass back the `next` or `previous` value of a previous response verbatim; building one by hand is supported. A token is base64url (unpadded, RFC 4648 §5) of the JSON object `{"key": , "back": }`. Both fields are omitted when empty, and unknown fields are rejected. `key` is a position in the endpoint's textual form: - transactions: decimal transaction id - logs: decimal ledger-local log id - audit entries: decimal audit sequence - accounts: address - ledgers and numscripts: name - signing keys: key id - prepared queries: decimal id for TRANSACTIONS and LOGS targets, address for ACCOUNTS - index inspection: base64url of the encoded metadata value Both directions exclude the key and return rows in the requested order (`reverse` included): - `{"key": K}` serves the rows strictly after K; - `{"key": K, "back": true}` serves the page that ends strictly before K; - `{"back": true}` serves the last page; - an absent or empty token, or `e30` (`{}`), serves the first page. On a forward page, `next` is set when a further row follows the page, and `previous` whenever the request carried a key. On a back page, `previous` is set when a further row precedes the page, and `next` whenever the request carried a key. A first page therefore has no `previous`, and the last page requested with `{"back": true}` has no `next`. A malformed token, or a key that is not a valid position for the endpoint, is rejected with 400 `INVALID_REQUEST`. - `reverse` boolean ## Headers - `X-Consistency` 'linearizable' | 'stale' ## Response `200` List of numscripts retrieved successfully - ListNumscriptsResponse - `data` NumscriptInfo[], required: One page of numscripts, in the requested name order - `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 - `next` string: Page token of a paged list. Clients normally pass back the `next` or `previous` value of a previous response verbatim; building one by hand is supported. A token is base64url (unpadded, RFC 4648 §5) of the JSON object `{"key": , "back": }`. Both fields are omitted when empty, and unknown fields are rejected. `key` is a position in the endpoint's textual form: - transactions: decimal transaction id - logs: decimal ledger-local log id - audit entries: decimal audit sequence - accounts: address - ledgers and numscripts: name - signing keys: key id - prepared queries: decimal id for TRANSACTIONS and LOGS targets, address for ACCOUNTS - index inspection: base64url of the encoded metadata value Both directions exclude the key and return rows in the requested order (`reverse` included): - `{"key": K}` serves the rows strictly after K; - `{"key": K, "back": true}` serves the page that ends strictly before K; - `{"back": true}` serves the last page; - an absent or empty token, or `e30` (`{}`), serves the first page. On a forward page, `next` is set when a further row follows the page, and `previous` whenever the request carried a key. On a back page, `previous` is set when a further row precedes the page, and `next` whenever the request carried a key. A first page therefore has no `previous`, and the last page requested with `{"back": true}` has no `next`. A malformed token, or a key that is not a valid position for the endpoint, is rejected with 400 `INVALID_REQUEST`. - `previous` string: Page token of a paged list. Clients normally pass back the `next` or `previous` value of a previous response verbatim; building one by hand is supported. A token is base64url (unpadded, RFC 4648 §5) of the JSON object `{"key": , "back": }`. Both fields are omitted when empty, and unknown fields are rejected. `key` is a position in the endpoint's textual form: - transactions: decimal transaction id - logs: decimal ledger-local log id - audit entries: decimal audit sequence - accounts: address - ledgers and numscripts: name - signing keys: key id - prepared queries: decimal id for TRANSACTIONS and LOGS targets, address for ACCOUNTS - index inspection: base64url of the encoded metadata value Both directions exclude the key and return rows in the requested order (`reverse` included): - `{"key": K}` serves the rows strictly after K; - `{"key": K, "back": true}` serves the page that ends strictly before K; - `{"back": true}` serves the last page; - an absent or empty token, or `e30` (`{}`), serves the first page. On a forward page, `next` is set when a further row follows the page, and `previous` whenever the request carried a key. On a back page, `previous` is set when a further row precedes the page, and `next` whenever the request carried a key. A first page therefore has no `previous`, and the last page requested with `{"back": true}` has no `next`. A malformed token, or a key that is not a valid position for the endpoint, is rejected with 400 `INVALID_REQUEST`. - `hasMore` boolean, required: True when a following page exists; set iff `next` is. ## Other responses - `400`: Bad request - `401`: Authentication required (missing or invalid JWT token) - `403`: Insufficient permissions (missing required scope) - `404`: Not found - `405`: Method not allowed - `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 `listNumscripts` removed and replaced with `v3ListNumscripts` - **2026-10-08** `3da23d327316`: 3 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` - **2026-10-08** `b3ee1959d86a`: 1 info - added the new optional `header` request parameter `X-Consistency` - **2026-10-08** `21be46727a2f`: 6 info - added the new optional `query` request parameter `cursor` - added the new optional `query` request parameter `pageSize` - added the new optional `query` request parameter `reverse` - added the optional property `next` to the response with the `200` status - …2 more - **2026-10-06** `6413bb242a30`: 2 breaking, 5 warning - the response property `data` became nullable for the status `200` - removed the required property `hasMore` from the response with the `200` status - deleted the `query` request parameter `cursor` - deleted the `query` request parameter `pageSize` - …3 more [Operation history](https://skmtc.dev/formancehq/apis/ledger-api/changes/v3/:ledgerName/numscripts/get.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)