Backstage Entities API

openapi: 3.1.0
info:
  title: catalog
  version: '1'
  description: |
    The API surface consists of a few distinct groups of functionality. Each has a
    dedicated section below.

    :::note Note
      This page only describes some of the most commonly used parts of the API, and is a work in progress.
    :::

    All of the URL paths in this article are assumed to be on top of some base URL
    pointing at your catalog installation. For example, if the path given in a
    section below is `/entities`, and the catalog is located at
    `http://localhost:7007/api/catalog` during local development, the full URL would
    be `http://localhost:7007/api/catalog/entities`. The actual URL may vary from
    one organization to the other, especially in production, but is commonly your
    `backend.baseUrl` in your app config, plus `/api/catalog` at the end.

    Some or all of the endpoints may accept or require an `Authorization` header
    with a `Bearer` token, which should then be the Backstage token returned by the
    [`identity API`](https://backstage.io/api/stable/variables/_backstage_core-plugin-api.index.identityApiRef.html).
  license:
    name: Apache-2.0
    url: http://www.apache.org/licenses/LICENSE-2.0.html
  contact: {}
tags:
  - name: Entity
  - name: Locations
servers:
  - url: /
components:
  examples: {}
  headers: {}
  parameters:
    kind:
      name: kind
      in: path
      required: true
      schema:
        type: string
    namespace:
      name: namespace
      in: path
      required: true
      schema:
        type: string
    name:
      name: name
      in: path
      required: true
      schema:
        type: string
    uid:
      name: uid
      in: path
      required: true
      schema:
        type: string
    cursor:
      name: cursor
      in: query
      description: |
        You may pass the `cursor` query parameters to perform cursor based pagination
        through the set of entities. The value of `cursor` will be returned in the response, under the `pageInfo` property:

        ```json
          "pageInfo": {
            "nextCursor": "a-cursor",
            "prevCursor": "another-cursor"
          }
        ```

        If `nextCursor` exists, it can be used to retrieve the next batch of entities. Following the same approach,
        if `prevCursor` exists, it can be used to retrieve the previous batch of entities.

        - [`filter`](#filtering), for selecting only a subset of all entities
        - [`fields`](#field-selection), for selecting only parts of the full data
          structure of each entity
        - `limit` for limiting the number of entities returned (20 is the default)
        - [`orderField`](#ordering), for deciding the order of the entities
        - `fullTextFilter`
          **NOTE**: [`filter`, `orderField`, `fullTextFilter`] and `cursor` are mutually exclusive. This means that,
          it isn't possible to change any of [`filter`, `orderField`, `fullTextFilter`] when passing `cursor` as query parameters,
          as changing any of these properties will affect pagination. If any of `filter`, `orderField`, `fullTextFilter` is specified together with `cursor`, only the latter is taken into consideration.
      required: false
      allowReserved: true
      schema:
        type: string
        minLength: 1
    after:
      name: after
      in: query
      description: Pointer to the previous page of results.
      required: false
      allowReserved: true
      schema:
        type: string
        minLength: 1
    fields:
      name: fields
      in: query
      description: |
        By default the full entities are returned, but you can pass in a `fields` query
        parameter which selects what parts of the entity data to retain. This makes the
        response smaller and faster to transfer, and may allow the catalog to perform
        more efficient queries.

        The query parameter value is a comma separated list of simplified JSON paths
        like above. Each path corresponds to the key of either a value, or of a subtree
        root that you want to keep in the output. The rest is pruned away. For example,
        specifying `?fields=metadata.name,metadata.annotations,spec` retains only the
        `name` and `annotations` fields of the `metadata` of each entity (it'll be an
        object with at most two keys), keeps the entire `spec` unchanged, and cuts out
        all other roots such as `relations`.

        Some more real world usable examples:

        - Return only enough data to form the full ref of each entity:

          `/entities/by-query?fields=kind,metadata.namespace,metadata.name`
      required: false
      allowReserved: true
      explode: false
      schema:
        type: array
        items:
          type: string
      examples:
        Get name and the entire relations collection:
          value:
            - metadata.name
            - relations
        Get kind, name and namespace:
          value:
            - kind
            - metadata.name
            - metadata.namespace
    filter:
      name: filter
      in: query
      description: |
        You can pass in one or more filter sets that get matched against each entity.
        Each filter set is a number of conditions that all have to match for the
        condition to be true (conditions effectively have an AND between them). At least
        one filter set has to be true for the entity to be part of the result set
        (filter sets effectively have an OR between them).

        Example:

        ```text
        /entities/by-query?filter=kind=user,metadata.namespace=default&filter=kind=group,spec.type

          Return entities that match

            Filter set 1:
              Condition 1: kind = user
                          AND
              Condition 2: metadata.namespace = default

            OR

            Filter set 2:
              Condition 1: kind = group
                          AND
              Condition 2: spec.type exists
        ```

        Each condition is either on the form `<key>`, or on the form `<key>=<value>`.
        The first form asserts on the existence of a certain key (with any value), and
        the second asserts that the key exists and has a certain value. All checks are
        always case _insensitive_.

        In all cases, the key is a simplified JSON path in a given piece of entity data.
        Each part of the path is a key of an object, and the traversal also descends
        through arrays. There are two special forms:

        - Array items that are simple value types (such as strings) match on a key-value
          pair where the key is the item as a string, and the value is the string `true`
        - Relations can be matched on a `relations.<type>=<targetRef>` form

        Let's look at a simplified example to illustrate the concept:

        ```json
        {
          "a": {
            "b": ["c", { "d": 1 }],
            "e": 7
          }
        }
        ```

        This would match any one of the following conditions:

        - `a`
        - `a.b`
        - `a.b.c`
        - `a.b.c=true`
        - `a.b.d`
        - `a.b.d=1`
        - `a.e`
        - `a.e=7`

        Some more real world usable examples:

        - Return all orphaned entities:

          `/entities/by-query?filter=metadata.annotations.backstage.io/orphan=true`

        - Return all users and groups:

          `/entities/by-query?filter=kind=user&filter=kind=group`

        - Return all service components:

          `/entities/by-query?filter=kind=component,spec.type=service`

        - Return all entities with the `java` tag:

          `/entities/by-query?filter=metadata.tags.java`

        - Return all users who are members of the `ops` group (note that the full
          [reference](references.md) of the group is used):

          `/entities/by-query?filter=kind=user,relations.memberof=group:default/ops`

      required: false
      allowReserved: true
      schema:
        type: array
        items:
          type: string
      examples:
        Get groups:
          value:
            - kind=group
        Get orphaned components:
          value:
            - kind=component,metadata.annotations.backstage.io/orphan=true
    offset:
      name: offset
      in: query
      description: Number of records to skip in the query page.
      required: false
      allowReserved: true
      schema:
        type: integer
        minimum: 0
    limit:
      name: limit
      in: query
      description: Number of records to return in the response.
      required: false
      allowReserved: true
      schema:
        type: integer
        minimum: 0
    orderField:
      name: orderField
      in: query
      description: |
        By default the entities are returned ordered by their internal uid. You can
        customize the `orderField` query parameters to affect that ordering.

        For example, to return entities by their name:

        `/entities/by-query?orderField=metadata.name,asc`

        Each parameter can be followed by `asc` for ascending lexicographical order or
        `desc` for descending (reverse) lexicographical order.
      required: false
      allowReserved: true
      schema:
        type: array
        items:
          type: string
          description: A two-item tuple of [field, order].
      explode: true
      style: form
      examples:
        Order ascending by name:
          value:
            - metadata.name,asc
        Order descending by owner:
          value:
            - spec.owner,desc
    totalItems:
      name: totalItems
      in: query
      description: |
        Controls whether the response's `totalItems` field is computed. Computing
        the total may be expensive for large catalogs; pass `exclude` if the
        caller does not need it (e.g. cursor-paginated UIs that only display the
        count cosmetically). Defaults to `include`. New values may be added in
        the future, such as an approximate mode.
      required: false
      allowReserved: true
      schema:
        type: string
        enum:
          - include
          - exclude
  requestBodies: {}
  responses:
    ErrorResponse:
      description: An error response from the backend.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  schemas:
    Error:
      type: object
      properties:
        error:
          type: object
          properties:
            name:
              type: string
            message:
              type: string
            stack:
              type: string
            code:
              type: string
          required:
            - name
            - message
        request:
          type: object
          properties:
            method:
              type: string
            url:
              type: string
          required:
            - method
            - url
        response:
          type: object
          properties:
            statusCode:
              type: number
          required:
            - statusCode
      required:
        - error
        - response
      additionalProperties: {}
    JsonObject:
      type: object
      properties: {}
      description: A type representing all allowed JSON object values.
      additionalProperties: {}
    MapStringString:
      type: object
      properties: {}
      additionalProperties:
        type: string
      description: Construct a type with a set of properties K of type T
    EntityLink:
      type: object
      properties:
        type:
          type: string
          description: An optional value to categorize links into specific groups
        icon:
          type: string
          description: An optional semantic key that represents a visual icon.
        title:
          type: string
          description: An optional descriptive title for the link.
        url:
          type: string
          description: The url to the external site, document, etc.
      required:
        - url
      description: A link to external information that is related to the entity.
      additionalProperties: false
    EntityMeta:
      type: object
      properties:
        links:
          type: array
          items:
            $ref: '#/components/schemas/EntityLink'
          description: A list of external hyperlinks related to the entity.
        tags:
          type: array
          items:
            type: string
          description: |-
            A list of single-valued strings, to for example classify catalog entities in
            various ways.
        annotations:
          $ref: '#/components/schemas/MapStringString'
        labels:
          $ref: '#/components/schemas/MapStringString'
        description:
          type: string
          description: |-
            A short (typically relatively few words, on one line) description of the
            entity.
        title:
          type: string
          description: |-
            A display name of the entity, to be presented in user interfaces instead
            of the `name` property above, when available.
            This field is sometimes useful when the `name` is cumbersome or ends up
            being perceived as overly technical. The title generally does not have
            as stringent format requirements on it, so it may contain special
            characters and be more explanatory. Do keep it very short though, and
            avoid situations where a title can be confused with the name of another
            entity, or where two entities share a title.
            Note that this is only for display purposes, and may be ignored by some
            parts of the code. Entity references still always make use of the `name`
            property, not the title.
        namespace:
          type: string
          description: The namespace that the entity belongs to.
        name:
          type: string
          description: |-
            The name of the entity.
            Must be unique within the catalog at any given point in time, for any
            given namespace + kind pair. This value is part of the technical
            identifier of the entity, and as such it will appear in URLs, database
            tables, entity references, and similar. It is subject to restrictions
            regarding what characters are allowed.
            If you want to use a different, more human readable string with fewer
            restrictions on it in user interfaces, see the `title` field below.
        etag:
          type: string
          description: |-
            An opaque string that changes for each update operation to any part of
            the entity, including metadata.
            This field can not be set by the user at creation time, and the server
            will reject an attempt to do so. The field will be populated in read
            operations. The field can (optionally) be specified when performing
            update or delete operations, and the server will then reject the
            operation if it does not match the current stored value.
        uid:
          type: string
          description: |-
            A globally unique ID for the entity.
            This field can not be set by the user at creation time, and the server
            will reject an attempt to do so. The field will be populated in read
            operations. The field can (optionally) be specified when performing
            update or delete operations, but the server is free to reject requests
            that do so in such a way that it breaks semantics.
      required:
        - name
      description: Metadata fields common to all versions/kinds of entity.
      additionalProperties: {}
    EntityRelation:
      type: object
      properties:
        targetRef:
          type: string
          description: The entity ref of the target of this relation.
        type:
          type: string
          description: The type of the relation.
      required:
        - targetRef
        - type
      description: A relation of a specific type to another entity in the catalog.
      additionalProperties: false
    Entity:
      type: object
      properties:
        relations:
          type: array
          items:
            $ref: '#/components/schemas/EntityRelation'
          description: The relations that this entity has with other entities.
        spec:
          $ref: '#/components/schemas/JsonObject'
        metadata:
          $ref: '#/components/schemas/EntityMeta'
        kind:
          type: string
          description: The high level entity type being described.
        apiVersion:
          type: string
          description: |-
            The version of specification format for this particular entity that
            this is written against.
      required:
        - metadata
        - kind
        - apiVersion
      description: The parts of the format that's common to all versions/kinds of entity.
    NullableEntity:
      anyOf:
        - type: object
          properties:
            relations:
              type: array
              items:
                $ref: '#/components/schemas/EntityRelation'
              description: The relations that this entity has with other entities.
            spec:
              $ref: '#/components/schemas/JsonObject'
            metadata:
              $ref: '#/components/schemas/EntityMeta'
            kind:
              type: string
              description: The high level entity type being described.
            apiVersion:
              type: string
              description: |-
                The version of specification format for this particular entity that
                this is written against.
          required:
            - metadata
            - kind
            - apiVersion
          description: The parts of the format that's common to all versions/kinds of entity.
        - type: 'null'
    EntityAncestryResponse:
      type: object
      properties:
        items:
          type: array
          items:
            type: object
            properties:
              parentEntityRefs:
                items:
                  type: string
                type: array
              entity:
                $ref: '#/components/schemas/Entity'
            required:
              - parentEntityRefs
              - entity
        rootEntityRef:
          type: string
      required:
        - items
        - rootEntityRef
      additionalProperties: false
    EntitiesBatchResponse:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/NullableEntity'
          description: |-
            The list of entities, in the same order as the refs in the request. Entries
            that are null signify that no entity existed with that ref.
      required:
        - items
      additionalProperties: false
    EntityFacet:
      type: object
      properties:
        value:
          type: string
        count:
          type: number
      required:
        - value
        - count
      additionalProperties: false
    EntityFacetsResponse:
      type: object
      properties:
        facets:
          type: object
          additionalProperties:
            type: array
            items:
              $ref: '#/components/schemas/EntityFacet'
      required:
        - facets
      additionalProperties: false
    Location:
      type: object
      properties:
        target:
          type: string
        type:
          type: string
        id:
          type: string
        entityRef:
          type: string
          description: The entity ref of the corresponding Location kind entity, e.g. location:default/generated-<sha1hex>.
      required:
        - target
        - type
        - id
        - entityRef
      description: Entity location for a specific entity.
      additionalProperties: false
    LocationSpec:
      type: object
      properties:
        target:
          type: string
        type:
          type: string
      required:
        - target
        - type
      description: Holds the entity location information.
      additionalProperties: false
    LocationsQueryResponse:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/Location'
          description: The list of locations paginated by a specific query.
        totalItems:
          type: number
        pageInfo:
          type: object
          properties:
            nextCursor:
              type: string
              description: The cursor for the next batch of locations.
      required:
        - items
        - totalItems
        - pageInfo
      additionalProperties: false
    AnalyzeLocationExistingEntity:
      type: object
      properties:
        entity:
          $ref: '#/components/schemas/Entity'
        isRegistered:
          type: boolean
        location:
          $ref: '#/components/schemas/LocationSpec'
      required:
        - entity
        - isRegistered
        - location
      description: |-
        If the folder pointed to already contained catalog info yaml files, they are
        read and emitted like this so that the frontend can inform the user that it
        located them and can make sure to register them as well if they weren't
        already
      additionalProperties: false
    RecursivePartialEntityRelation:
      type: object
      properties:
        targetRef:
          type: string
          description: The entity ref of the target of this relation.
        type:
          type: string
          description: The type of the relation.
      description: A relation of a specific type to another entity in the catalog.
      additionalProperties: false
    RecursivePartialEntityMeta:
      allOf:
        - $ref: '#/components/schemas/JsonObject'
        - type: object
          properties:
            links:
              type: array
              items:
                $ref: '#/components/schemas/EntityLink'
              description: A list of external hyperlinks related to the entity.
            tags:
              type: array
              items:
                type: string
              description: |-
                A list of single-valued strings, to for example classify catalog entities in
                various ways.
            annotations:
              $ref: '#/components/schemas/MapStringString'
            labels:
              $ref: '#/components/schemas/MapStringString'
            description:
              type: string
              description: |-
                A short (typically relatively few words, on one line) description of the
                entity.
            title:
              type: string
              description: |-
                A display name of the entity, to be presented in user interfaces instead
                of the `name` property above, when available.
                This field is sometimes useful when the `name` is cumbersome or ends up
                being perceived as overly technical. The title generally does not have
                as stringent format requirements on it, so it may contain special
                characters and be more explanatory. Do keep it very short though, and
                avoid situations where a title can be confused with the name of another
                entity, or where two entities share a title.
                Note that this is only for display purposes, and may be ignored by some
                parts of the code. Entity references still always make use of the `name`
                property, not the title.
            namespace:
              type: string
              description: The namespace that the entity belongs to.
            name:
              type: string
              description: |-
                The name of the entity.
                Must be unique within the catalog at any given point in time, for any
                given namespace + kind pair. This value is part of the technical
                identifier of the entity, and as such it will appear in URLs, database
                tables, entity references, and similar. It is subject to restrictions
                regarding what characters are allowed.
                If you want to use a different, more human readable string with fewer
                restrictions on it in user interfaces, see the `title` field below.
            etag:
              type: string
              description: |-
                An opaque string that changes for each update operation to any part of
                the entity, including metadata.
                This field can not be set by the user at creation time, and the server
                will reject an attempt to do so. The field will be populated in read
                operations. The field can (optionally) be specified when performing
                update or delete operations, and the server will then reject the
                operation if it does not match the current stored value.
            uid:
              type: string
              description: |-
                A globally unique ID for the entity.
                This field can not be set by the user at creation time, and the server
                will reject an attempt to do so. The field will be populated in read
                operations. The field can (optionally) be specified when performing
                update or delete operations, but the server is free to reject requests
                that do so in such a way that it breaks semantics.
          description: Metadata fields common to all versions/kinds of entity.
      additionalProperties: false
    RecursivePartialEntity:
      type: object
      properties:
        apiVersion:
          type: string
          description: |-
            The version of specification format for this particular entity that
            this is written against.
        kind:
          type: string
          description: The high level entity type being described.
        metadata:
          $ref: '#/components/schemas/RecursivePartialEntityMeta'
        spec:
          $ref: '#/components/schemas/JsonObject'
        relations:
          type: array
          items:
            $ref: '#/components/schemas/RecursivePartialEntityRelation'
          description: The relations that this entity has with other entities.
      description: Makes all keys of an entire hierarchy optional.
      additionalProperties: false
    AnalyzeLocationEntityField:
      type: object
      properties:
        description:
          type: string
          description: |-
            A text to show to the user to inform about the choices made. Like, it could say
            "Found a CODEOWNERS file that covers this target, so we suggest leaving this
            field empty; which would currently make it owned by X" where X is taken from the
            codeowners file.
        value:
          oneOf:
            - type: string
            - type: 'null'
        state:
          type: string
          enum:
            - analysisSuggestedValue
            - analysisSuggestedNoValue
            - needsUserInput
          description: The outcome of the analysis for this particular field
        field:
          type: string
          description: |-
            e.g. "spec.owner"? The frontend needs to know how to "inject" the field into the
            entity again if the user wants to change it
      required:
        - description
        - value
        - state
        - field
      additionalProperties: false
    AnalyzeLocationGenerateEntity:
      type: object
      properties:
        fields:
          type: array
          items:
            $ref: '#/components/schemas/AnalyzeLocationEntityField'
        entity:
          $ref: '#/components/schemas/RecursivePartialEntity'
      required:
        - fields
        - entity
      description: |-
        This is some form of representation of what the analyzer could deduce.
        We should probably have a chat about how this can best be conveyed to
        the frontend. It'll probably contain a (possibly incomplete) entity, plus
        enough info for the frontend to know what form data to show to the user
        for overriding/completing the info.
      additionalProperties: false
    AnalyzeLocationResponse:
      type: object
      properties:
        generateEntities:
          items:
            $ref: '#/components/schemas/AnalyzeLocationGenerateEntity'
          type: array
        existingEntityFiles:
          items:
            $ref: '#/components/schemas/AnalyzeLocationExistingEntity'
          type: array
      required:
        - generateEntities
        - existingEntityFiles
      additionalProperties: false
    LocationInput:
      type: object
      properties:
        type:
          type: string
        target:
          type: string
      required:
        - type
        - target
      additionalProperties: false
    EntitiesQueryResponse:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/Entity'
          description: The list of entities paginated by a specific filter.
        totalItems:
          type: number
        pageInfo:
          type: object
          properties:
            nextCursor:
              type: string
              description: The cursor for the next batch of entities.
            prevCursor:
              type: string
              description: The cursor for the previous batch of entities.
      required:
        - items
        - totalItems
        - pageInfo
      additionalProperties: false
  securitySchemes:
    JWT:
      type: http
      scheme: bearer
      bearerFormat: JWT
paths:
  /refresh:
    post:
      operationId: RefreshEntity
      tags:
        - Entity
      description: Refresh the entity related to entityRef.
      responses:
        '200':
          description: Refreshed
        '400':
          $ref: '#/components/responses/ErrorResponse'
        default:
          $ref: '#/components/responses/ErrorResponse'
      security:
        - {}
        - JWT: []
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                authorizationToken:
                  type: string
                entityRef:
                  type: string
                  description: The reference to a single entity that should be refreshed
              required:
                - entityRef
              description: Options for requesting a refresh of entities in the catalog.
              additionalProperties: false
  /entities:
    get:
      operationId: GetEntities
      tags:
        - Entity
      description: Get all entities matching a given filter.
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Entity'
        '400':
          $ref: '#/components/responses/ErrorResponse'
        default:
          $ref: '#/components/responses/ErrorResponse'
      security:
        - {}
        - JWT: []
      parameters:
        - $ref: '#/components/parameters/fields'
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/filter'
        - $ref: '#/components/parameters/offset'
        - $ref: '#/components/parameters/after'
        - name: order
          in: query
          allowReserved: true
          required: false
          schema:
            type: array
            items:
              type: string
  /entities/by-uid/{uid}:
    get:
      operationId: GetEntityByUid
      tags:
        - Entity
      description: Get a single entity by the UID.
      responses:
        '200':
          description: Ok
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Entity'
        '400':
          $ref: '#/components/responses/ErrorResponse'
        default:
          $ref: '#/components/responses/ErrorResponse'
      security:
        - {}
        - JWT: []
      parameters:
        - $ref: '#/components/parameters/uid'
    delete:
      operationId: DeleteEntityByUid
      tags:
        - Entity
      description: Delete a single entity by UID.
      responses:
        '204':
          description: Deleted success

# --- truncated at 32 KB (48 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/backstage/refs/heads/main/openapi/backstage-catalog-backend-openapi.yaml