Backstage Scaffolder API — Tasks

naftiko: 1.0.0-alpha2
info:
  label: Backstage Scaffolder API — Tasks
  description: 'Backstage Scaffolder API — Tasks. 7 operations. Lead operation: Backstage Dry-run a template. Self-contained
    Naftiko capability covering one Backstage business surface.'
  tags:
  - Backstage
  - Tasks
  created: '2026-05-19'
  modified: '2026-05-19'
binds:
- namespace: env
  keys:
    BACKSTAGE_API_KEY: BACKSTAGE_API_KEY
capability:
  consumes:
  - type: http
    namespace: scaffolder-tasks
    baseUri: https://localhost:7007/api/scaffolder
    description: Backstage Scaffolder API — Tasks business capability. Self-contained, no shared references.
    resources:
    - name: v2-dry-run
      path: /v2/dry-run
      operations:
      - name: dryruntask
        method: POST
        description: Backstage Dry-run a template
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: true
    - name: v2-tasks
      path: /v2/tasks
      operations:
      - name: listtasks
        method: GET
        description: Backstage List scaffolder tasks
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: createdBy
          in: query
          type: string
          description: Filter tasks by the user who created them.
      - name: createtask
        method: POST
        description: Backstage Create a scaffolder task
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: true
    - name: v2-tasks-taskId
      path: /v2/tasks/{taskId}
      operations:
      - name: gettask
        method: GET
        description: Backstage Get task by ID
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: taskId
          in: path
          type: string
          description: The unique identifier of the task.
          required: true
    - name: v2-tasks-taskId-cancel
      path: /v2/tasks/{taskId}/cancel
      operations:
      - name: canceltask
        method: POST
        description: Backstage Cancel a task
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: taskId
          in: path
          type: string
          required: true
    - name: v2-tasks-taskId-eventstream
      path: /v2/tasks/{taskId}/eventstream
      operations:
      - name: gettaskeventstream
        method: GET
        description: Backstage Get task event stream
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: taskId
          in: path
          type: string
          required: true
        - name: after
          in: query
          type: integer
          description: Only return events after this sequence number.
    - name: v2-tasks-taskId-logs
      path: /v2/tasks/{taskId}/logs
      operations:
      - name: gettasklogs
        method: GET
        description: Backstage Get task logs
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: taskId
          in: path
          type: string
          required: true
        - name: after
          in: query
          type: integer
          description: Only return log entries after this sequence number.
    authentication:
      type: bearer
      token: '{{env.BACKSTAGE_API_KEY}}'
  exposes:
  - type: rest
    namespace: scaffolder-tasks-rest
    port: 8080
    description: REST adapter for Backstage Scaffolder API — Tasks. One Spectral-compliant resource per consumed operation,
      prefixed with /v1.
    resources:
    - path: /v1/v2/dry-run
      name: v2-dry-run
      description: REST surface for v2-dry-run.
      operations:
      - method: POST
        name: dryruntask
        description: Backstage Dry-run a template
        call: scaffolder-tasks.dryruntask
        with:
          body: rest.body
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/v2/tasks
      name: v2-tasks
      description: REST surface for v2-tasks.
      operations:
      - method: GET
        name: listtasks
        description: Backstage List scaffolder tasks
        call: scaffolder-tasks.listtasks
        with:
          createdBy: rest.createdBy
        outputParameters:
        - type: object
          mapping: $.
      - method: POST
        name: createtask
        description: Backstage Create a scaffolder task
        call: scaffolder-tasks.createtask
        with:
          body: rest.body
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/v2/tasks/{taskid}
      name: v2-tasks-taskid
      description: REST surface for v2-tasks-taskId.
      operations:
      - method: GET
        name: gettask
        description: Backstage Get task by ID
        call: scaffolder-tasks.gettask
        with:
          taskId: rest.taskId
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/v2/tasks/{taskid}/cancel
      name: v2-tasks-taskid-cancel
      description: REST surface for v2-tasks-taskId-cancel.
      operations:
      - method: POST
        name: canceltask
        description: Backstage Cancel a task
        call: scaffolder-tasks.canceltask
        with:
          taskId: rest.taskId
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/v2/tasks/{taskid}/eventstream
      name: v2-tasks-taskid-eventstream
      description: REST surface for v2-tasks-taskId-eventstream.
      operations:
      - method: GET
        name: gettaskeventstream
        description: Backstage Get task event stream
        call: scaffolder-tasks.gettaskeventstream
        with:
          taskId: rest.taskId
          after: rest.after
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/v2/tasks/{taskid}/logs
      name: v2-tasks-taskid-logs
      description: REST surface for v2-tasks-taskId-logs.
      operations:
      - method: GET
        name: gettasklogs
        description: Backstage Get task logs
        call: scaffolder-tasks.gettasklogs
        with:
          taskId: rest.taskId
          after: rest.after
        outputParameters:
        - type: object
          mapping: $.
  - type: mcp
    namespace: scaffolder-tasks-mcp
    port: 9090
    transport: http
    description: MCP adapter for Backstage Scaffolder API — Tasks. One tool per consumed operation, routed inline through
      this capability's consumes block.
    tools:
    - name: backstage-dry-run-template
      description: Backstage Dry-run a template
      hints:
        readOnly: false
        destructive: false
        idempotent: false
      call: scaffolder-tasks.dryruntask
      with:
        body: tools.body
      outputParameters:
      - type: object
        mapping: $.
    - name: backstage-list-scaffolder-tasks
      description: Backstage List scaffolder tasks
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: scaffolder-tasks.listtasks
      with:
        createdBy: tools.createdBy
      outputParameters:
      - type: object
        mapping: $.
    - name: backstage-create-scaffolder-task
      description: Backstage Create a scaffolder task
      hints:
        readOnly: false
        destructive: false
        idempotent: false
      call: scaffolder-tasks.createtask
      with:
        body: tools.body
      outputParameters:
      - type: object
        mapping: $.
    - name: backstage-get-task-id
      description: Backstage Get task by ID
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: scaffolder-tasks.gettask
      with:
        taskId: tools.taskId
      outputParameters:
      - type: object
        mapping: $.
    - name: backstage-cancel-task
      description: Backstage Cancel a task
      hints:
        readOnly: false
        destructive: false
        idempotent: false
      call: scaffolder-tasks.canceltask
      with:
        taskId: tools.taskId
      outputParameters:
      - type: object
        mapping: $.
    - name: backstage-get-task-event-stream
      description: Backstage Get task event stream
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: scaffolder-tasks.gettaskeventstream
      with:
        taskId: tools.taskId
        after: tools.after
      outputParameters:
      - type: object
        mapping: $.
    - name: backstage-get-task-logs
      description: Backstage Get task logs
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: scaffolder-tasks.gettasklogs
      with:
        taskId: tools.taskId
        after: tools.after
      outputParameters:
      - type: object
        mapping: $.