Run Direct Script

Endpoint

When to Use

Run Direct Script is appropriate in the following scenarios:

• Tenant setup operations — one-time initialisation steps performed during tenant onboarding that are executed once and then discarded.
• Data migrations during deployment — inline scripts needed at deploy time that are authored, reviewed, and executed as part of the deployment runbook.
• Emergency fixes — time-critical data corrections that cannot wait for the full stored-script approval cycle. Must be followed up by a post-incident review.

For all other production write operations, use Run Stored Script. It provides a full audit trail, version control, and pre-approval of the SQL that will be executed.

Request Body

Content-Type: application/json

Example Request Body

{
  "sqlScriptText": "UPDATE dbo.EmployeePaySettings SET BaseSalary = @NewSalary WHERE EmployeeID = @EmployeeID AND TenantID = @TenantID",
  "scriptParameters": {
    "NewSalary":  60000,
    "EmployeeID": 42
  }
}

Full Request Example

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

{
  "sqlScriptText": "UPDATE dbo.EmployeePaySettings SET BaseSalary = @NewSalary WHERE EmployeeID = @EmployeeID AND TenantID = @TenantID",
  "scriptParameters": {
    "NewSalary":  60000,
    "EmployeeID": 42
  }
}

Response

On success, the endpoint returns HTTP 200 OK:

{
  "success": true
}

No script code or SQL text is echoed back in the response. No row data is returned. If you need to verify the effect of the script, issue a separate Execute → JSON read call after the write.

Authorization

The caller's JWT must include the TenantAdmin role. Requests with insufficient role are rejected with 403 Forbidden before the SQL is evaluated or executed.

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

Security Considerations

Additional security guidelines for this endpoint:

• Restrict network access to this endpoint — it should not be reachable from untrusted networks or end-user browsers.
• Log all invocations with the caller identity, the full script text, and all parameter values in your operational audit system.
• Never expose this endpoint through a public-facing API gateway or relay it through a less-privileged service.
• If the script will modify sensitive data (PII, payroll figures, credentials), apply a mandatory second-approval workflow in your runbook before calling this endpoint.
• Include AND TenantID = @TenantID in every WHERE clause. Do not rely on data integrity alone — the explicit filter is a defence-in-depth measure.

Comparison — Stored vs Direct

Use this table to select the right endpoint for your use case:

Error Handling