Save Harbor Saved Query Draft

Beta

PUT

https://app.polytomic.com/api/harbors/:harbor_id/saved-queries/:saved_query_id/draft

PUT

/api/harbors/:harbor_id/saved-queries/:saved_query_id/draft

curl -X PUT https://app.polytomic.com/api/harbors/248df4b7-aa70-47b8-a036-33ac447e668d/saved-queries/248df4b7-aa70-47b8-a036-33ac447e668d/draft \
     -H "Authorization: Bearer <token>" \
     -H "Content-Type: application/json" \
     -d '{
  "name": "Monthly revenue",
  "sql_template": "SELECT account_id, sum(amount) AS revenue FROM orders WHERE created_at >= {{start_date}} GROUP BY account_id"
}'

{
  "data": {
    "change_note": "string",
    "created_at": "2024-01-15T09:30:00Z",
    "created_by": "248df4b7-aa70-47b8-a036-33ac447e668d",
    "created_by_type": "string",
    "description": "string",
    "id": "248df4b7-aa70-47b8-a036-33ac447e668d",
    "name": "string",
    "owner": "string",
    "parameters": [
      {
        "name": "start_date",
        "type": "string",
        "default_value": null,
        "required": true
      }
    ],
    "saved_query_id": "248df4b7-aa70-47b8-a036-33ac447e668d",
    "sql_template": "string",
    "updated_at": "2024-01-15T09:30:00Z",
    "updated_by": "248df4b7-aa70-47b8-a036-33ac447e668d",
    "updated_by_type": "string",
    "validation_values": {}
  }
}

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:

{"name": "days", "type": "number", "required": true, "default_value": 7}

Authentication

AuthorizationBearer

Bearer user API key

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

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

dataobjectOptional

The saved query draft

Errors

400

Bad Request Error

403

Forbidden Error

404

Not Found Error

422

Unprocessable Entity Error

500

Internal Server Error

Authentication

Path parameters

Headers

Request

Response

Errors