ALTER API ENDPOINT

Modifies an existing API endpoint definition. Supports merging OPTIONS, changing the URL, changing the response format, and renaming.

Category: api-endpointPrivilege: adminDeltaForge extension

Syntax

ALTER API ENDPOINT [IF EXISTS] <name>
  { SET OPTIONS (<key> = '<value>', ...)
  | SET URL '<path>'
  | SET RESPONSE FORMAT { JSON | XML }
  | RENAME TO <new_name> } ...

Description

## Overview ALTER API ENDPOINT mutates an existing endpoint in-place. It is the only supported path for changing URL, response format, OPTIONS, or name, the row cannot be updated by editing the catalog directly. Multiple actions in a single statement are applied in order as one atomic update. ## Supported actions - **SET OPTIONS (...)**, merge the supplied keys over the existing option map. Keys already present are overwritten; keys not mentioned are preserved. The secret-reject list is re-checked, so you cannot smuggle auth material in via ALTER. - **SET URL '<path>'**, replace the URL template. Any {placeholder} that no current path_param.* or USING (...) override fills will break future invocations. - **SET RESPONSE FORMAT { JSON | XML }**, change the landed-file extension. Existing files keep their original extension; only future runs are affected. - **RENAME TO <new_name>**, change the three-part name. The new <zone>.<api> prefix must still point at an existing rest_api connection; the leaf must be unique within it. ## Access Control Requires the admin role. ## Compatibility DeltaForge extension.

Parameters

Name	Type	Description
`name`		Target endpoint as <zone>.<api>.<name>.
`actions`		One or more actions applied in order. SET OPTIONS merges over the existing option map (new keys overwrite, absent keys are preserved). Use SET OPTIONS with an empty-string value to blank a single key.
`if_exists`		When true, silently no-op if the endpoint does not exist.

Examples

-- Narrow which issues are fetched without touching pagination settings
ALTER API ENDPOINT landing.github.issues
  SET OPTIONS ('query_param.state' = 'closed', 'query_param.labels' = 'bug');

-- Point the same endpoint at a different URL on the same connection
ALTER API ENDPOINT landing.github.issues
  SET URL '/repos/{owner}/{repo}/pulls'
  SET OPTIONS ('pagination.strategy' = 'link_header');

-- Rename to match a new naming convention
ALTER API ENDPOINT landing.github.issues
  RENAME TO landing.github.repo_issues;

Pitfalls

SET OPTIONS is a merge, not a replace. To remove a stored key you must set it to the empty string; simply omitting it preserves the existing value. Use DESCRIBE API ENDPOINT afterwards to confirm the resolved option map.
Renaming does NOT move already-landed files in the storage zone, those keep their original per-run folder path. Future INVOKE runs write under the new name's path; mixed layouts are the operator's problem.
Changing RESPONSE FORMAT after files have been landed produces a mixed-extension directory. The downstream external table's format selection should be revisited to match the file set it will now scan.