Create Harbor Saved Query Draft

Beta
Creates a stable Harbor saved query with its initial mutable draft. Saved queries are supported only for Polytomic-managed Harbors whose backing Connection type is `polytomic_harbor`. Customer-managed Harbor backings return an unsupported-backing error. The saved query receives a stable ID, but it remains absent from published saved-query reads until an administrator publishes its initial draft. Use `{{parameter_name}}` references in `sql_template`. Each reference must have one scalar declaration. Validation values and defaults must match the declared `string`, `number`, `boolean`, `date`, `timestamp`, or `uuid` type. 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.

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