Scaffolder

Use these operations to interact with Scaffolder templates in Cortex.

Required permissions

• List or retrieve Scaffolder templates: no additional permission is required.

• Create, update, or delete Scaffolder templates: your API key must have the Configure Scaffolder permission.

Identifying a template

Every Scaffolder template has a tag: a stable, human-readable identifier that is unique within your workspace. Tags may contain lowercase letters, numbers, and dashes, and may not start or end with a dash. If you omit the tag when creating a template, Cortex derives one from the template's name. An existing template keeps its tag unless you supply a new one.

Operations that take a tagOrId path parameter accept either the tag or the unique, auto-generated Cortex ID. Prefer the tag: it is the identifier you choose, so it stays readable and portable across workspaces.

Creating and updating

POST /api/v1/scaffolders is an upsert. If a template with the same tag already exists, that template is updated instead of a new one being created. Use PUT /api/v1/scaffolders/{tagOrId} when you want to update a specific template and have the request fail if it does not exist.

Operations

List Scaffolder templates

get

List Scaffolder templates.

Authorizations

AuthorizationstringRequired

All requests to the Cortex API need to provide an Authorization: Bearer <token> header, where <token> is an API key created in the Settings page of your workspace.

Query parameters

pageSizeinteger · int32Required

Number of results to return per page, between 1 and 1000. Default 250.

Default: 250

pageinteger · int32Required

Page number to return, 0-indexed. Default 0.

Default: 0

Responses

200

Successfully found Scaffolder templates

pageinteger · int32Required

Current page number, 0-indexed

totalinteger · int32Required

Total number of results

totalPagesinteger · int32Required

Total number of pages

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.

application/problem+json

get/api/v1/scaffolders

GET /api/v1/scaffolders?pageSize=250&page=0 HTTP/1.1
Host: api.getcortexapp.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "page": 1,
  "scaffolders": [
    {
      "createYamlFile": true,
      "createdAt": "text",
      "description": "text",
      "id": "text",
      "labels": [
        "text"
      ],
      "name": "text",
      "publisherOptions": {
        "provider": "GITHUB"
      },
      "repoLocator": {
        "provider": "GITHUB"
      },
      "requireNewService": true,
      "requirePullRequest": true,
      "showReadme": true,
      "strictAliasUsage": true,
      "tag": "text",
      "type": "COOKIECUTTER",
      "updatedAt": "text"
    }
  ],
  "total": 1,
  "totalPages": 1
}

Retrieve Scaffolder template

get

Retrieve a Scaffolder template by tag or Cortex ID.

Authorizations

AuthorizationstringRequired

All requests to the Cortex API need to provide an Authorization: Bearer <token> header, where <token> is an API key created in the Settings page of your workspace.

Path parameters

tagOrIdstringRequired

Entity identifier - can be a tag or CID

Responses

200

Successfully found the Scaffolder template

createYamlFilebooleanRequired

Whether a cortex.yaml is generated for the created entity

createdAtstringRequired

ISO-8601 timestamp at which the template was registered

descriptionstringOptional

Description of the Scaffolder template

idstringRequired

Unique, auto-generated Cortex ID of the Scaffolder template

labelsstring[]Required

Descriptive labels used to group templates in the UI

namestringRequired

Display name of the Scaffolder template

publisherOptionsone ofOptional

or

or

or

repoLocatorone ofRequired

or

or

or

requireNewServicebooleanRequired

Whether running the template must create a new entity

requirePullRequestbooleanRequired

Whether the template publishes via a pull request to an existing repository

showReadmebooleanRequired

Whether the template repository's README is shown before a run

strictAliasUsagebooleanRequired

Whether runs are restricted to the git configuration alias the template names

tagstringRequired

Stable, human-readable identifier, unique within the workspace

typestring · enumRequired

The templating engine of the template

Possible values:

updatedAtstringRequired

ISO-8601 timestamp at which the template was last updated

403

Access denied

application/json

404

Scaffolder template not found

application/json

429

The client has exceeded the rate limit by performing too many requests in a short period. Retry the request after a delay.

application/problem+json

get/api/v1/scaffolders/{tagOrId}

GET /api/v1/scaffolders/{tagOrId} HTTP/1.1
Host: api.getcortexapp.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "createYamlFile": true,
  "createdAt": "text",
  "description": "text",
  "id": "text",
  "labels": [
    "text"
  ],
  "name": "text",
  "publisherOptions": {
    "provider": "GITHUB"
  },
  "repoLocator": {
    "provider": "GITHUB"
  },
  "requireNewService": true,
  "requirePullRequest": true,
  "showReadme": true,
  "strictAliasUsage": true,
  "tag": "text",
  "type": "COOKIECUTTER",
  "updatedAt": "text"
}

Create or update Scaffolder template

post

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.

Authorizations

AuthorizationstringRequired

All requests to the Cortex API need to provide an Authorization: Bearer <token> header, where <token> is an API key created in the Settings page of your workspace.

Body

createYamlFilebooleanRequired

Whether a cortex.yaml is generated for the created entity. Defaults to true

descriptionstringOptional

Description of the Scaffolder template

labelsstring[]Required

Descriptive labels used to group templates in the UI

namestringRequired

Display name of the Scaffolder template

publisherOptionsone ofOptional

or

or

or

repoLocatorone ofRequired

or

or

or

requireNewServicebooleanRequired

Whether running the template must create a new entity. Defaults to true

requirePullRequestbooleanRequired

Whether the template publishes via a pull request to an existing repository. Defaults to false

showReadmebooleanRequired

Whether the template repository's README is shown before a run. Defaults to false

strictAliasUsagebooleanRequired

Whether runs are restricted to the git configuration alias the template names. Defaults to true

tagstringOptional

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.

typestring · enumRequired

The templating engine of the template

Possible values:

Responses

200

Scaffolder template created or updated successfully

createYamlFilebooleanRequired

Whether a cortex.yaml is generated for the created entity

createdAtstringRequired

ISO-8601 timestamp at which the template was registered

descriptionstringOptional

Description of the Scaffolder template

idstringRequired

Unique, auto-generated Cortex ID of the Scaffolder template

labelsstring[]Required

Descriptive labels used to group templates in the UI

namestringRequired

Display name of the Scaffolder template

publisherOptionsone ofOptional

or

or

or

repoLocatorone ofRequired

or

or

or

requireNewServicebooleanRequired

Whether running the template must create a new entity

requirePullRequestbooleanRequired

Whether the template publishes via a pull request to an existing repository

showReadmebooleanRequired

Whether the template repository's README is shown before a run

strictAliasUsagebooleanRequired

Whether runs are restricted to the git configuration alias the template names

tagstringRequired

Stable, human-readable identifier, unique within the workspace

typestring · enumRequired

The templating engine of the template

Possible values:

updatedAtstringRequired

ISO-8601 timestamp at which the template was last updated

400

Bad request

application/json

403

Access denied

application/json

429

The client has exceeded the rate limit by performing too many requests in a short period. Retry the request after a delay.

application/problem+json

post/api/v1/scaffolders

POST /api/v1/scaffolders HTTP/1.1
Host: api.getcortexapp.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 281

{
  "createYamlFile": true,
  "description": "text",
  "labels": [
    "text"
  ],
  "name": "text",
  "publisherOptions": {
    "provider": "GITHUB"
  },
  "repoLocator": {
    "provider": "GITHUB"
  },
  "requireNewService": true,
  "requirePullRequest": true,
  "showReadme": true,
  "strictAliasUsage": true,
  "tag": "text",
  "type": "COOKIECUTTER"
}

{
  "createYamlFile": true,
  "createdAt": "text",
  "description": "text",
  "id": "text",
  "labels": [
    "text"
  ],
  "name": "text",
  "publisherOptions": {
    "provider": "GITHUB"
  },
  "repoLocator": {
    "provider": "GITHUB"
  },
  "requireNewService": true,
  "requirePullRequest": true,
  "showReadme": true,
  "strictAliasUsage": true,
  "tag": "text",
  "type": "COOKIECUTTER",
  "updatedAt": "text"
}

Update Scaffolder template

put

Update a Scaffolder template by tag or Cortex ID.

API key must have the Configure Scaffolder permission.

Authorizations

AuthorizationstringRequired

All requests to the Cortex API need to provide an Authorization: Bearer <token> header, where <token> is an API key created in the Settings page of your workspace.

Path parameters

tagOrIdstringRequired

Entity identifier - can be a tag or CID

Body

createYamlFilebooleanRequired

Whether a cortex.yaml is generated for the created entity. Defaults to true

descriptionstringOptional

Description of the Scaffolder template

labelsstring[]Required

Descriptive labels used to group templates in the UI

namestringRequired

Display name of the Scaffolder template

publisherOptionsone ofOptional

or

or

or

repoLocatorone ofRequired

or

or

or

requireNewServicebooleanRequired

Whether running the template must create a new entity. Defaults to true

requirePullRequestbooleanRequired

Whether the template publishes via a pull request to an existing repository. Defaults to false

showReadmebooleanRequired

Whether the template repository's README is shown before a run. Defaults to false

strictAliasUsagebooleanRequired

Whether runs are restricted to the git configuration alias the template names. Defaults to true

tagstringOptional

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.

typestring · enumRequired

The templating engine of the template

Possible values:

Responses

200

Scaffolder template updated successfully

createYamlFilebooleanRequired

Whether a cortex.yaml is generated for the created entity

createdAtstringRequired

ISO-8601 timestamp at which the template was registered

descriptionstringOptional

Description of the Scaffolder template

idstringRequired

Unique, auto-generated Cortex ID of the Scaffolder template

labelsstring[]Required

Descriptive labels used to group templates in the UI

namestringRequired

Display name of the Scaffolder template

publisherOptionsone ofOptional

or

or

or

repoLocatorone ofRequired

or

or

or

requireNewServicebooleanRequired

Whether running the template must create a new entity

requirePullRequestbooleanRequired

Whether the template publishes via a pull request to an existing repository

showReadmebooleanRequired

Whether the template repository's README is shown before a run

strictAliasUsagebooleanRequired

Whether runs are restricted to the git configuration alias the template names

tagstringRequired

Stable, human-readable identifier, unique within the workspace

typestring · enumRequired

The templating engine of the template

Possible values:

updatedAtstringRequired

ISO-8601 timestamp at which the template was last updated

400

Bad request

application/json

403

Access denied

application/json

404

Scaffolder template not found

application/json

429

The client has exceeded the rate limit by performing too many requests in a short period. Retry the request after a delay.

application/problem+json

put/api/v1/scaffolders/{tagOrId}

PUT /api/v1/scaffolders/{tagOrId} HTTP/1.1
Host: api.getcortexapp.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 281

{
  "createYamlFile": true,
  "description": "text",
  "labels": [
    "text"
  ],
  "name": "text",
  "publisherOptions": {
    "provider": "GITHUB"
  },
  "repoLocator": {
    "provider": "GITHUB"
  },
  "requireNewService": true,
  "requirePullRequest": true,
  "showReadme": true,
  "strictAliasUsage": true,
  "tag": "text",
  "type": "COOKIECUTTER"
}

{
  "createYamlFile": true,
  "createdAt": "text",
  "description": "text",
  "id": "text",
  "labels": [
    "text"
  ],
  "name": "text",
  "publisherOptions": {
    "provider": "GITHUB"
  },
  "repoLocator": {
    "provider": "GITHUB"
  },
  "requireNewService": true,
  "requirePullRequest": true,
  "showReadme": true,
  "strictAliasUsage": true,
  "tag": "text",
  "type": "COOKIECUTTER",
  "updatedAt": "text"
}

Delete Scaffolder template

delete

Delete a Scaffolder template by tag or Cortex ID.

API key must have the Configure Scaffolder permission.

Authorizations

AuthorizationstringRequired

All requests to the Cortex API need to provide an Authorization: Bearer <token> header, where <token> is an API key created in the Settings page of your workspace.

Path parameters

tagOrIdstringRequired

Entity identifier - can be a tag or CID

Responses

204

Scaffolder template deleted successfully

No content

403

Access denied

application/json

404

Scaffolder template not found

application/json

429

The client has exceeded the rate limit by performing too many requests in a short period. Retry the request after a delay.

application/problem+json

delete/api/v1/scaffolders/{tagOrId}

DELETE /api/v1/scaffolders/{tagOrId} HTTP/1.1
Host: api.getcortexapp.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

No content