--- title: "Create Hook" method: POST path: "/hooks" tags: ["hooks"] --- # Create Hook `POST /hooks` ## Request - Base URL: `https://example.scalr.io/api/iacp/v3` - URL: `https://example.scalr.io/api/iacp/v3/hooks` - Auth: HTTP bearer Creates a Hook from a VCS repository. The repository is cloned asynchronously, and the specified folder is archived and uploaded to the Blob storage. ## Request body - HookDocument: JSON:API Document. see: https://jsonapi.org/format/#document-structure - `data` Hook: Represents a reusable hook in the Scalr Hooks Registry. - `attributes` object, required - `description` string, nullable: Brief description of the hook's purpose. - `error-message` string, nullable: This field contains the error description, when this hook's status is `errored`. - `hook-blob-id` string, nullable: ID of the blob where hook source code is stored. - `interpreter` string, required: The interpreter used to execute the hook script. Examples: - `bash` - for shell scripts - `python` - for Python scripts - `node` - for JavaScript scripts **Important**: The interpreter specified here must be available in the execution environment. Make sure that the necessary dependencies are installed on the system where the hook will run. Scalr does not automatically install any runtime dependencies. This interpreter will be combined with the `scriptfile_path` to form the complete command to run the hook. - `name` string, required: Unique name for the hook. - `scriptfile-path` string, required: The path to the script file in the repository. This path is relative to the root of the repository. Examples: - `script.sh` - a script in the root directory - `scripts/hook.py` - a script in the scripts subdirectory - `/absolute/path.sh` - leading slash is automatically removed When the hook executes, the script runs in the Terraform workspace directory, not in the hook's directory. To access files within the hook directory, use the `SCALR_HOOK_DIR` environment variable: ```bash # Example: Read a config file from the hook directory cat "$SCALR_HOOK_DIR/config.json" # Example: Execute another script from the hook directory bash "$SCALR_HOOK_DIR/helpers/cleanup.sh" ``` The `interpreter` attribute specifies the command used to execute this script. - `status` 'pending' | 'active' | 'errored': The status of the hook. - `updated-at` string, date-time: Timestamp of the last update. - `vcs-repo` object, required: A reference to the VCS repository for the hook. - `branch` string, nullable: Branch of a repository the hook is associated with. If omitted, the repository default branch will be used. - `identifier` string, required: A reference to the VCS repository. For GitHub, GitHub Enterprise and GitLab the format is `/`. For Azure DevOps Services the format is `//`. - `id` string - `links` object - `self` string - `relationships` object, required - `account` object: The account this hook belongs to. - `data` object, nullable, required - `id` string, required - `type` 'accounts' | '', required - `environments` object: The list of environments this hook is associated with. - `data` object[], nullable, required - `id` string, required - `type` 'environments' | '', required - `readme` object: The readme for the hook. - `data` object, nullable, required - `id` string, required - `type` 'hook-readme' | '', required - `updated-by` object: The user who last updated the hook. - `data` object, nullable, required - `id` string, required - `type` 'users' | '', required - `vcs-provider` object, required: The VCS provider associated with the hook. - `data` object, required - `id` string, required - `type` 'vcs-providers' | '', required - `vcs-revision` object: The Git commit information when the hook was fetched from VCS. - `data` object, nullable, required - `id` string, required - `type` 'vcs-revisions' | '', required - `type` 'hooks', required - `included` object[] - `meta` object ## Response `201` Successfully created hook. - HookDocument: JSON:API Document. see: https://jsonapi.org/format/#document-structure - `data` Hook: Represents a reusable hook in the Scalr Hooks Registry. - `attributes` object, required - `description` string, nullable: Brief description of the hook's purpose. - `error-message` string, nullable: This field contains the error description, when this hook's status is `errored`. - `hook-blob-id` string, nullable: ID of the blob where hook source code is stored. - `interpreter` string, required: The interpreter used to execute the hook script. Examples: - `bash` - for shell scripts - `python` - for Python scripts - `node` - for JavaScript scripts **Important**: The interpreter specified here must be available in the execution environment. Make sure that the necessary dependencies are installed on the system where the hook will run. Scalr does not automatically install any runtime dependencies. This interpreter will be combined with the `scriptfile_path` to form the complete command to run the hook. - `name` string, required: Unique name for the hook. - `scriptfile-path` string, required: The path to the script file in the repository. This path is relative to the root of the repository. Examples: - `script.sh` - a script in the root directory - `scripts/hook.py` - a script in the scripts subdirectory - `/absolute/path.sh` - leading slash is automatically removed When the hook executes, the script runs in the Terraform workspace directory, not in the hook's directory. To access files within the hook directory, use the `SCALR_HOOK_DIR` environment variable: ```bash # Example: Read a config file from the hook directory cat "$SCALR_HOOK_DIR/config.json" # Example: Execute another script from the hook directory bash "$SCALR_HOOK_DIR/helpers/cleanup.sh" ``` The `interpreter` attribute specifies the command used to execute this script. - `status` 'pending' | 'active' | 'errored': The status of the hook. - `updated-at` string, date-time: Timestamp of the last update. - `vcs-repo` object, required: A reference to the VCS repository for the hook. - `branch` string, nullable: Branch of a repository the hook is associated with. If omitted, the repository default branch will be used. - `identifier` string, required: A reference to the VCS repository. For GitHub, GitHub Enterprise and GitLab the format is `/`. For Azure DevOps Services the format is `//`. - `id` string - `links` object - `self` string - `relationships` object, required - `account` object: The account this hook belongs to. - `data` object, nullable, required - `id` string, required - `type` 'accounts' | '', required - `environments` object: The list of environments this hook is associated with. - `data` object[], nullable, required - `id` string, required - `type` 'environments' | '', required - `readme` object: The readme for the hook. - `data` object, nullable, required - `id` string, required - `type` 'hook-readme' | '', required - `updated-by` object: The user who last updated the hook. - `data` object, nullable, required - `id` string, required - `type` 'users' | '', required - `vcs-provider` object, required: The VCS provider associated with the hook. - `data` object, required - `id` string, required - `type` 'vcs-providers' | '', required - `vcs-revision` object: The Git commit information when the hook was fetched from VCS. - `data` object, nullable, required - `id` string, required - `type` 'vcs-revisions' | '', required - `type` 'hooks', required - `included` object[] - `meta` object ## Other responses - `403`: User unauthorized to perform action. - `404`: Relationship resource not found, or user unauthorized to perform action. - `422`: Malformed request or validation error. - `4XX`: Client error. - `5XX`: Server error. ## Changes - **2026-11-03** `d3e1dc85657a`: 1 info - endpoint added [Operation history](https://skmtc.dev/scalr/apis/scalr-iacp-api/changes/hooks/post.md) --- [API](https://skmtc.dev/scalr/apis/scalr-iacp-api.md) - [All operations](https://skmtc.dev/scalr/apis/scalr-iacp-api/llms.txt) - [OpenAPI document](https://skmtc.dev/scalr/apis/scalr-iacp-api/revisions/d3e1dc85657a?raw)