Backstage
@acameron17/backstagev2026.09.17.1
01README
Backstage software catalog reader — query entities, read one entity with its relations, trace an entity's ancestry, list the locations that feed the catalog, count entity facets, and audit catalog hygiene. Read-only. No CLI dependencies: native fetch against the Backstage Catalog HTTP API with a static token stored in a swamp vault.
Authentication
Requires a Backstage static external-access token with read access to the catalog, stored in a swamp vault.
Usage
swamp model create @acameron17/backstage catalog \
--global-arg baseUrl=https://backstage.example.org \
--global-arg 'token=${{ vault.get("backstage", "API_TOKEN") }}'
swamp model method run catalog audit_catalog
swamp model method run catalog query_entities --arg filter=kind=componentMethods
- query_entities — catalog entities matching a filter, with tallies by kind, type, owner, and lifecycle
- get_entity — one entity with its labels, annotations, and relations
- get_ancestry — the ancestry chain from an entity up to its root location
- list_locations — registered catalog locations, grouped by location type
- entity_facets — distinct value counts for entity facets such as kind, spec.type, or spec.owner
- audit_catalog — one whole-catalog sweep reporting inventory plus hygiene gaps: entities with no owner, no description, or an orphan marker
02Models
@acameron17/backstagev2026.09.17.1backstage.ts
Global Arguments
| Argument | Type | Description |
|---|---|---|
| baseUrl | string | Backstage base URL, e.g. https://backstage.example.org |
| token | string | Backstage static external-access token, sent as a Bearer credential (use a vault reference) |
fn query_entities(filter: array, fullTextTerm?: string, fullTextFields: array, orderField: array, limit: number, pageSize: number, topN: number, label: string)
Query catalog entities. Each filter string is one AND-set of key=value pairs; multiple filter strings are ORed together, matching the catalog filter syntax.
| Argument | Type | Description |
|---|---|---|
| filter | array | Filter sets, e.g. ["kind=component,spec.type=service"]. Repeat for OR. |
| fullTextTerm? | string | Free-text term matched against the entity |
| fullTextFields | array | Fields the free-text term searches, e.g. metadata.name |
| orderField | array | Sort directives in "field,order" form, e.g. metadata.name,asc |
| limit | number | Maximum entities to collect across pages |
| pageSize | number | Entities requested per page |
| topN | number | Rows to keep per grouping |
| label | string | Instance label, so separate queries keep separate version history |
fn get_entity(entityRef: string)
Read one catalog entity by reference, including its labels, annotations, and relations.
| Argument | Type | Description |
|---|---|---|
| entityRef | string | Entity reference, e.g. component:default/my-service |
fn get_ancestry(entityRef: string)
Read the ancestry chain for one entity, showing which location or parent entity emitted it.
| Argument | Type | Description |
|---|---|---|
| entityRef | string | Entity reference, e.g. component:default/my-service |
fn list_locations()
List the registered catalog locations that feed the catalog, grouped by location type.
fn entity_facets(facet: array, filter: array, topN: number, label: string)
Count distinct values for one or more entity facets, e.g. kind, spec.type, spec.owner, or metadata.tags.
| Argument | Type | Description |
|---|---|---|
| facet | array | Facet paths to count, e.g. kind or relations.ownedBy |
| filter | array | Filter sets applied before counting |
| topN | number | Values to keep per facet |
| label | string | Instance label, so separate facet sets keep separate version history |
fn audit_catalog(filter: array, limit: number, pageSize: number, topN: number, sampleSize: number)
Sweep the whole catalog once and report inventory plus hygiene gaps: entities without an owner, without a description, and marked orphaned.
| Argument | Type | Description |
|---|---|---|
| filter | array | Filter sets to narrow the sweep, e.g. ["kind=component"] |
| limit | number | Maximum entities to sweep across pages |
| pageSize | number | Entities requested per page |
| topN | number | Rows to keep per grouping |
| sampleSize | number | Entity references to list per hygiene gap |
Resources
entities(24h)— Catalog entities matching a filter, with tallies by kind, type, owner, and lifecycle
entity(24h)— One catalog entity with its annotations and relations
ancestry(24h)— Ancestry chain for one entity, from the entity up to its root location
locations(24h)— Registered catalog locations, grouped by location type
facets(24h)— Distinct value counts for the requested entity facets
catalogAudit(24h)— Whole-catalog inventory and hygiene audit: ownership, documentation, and orphan coverage
03Previous Versions
2026.09.16.1
04Stats
A
100 / 100
Downloads
14
Archive size
24.5 KB
- Has README or module doc2/2earned
- README has a code example1/1earned
- README is substantive1/1earned
- Most symbols documented1/1earned
- No slow types (deprecated)1/1earned
- Dependencies pass trust audit2/2earned
- Has description1/1earned
- Platform support declared (or universal)2/2earned
- License declared1/1earned
- Verified public repository2/2earned
05Platforms
06Labels