Save Harbor Saved Query Draft

Beta
Creates or completely replaces the mutable draft for a Harbor saved query. Replacement is complete rather than partial. The next validation or publication uses the replacement SQL, parameter declarations, and validation values. Unknown JSON fields, including fields inside parameter declarations, return `400 Bad Request` before the draft is saved. Use `default_value`, not `default`, for parameter defaults. When you omit a parameter during execution, Polytomic uses its published `default_value`, never its draft validation value. An omitted optional parameter without a default binds SQL `NULL`. A required parameter allows omission when a default exists, but rejects explicit `null` even with a default. For a report window, use a required parameter with a default so omission selects a useful window and explicit `null` is rejected: ```json {"name": "days", "type": "number", "required": true, "default_value": 7} ```

Authentication

AuthorizationBearer
Bearer user API key
OR
AuthorizationBasic

Basic organization-scoped API key

Path parameters

harbor_idstringRequiredformat: "uuid"
Unique identifier of the Harbor.
saved_query_idstringRequiredformat: "uuid"
Unique stable identifier of the saved query.

Headers

X-Polytomic-VersionstringOptional

Request

This endpoint expects an object.
namestringRequired

Human-readable saved-query name. Maximum 200 characters.

sql_templatestringRequired

DuckDB SQL template using {{name}} references for bound parameters.

change_notestring or nullOptional
Optional note copied to the immutable published version.
descriptionstringOptional
Business definition and usage notes. Maximum 2,000 characters.
ownerstringOptional

Human-readable owner label. Maximum 200 characters.

parameterslist of objects or nullOptional
Typed scalar parameter declarations.
validation_valuesmap from strings to any or nullOptional

Author-supplied JSON scalar values used only to validate this draft.

Response

OK
dataobjectOptional

Errors

400
Bad Request Error
403
Forbidden Error
404
Not Found Error
422
Unprocessable Entity Error
500
Internal Server Error