Backstage Scaffolder API

openapi: 3.1.0
info:
  title: Backstage Scaffolder API
  description: >-
    The Backstage Scaffolder (Software Templates) REST API provides endpoints
    for creating, managing, and monitoring scaffolder tasks. It enables
    programmatic execution of software templates to bootstrap new projects,
    components, and other software assets. The API supports task creation,
    status monitoring via event streams, listing available actions, and
    dry-run capabilities for testing templates.
  version: 2.0.0
  contact:
    name: Backstage
    url: https://backstage.io
  license:
    name: Apache-2.0
    url: https://www.apache.org/licenses/LICENSE-2.0
externalDocs:
  description: Backstage Software Templates Documentation
  url: https://backstage.io/docs/features/software-templates/
servers:
  - url: https://localhost:7007/api/scaffolder
    description: Local development server
paths:
  /v2/tasks:
    get:
      operationId: listTasks
      summary: Backstage List scaffolder tasks
      description: >-
        Lists scaffolder tasks, optionally filtered by the user who created
        them. Returns task metadata and status information.
      tags:
        - Tasks
      security:
        - bearerAuth: []
      parameters:
        - name: createdBy
          in: query
          required: false
          description: Filter tasks by the user who created them.
          schema:
            type: string
      responses:
        '200':
          description: A list of scaffolder tasks.
          content:
            application/json:
              schema:
                type: object
                properties:
                  tasks:
                    type: array
                    items:
                      $ref: '#/components/schemas/Task'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: createTask
      summary: Backstage Create a scaffolder task
      description: >-
        Creates a new scaffolder task to execute a software template. The task
        runs asynchronously and its progress can be monitored through the
        event stream or logs endpoints.
      tags:
        - Tasks
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - templateRef
                - values
              properties:
                templateRef:
                  type: string
                  description: >-
                    The entity reference of the template to execute.
                  example: template:default/create-react-app
                values:
                  type: object
                  description: >-
                    The input values for the template parameters.
                  additionalProperties: true
                secrets:
                  type: object
                  description: >-
                    Secret values to pass to the template (not persisted).
                  additionalProperties:
                    type: string
      responses:
        '201':
          description: Task created successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    description: The unique identifier of the created task.
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v2/tasks/{taskId}:
    get:
      operationId: getTask
      summary: Backstage Get task by ID
      description: Retrieves the details and current status of a scaffolder task.
      tags:
        - Tasks
      security:
        - bearerAuth: []
      parameters:
        - name: taskId
          in: path
          required: true
          description: The unique identifier of the task.
          schema:
            type: string
      responses:
        '200':
          description: The task details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Task'
        '404':
          $ref: '#/components/responses/NotFound'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v2/tasks/{taskId}/cancel:
    post:
      operationId: cancelTask
      summary: Backstage Cancel a task
      description: Requests cancellation of a running scaffolder task.
      tags:
        - Tasks
      security:
        - bearerAuth: []
      parameters:
        - name: taskId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Cancellation requested successfully.
        '404':
          $ref: '#/components/responses/NotFound'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v2/tasks/{taskId}/eventstream:
    get:
      operationId: getTaskEventStream
      summary: Backstage Get task event stream
      description: >-
        Returns a server-sent event stream of task progress events. This
        endpoint streams real-time updates about the task execution including
        step progress, log messages, and completion status.
      tags:
        - Tasks
      security:
        - bearerAuth: []
      parameters:
        - name: taskId
          in: path
          required: true
          schema:
            type: string
        - name: after
          in: query
          required: false
          description: Only return events after this sequence number.
          schema:
            type: integer
      responses:
        '200':
          description: A server-sent event stream of task events.
          content:
            text/event-stream:
              schema:
                type: string
        '404':
          $ref: '#/components/responses/NotFound'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v2/tasks/{taskId}/logs:
    get:
      operationId: getTaskLogs
      summary: Backstage Get task logs
      description: >-
        Retrieves the log entries for a scaffolder task, providing detailed
        information about each step of template execution.
      tags:
        - Tasks
      security:
        - bearerAuth: []
      parameters:
        - name: taskId
          in: path
          required: true
          schema:
            type: string
        - name: after
          in: query
          required: false
          description: Only return log entries after this sequence number.
          schema:
            type: integer
      responses:
        '200':
          description: Task log entries.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    type:
                      type: string
                    createdAt:
                      type: string
                      format: date-time
                    body:
                      type: object
                      properties:
                        message:
                          type: string
                        stepId:
                          type: string
                        status:
                          type: string
        '404':
          $ref: '#/components/responses/NotFound'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v2/templates/{namespace}/{kind}/{name}/parameter-schema:
    get:
      operationId: getTemplateParameterSchema
      summary: Backstage Get template parameter schema
      description: >-
        Retrieves the parameter schema for a specific template. This describes
        the input parameters the template accepts and their validation rules.
      tags:
        - Templates
      security:
        - bearerAuth: []
      parameters:
        - name: namespace
          in: path
          required: true
          schema:
            type: string
        - name: kind
          in: path
          required: true
          schema:
            type: string
        - name: name
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: The parameter schema for the template.
          content:
            application/json:
              schema:
                type: object
                description: JSON Schema describing the template parameters.
        '404':
          $ref: '#/components/responses/NotFound'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v2/actions:
    get:
      operationId: listActions
      summary: Backstage List available actions
      description: >-
        Lists all available scaffolder actions that can be used in templates.
        Each action includes its ID, description, and input/output schemas.
      tags:
        - Actions
      security:
        - bearerAuth: []
      responses:
        '200':
          description: A list of available scaffolder actions.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Action'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v2/dry-run:
    post:
      operationId: dryRunTask
      summary: Backstage Dry-run a template
      description: >-
        Executes a template as a dry run without actually performing any
        side effects. Useful for testing and validating templates before
        actual execution.
      tags:
        - Tasks
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - template
                - values
              properties:
                template:
                  type: object
                  description: The template entity to dry-run.
                values:
                  type: object
                  description: Input values for the template parameters.
                  additionalProperties: true
                secrets:
                  type: object
                  description: Secret values to pass to the template.
                  additionalProperties:
                    type: string
                directoryContents:
                  type: array
                  description: Initial directory contents for the workspace.
                  items:
                    type: object
                    properties:
                      path:
                        type: string
                      base64Content:
                        type: string
      responses:
        '200':
          description: Dry-run result.
          content:
            application/json:
              schema:
                type: object
                properties:
                  log:
                    type: array
                    items:
                      type: object
                      properties:
                        type:
                          type: string
                        body:
                          type: object
                  directoryContents:
                    type: array
                    items:
                      type: object
                      properties:
                        path:
                          type: string
                        base64Content:
                          type: string
                  steps:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                        name:
                          type: string
                        status:
                          type: string
                  output:
                    type: object
                    additionalProperties: true
        '401':
          $ref: '#/components/responses/Unauthorized'
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: >-
        Backstage token returned by the identity API.
  schemas:
    Task:
      type: object
      properties:
        id:
          type: string
          description: The unique identifier of the task.
        spec:
          type: object
          properties:
            apiVersion:
              type: string
            templateInfo:
              type: object
              properties:
                entityRef:
                  type: string
                  description: Reference to the template entity.
            steps:
              type: array
              items:
                type: object
                properties:
                  id:
                    type: string
                  name:
                    type: string
                  action:
                    type: string
                  input:
                    type: object
            output:
              type: object
              additionalProperties: true
            parameters:
              type: object
              additionalProperties: true
        status:
          type: string
          description: The current status of the task.
          enum:
            - open
            - processing
            - completed
            - failed
            - cancelled
        createdAt:
          type: string
          format: date-time
        lastHeartbeatAt:
          type: string
          format: date-time
        completedAt:
          type: string
          format: date-time
        createdBy:
          type: string
          description: The user who created the task.
    Action:
      type: object
      properties:
        id:
          type: string
          description: The unique identifier of the action.
          example: fetch:plain
        description:
          type: string
          description: A human-readable description of the action.
        schema:
          type: object
          properties:
            input:
              type: object
              description: JSON Schema for the action input.
            output:
              type: object
              description: JSON Schema for the action output.
  responses:
    Unauthorized:
      description: Missing or invalid authentication token.
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: object
                properties:
                  name:
                    type: string
                  message:
                    type: string
    NotFound:
      description: The requested resource was not found.
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: object
                properties:
                  name:
                    type: string
                  message:
                    type: string
tags:
  - name: Actions
    description: Endpoints for listing available scaffolder actions.
  - name: Tasks
    description: Endpoints for creating and managing scaffolder tasks.
  - name: Templates
    description: Endpoints for template metadata and parameter schemas.