Get Roadie in your IDE with our new MCP Servers
Roadie
← Backstage Scaffolder Actions

Backstage API Request

Action ID: http:backstage:request
NPM Package:

@roadiehq/scaffolder-backend-module-http-request

Description

Sends a HTTP request to the Backstage API. It uses the token of the user who triggers the task to authenticate requests.

Input Schema

PropertyTypeDescriptionRequired
bodyany-
pathstring-
methodstring-
paramsobject-
headersobject-
timeoutnumber-
logRequestPathboolean-
continueOnBadResponseboolean-

Output Schema

PropertyTypeDescriptionRequired
bodyany-
codestring-
headersobject-

Usage Examples

Check if a Catalog entity exists by name

Use this to verify that an expected entity is already present in the Catalog before proceeding. This typically runs after fetching your template with fetch:template.

Copy 
steps:
  - id: fetchBase
    action: fetch:template
    input:
      url: https://github.com/acme/software-templates/archive/main.zip
      targetPath: ./skeleton
      values:
        name: ${{ parameters.serviceName }}

  - id: lookupEntity
    action: http:backstage:request
    input:
      path: /api/catalog/entities/by-name
      method: GET
      params:
        kind: Component
        namespace: default
        name: ${{ parameters.serviceName }}
      headers:
        Accept: application/json
      logRequestPath: true
      timeout: 5000

Trigger a Catalog refresh for a new component

After publishing a new repository with publish:github, request a Catalog refresh so the entity is quickly re-ingested.

Copy 
steps:
  - id: publishRepo
    action: publish:github
    input:
      repoUrl: github.com?owner=acme&repo=${{ parameters.repoName }}
      defaultBranch: main
      protectDefaultBranch: true
      description: ${{ parameters.description }}

  - id: refreshCatalog
    action: http:backstage:request
    input:
      path: /api/catalog/refresh
      method: POST
      headers:
        Content-Type: application/json
        Accept: application/json
      body:
        entityRef: component:default/${{ parameters.serviceName }}
      timeout: 3000

Register a Catalog location for the new repository

Register the catalog-info.yaml of the newly created repo so it appears in the Catalog. This is useful right after publish:github.

Copy 
steps:
  - id: publishRepo
    action: publish:github
    input:
      repoUrl: github.com?owner=acme&repo=${{ parameters.repoName }}
      defaultBranch: main
      protectDefaultBranch: true
      description: ${{ parameters.description }}

  - id: registerLocation
    action: http:backstage:request
    input:
      path: /api/catalog/locations
      method: POST
      headers:
        Content-Type: application/json
        Accept: application/json
      body:
        type: url
        target: https://github.com/acme/${{ parameters.repoName }}/blob/main/catalog-info.yaml
        presence: optional
      continueOnBadResponse: true
      logRequestPath: true
      timeout: 10000

Remove a deprecated Catalog location

Use this to clean up a Catalog location when decommissioning or migrating services. The step tolerates missing locations.

Copy 
steps:
  - id: cleanupLocation
    action: http:backstage:request
    input:
      path: /api/catalog/locations/${{ parameters.locationId }}
      method: DELETE
      continueOnBadResponse: true
      timeout: 5000

Probe TechDocs availability with a HEAD request

Check whether TechDocs content is available for a component without downloading the document. This can run after template setup with fetch:template.

Copy 
steps:
  - id: fetchBase
    action: fetch:template
    input:
      url: https://github.com/acme/software-templates/archive/main.zip
      targetPath: ./skeleton
      values:
        name: ${{ parameters.serviceName }}

  - id: checkTechDocs
    action: http:backstage:request
    input:
      path: /api/techdocs/static/docs/default/component/${{ parameters.serviceName }}/index.html
      method: HEAD
      continueOnBadResponse: true
      logRequestPath: true
      timeout: 2000