Run Stored Script — Multi-Query Engine

Endpoint

Method	URL
POST	`/api/v1/expressions/multiquery/scripts/run-stored`

When to Use

The Run Stored Script operation executes a SQL script that has been reviewed, approved, and stored in dbo.Shared_Configurations under a known catalogue code. It is the recommended approach for all production write operations triggered from workflows, scheduled jobs, or user-initiated actions.

Pre-Approved

Scripts are reviewed and stored by a platform administrator before they can be called. No ad-hoc SQL can be injected by a caller — only the stored script text is executed.

Audited

Every invocation is logged with the caller's TenantID, the catalogue code, the resolved parameters, and the timestamp. Audit records are immutable and available to platform administrators.

Version-Controlled

Scripts live in dbo.Shared_Configurations alongside your Multi-Query read templates. Schema migrations, code reviews, and rollbacks can be managed through the same configuration pipeline.

Parameterised

Callers supply runtime values via scriptParameters. TenantID is always injected from the JWT — callers cannot supply or override it, ensuring operations are always scoped to the correct tenant.

Stored vs Direct — Which to Choose?

Use Run Stored Script when the SQL operation is a known, repeatable business action (e.g. initialising a pay period, archiving records, triggering a batch recalculation). Use Run Direct Script only for ad-hoc setup or emergency recovery operations where storing the script in advance is impractical. See the full comparison on the Run Direct Script page.

Request Body

Content-Type: application/json

Field	Type	Required	Description
`scriptCatalogueCode`	string	Yes	The catalogue code identifying the stored script in `dbo.Shared_Configurations`. Case-insensitive.
`scriptParameters`	object	No	Key-value map of named parameters to inject into the script. Values must match the expected SQL parameter types declared in the script. `TenantID` must not be included here — it is always injected from the JWT.

Example Request Body

{
  "scriptCatalogueCode": "INITIALIZE_TENANT_PAYROLL",
  "scriptParameters": {
    "PayPeriodStart": "2026-05-01",
    "PayPeriodEnd":   "2026-05-31"
  }
}

Full Request Example

POST /api/v1/expressions/multiquery/scripts/run-stored
Authorization: Bearer eyJ...
Content-Type: application/json

{
  "scriptCatalogueCode": "INITIALIZE_TENANT_PAYROLL",
  "scriptParameters": {
    "PayPeriodStart": "2026-05-01",
    "PayPeriodEnd":   "2026-05-31"
  }
}

TenantID is Automatic

Do not include TenantID in scriptParameters. It is always extracted from the caller's JWT and injected into the script as @TenantID automatically. Including it manually will result in a validation error.

Response

On success, the endpoint returns HTTP 200 OK with the following body:

{
  "success": true,
  "scriptCatalogueCode": "INITIALIZE_TENANT_PAYROLL"
}

The response confirms which script was executed. No SQL result rows are returned — this endpoint is designed for write/mutation operations only. If you need to read data after a write, issue a separate Execute → JSON call.

Storing a Script

Scripts are stored in dbo.Shared_Configurations with a Type of 'SqlScript'. The Value column holds the parameterised SQL text. The Code column becomes the scriptCatalogueCode referenced in API calls.

INSERT INTO dbo.Shared_Configurations
    (Code, Type, Value, TenantID, CreatedOn, CreatedBy)
VALUES
    (
        'INITIALIZE_TENANT_PAYROLL',
        'SqlScript',
        'INSERT INTO dbo.PayPeriods (TenantID, PeriodStart, PeriodEnd, Status)
         VALUES (@TenantID, @PayPeriodStart, @PayPeriodEnd, ''Open'')',
        @AdminTenantID,
        GETUTCDATE(),
        @AdminUserID
    );

All stored scripts should follow the same change-management process as application code: peer review, testing in a non-production environment, and documented approval before being deployed to production tenants.

Authorization

The caller's JWT must include the TenantAdmin role. Requests without this role are rejected with 403 Forbidden.

This endpoint is protected by the ApiLimit("MultiQuery.RunStoredScript") rate limit policy. Limits are configured per tenant by a platform administrator.

Error Handling

HTTP Status	Error Condition	Resolution
`400 Bad Request`	Missing required script parameter	Add the missing parameter to `scriptParameters`. The error response body names the missing parameter.
`400 Bad Request`	TenantID supplied in scriptParameters	Remove `TenantID` from `scriptParameters` — it is injected automatically.
`401 Unauthorized`	Missing or invalid JWT	Obtain a fresh token and retry.
`403 Forbidden`	Caller lacks TenantAdmin role	Request elevation or use a service account with the correct role.
`404 Not Found`	Script catalogue code not found	Verify the `scriptCatalogueCode` matches a record in `dbo.Shared_Configurations` for the caller's tenant.
`429 Too Many Requests`	Rate limit exceeded	Wait for the `Retry-After` interval before retrying.
`500 Internal Server Error`	SQL execution error	Check the error response body for the underlying SQL error message. Review the script for logic or constraint violations.

Security Requirement

Scripts execute with the permissions of the API service account, which typically has broad write access across tenant data. Scripts must be reviewed and approved by a qualified administrator before being stored in the catalogue. Never store untrusted, unreviewed, or externally supplied SQL in the catalogue. Treat stored scripts with the same rigour as application source code.

Execute → HTML Run Direct Script