---
title: "Create or update Scaffolder template"
method: POST
path: "/api/v1/scaffolders"
tags: ["Scaffolder"]
---

# Create or update Scaffolder template

`POST /api/v1/scaffolders`

## Request

- Base URL: `https://api.getcortexapp.com`
- URL: `https://api.getcortexapp.com/api/v1/scaffolders`
- Auth: HTTP bearer

Create or update a Scaffolder template.

API key must have the `Configure Scaffolder` permission.

**Note:** If a Scaffolder template with the same tag already exists, it will be updated.

## Request body

- ScaffolderRequest
  - `createYamlFile` boolean, required: Whether a cortex.yaml is generated for the created entity. Defaults to `true`
  - `description` string: Description of the Scaffolder template
  - `labels` string[], required: Descriptive labels used to group templates in the UI
  - `name` string, required: Display name of the Scaffolder template
  - `publisherOptions` union
    - AzureDevops: Options applied to the repository the Scaffolder publishes to
      - `provider` 'GITHUB' | 'GITLAB' | 'BITBUCKET' | 'AZUREDEVOPS', required: The git provider the options apply to
    - Bitbucket: Options applied to the repository the Scaffolder publishes to
      - `provider` 'GITHUB' | 'GITLAB' | 'BITBUCKET' | 'AZUREDEVOPS', required: The git provider the options apply to
      - `visibility` 'PUBLIC' | 'PRIVATE': Visibility of the created repository
    - Github: Options applied to the repository the Scaffolder publishes to
      - `provider` 'GITHUB' | 'GITLAB' | 'BITBUCKET' | 'AZUREDEVOPS', required: The git provider the options apply to
      - `sparseCheckout` boolean, required: Whether the destination is cloned with sparse checkout
      - `visibility` 'PUBLIC' | 'PRIVATE' | 'INTERNAL': Visibility of the created repository
    - Gitlab: Options applied to the repository the Scaffolder publishes to
      - `provider` 'GITHUB' | 'GITLAB' | 'BITBUCKET' | 'AZUREDEVOPS', required: The git provider the options apply to
      - `visibility` 'PUBLIC' | 'PRIVATE': Visibility of the created repository
  - `repoLocator` union, required
    - AzureDevops: Options applied to the repository the Scaffolder publishes to
      - `provider` 'GITHUB' | 'GITLAB' | 'BITBUCKET' | 'AZUREDEVOPS', required: The git provider the options apply to
    - Bitbucket: Options applied to the repository the Scaffolder publishes to
      - `provider` 'GITHUB' | 'GITLAB' | 'BITBUCKET' | 'AZUREDEVOPS', required: The git provider the options apply to
      - `visibility` 'PUBLIC' | 'PRIVATE': Visibility of the created repository
    - Github: Options applied to the repository the Scaffolder publishes to
      - `provider` 'GITHUB' | 'GITLAB' | 'BITBUCKET' | 'AZUREDEVOPS', required: The git provider the options apply to
      - `sparseCheckout` boolean, required: Whether the destination is cloned with sparse checkout
      - `visibility` 'PUBLIC' | 'PRIVATE' | 'INTERNAL': Visibility of the created repository
    - Gitlab: Options applied to the repository the Scaffolder publishes to
      - `provider` 'GITHUB' | 'GITLAB' | 'BITBUCKET' | 'AZUREDEVOPS', required: The git provider the options apply to
      - `visibility` 'PUBLIC' | 'PRIVATE': Visibility of the created repository
  - `requireNewService` boolean, required: Whether running the template must create a new entity. Defaults to `true`
  - `requirePullRequest` boolean, required: Whether the template publishes via a pull request to an existing repository. Defaults to `false`
  - `showReadme` boolean, required: Whether the template repository's README is shown before a run. Defaults to `false`
  - `strictAliasUsage` boolean, required: Whether runs are restricted to the git configuration alias the template names. Defaults to `true`
  - `tag` string: Stable, human-readable identifier, unique within the workspace. Lowercase letters, numbers, and dashes; may not start or end with a dash. Derived from the name when omitted on creation; an existing template keeps its tag unless a new one is provided.
  - `type` 'COOKIECUTTER', required: The templating engine of the template

## Response `200`

Scaffolder template created or updated successfully

- ScaffolderResponse
  - `createYamlFile` boolean, required: Whether a cortex.yaml is generated for the created entity
  - `createdAt` string, required: ISO-8601 timestamp at which the template was registered
  - `description` string: Description of the Scaffolder template
  - `id` string, required: Unique, auto-generated Cortex ID of the Scaffolder template
  - `labels` string[], required: Descriptive labels used to group templates in the UI
  - `name` string, required: Display name of the Scaffolder template
  - `publisherOptions` union
    - AzureDevops: Options applied to the repository the Scaffolder publishes to
      - `provider` 'GITHUB' | 'GITLAB' | 'BITBUCKET' | 'AZUREDEVOPS', required: The git provider the options apply to
    - Bitbucket: Options applied to the repository the Scaffolder publishes to
      - `provider` 'GITHUB' | 'GITLAB' | 'BITBUCKET' | 'AZUREDEVOPS', required: The git provider the options apply to
      - `visibility` 'PUBLIC' | 'PRIVATE': Visibility of the created repository
    - Github: Options applied to the repository the Scaffolder publishes to
      - `provider` 'GITHUB' | 'GITLAB' | 'BITBUCKET' | 'AZUREDEVOPS', required: The git provider the options apply to
      - `sparseCheckout` boolean, required: Whether the destination is cloned with sparse checkout
      - `visibility` 'PUBLIC' | 'PRIVATE' | 'INTERNAL': Visibility of the created repository
    - Gitlab: Options applied to the repository the Scaffolder publishes to
      - `provider` 'GITHUB' | 'GITLAB' | 'BITBUCKET' | 'AZUREDEVOPS', required: The git provider the options apply to
      - `visibility` 'PUBLIC' | 'PRIVATE': Visibility of the created repository
  - `repoLocator` union, required
    - AzureDevops: Options applied to the repository the Scaffolder publishes to
      - `provider` 'GITHUB' | 'GITLAB' | 'BITBUCKET' | 'AZUREDEVOPS', required: The git provider the options apply to
    - Bitbucket: Options applied to the repository the Scaffolder publishes to
      - `provider` 'GITHUB' | 'GITLAB' | 'BITBUCKET' | 'AZUREDEVOPS', required: The git provider the options apply to
      - `visibility` 'PUBLIC' | 'PRIVATE': Visibility of the created repository
    - Github: Options applied to the repository the Scaffolder publishes to
      - `provider` 'GITHUB' | 'GITLAB' | 'BITBUCKET' | 'AZUREDEVOPS', required: The git provider the options apply to
      - `sparseCheckout` boolean, required: Whether the destination is cloned with sparse checkout
      - `visibility` 'PUBLIC' | 'PRIVATE' | 'INTERNAL': Visibility of the created repository
    - Gitlab: Options applied to the repository the Scaffolder publishes to
      - `provider` 'GITHUB' | 'GITLAB' | 'BITBUCKET' | 'AZUREDEVOPS', required: The git provider the options apply to
      - `visibility` 'PUBLIC' | 'PRIVATE': Visibility of the created repository
  - `requireNewService` boolean, required: Whether running the template must create a new entity
  - `requirePullRequest` boolean, required: Whether the template publishes via a pull request to an existing repository
  - `showReadme` boolean, required: Whether the template repository's README is shown before a run
  - `strictAliasUsage` boolean, required: Whether runs are restricted to the git configuration alias the template names
  - `tag` string, required: Stable, human-readable identifier, unique within the workspace
  - `type` 'COOKIECUTTER', required: The templating engine of the template
  - `updatedAt` string, required: ISO-8601 timestamp at which the template was last updated

## Other responses

- `400`: Bad request
- `403`: Access denied
- `429`: The client has exceeded the rate limit by performing too many requests in a short period. Retry the request after a delay.

## Changes

- **2026-11-03** `a7b058663c95`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/cortex/apis/cortex-api/changes/api/v1/scaffolders/post.md)

---

[API](https://skmtc.dev/cortex/apis/cortex-api.md) - [All operations](https://skmtc.dev/cortex/apis/cortex-api/llms.txt) - [OpenAPI document](https://skmtc.dev/cortex/apis/cortex-api/revisions/a7b058663c95?raw)