---
title: "POST /analyze-location"
method: POST
path: "/analyze-location"
tags: ["Locations"]
---

# POST /analyze-location

`POST /analyze-location`

Validate a given location.

## Request body

- object
  - `catalogFileName` string
  - `location` LocationInput, required
    - `type` string, required
    - `target` string, required

## Response `200`

Ok

- AnalyzeLocationResponse
  - `generateEntities` AnalyzeLocationGenerateEntity[], required
    - `fields` AnalyzeLocationEntityField[], required
      - `description` string, required — 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` string, nullable, required
      - `state` 'analysisSuggestedValue' | 'analysisSuggestedNoValue' | 'needsUserInput', required — The outcome of the analysis for this particular field
      - `field` string, required — 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
    - `entity` RecursivePartialEntity, required — Makes all keys of an entire hierarchy optional.
      - `apiVersion` string — The version of specification format for this particular entity that this is written against.
      - `kind` string — The high level entity type being described.
      - `metadata` RecursivePartialEntityMeta — Metadata fields common to all versions/kinds of entity.
        - `links` EntityLink[] — A list of external hyperlinks related to the entity.
          - `type` string — An optional value to categorize links into specific groups
          - `icon` string — An optional semantic key that represents a visual icon.
          - `title` string — An optional descriptive title for the link.
          - `url` string, required — The url to the external site, document, etc.
        - `tags` string[] — A list of single-valued strings, to for example classify catalog entities in various ways.
        - `annotations` MapStringString — Construct a type with a set of properties K of type T
        - `labels` MapStringString — Construct a type with a set of properties K of type T
        - `description` string — A short (typically relatively few words, on one line) description of the entity.
        - `title` string — 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` string — The namespace that the entity belongs to.
        - `name` string — 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` string — 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` string — 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.
      - `spec` JsonObject — A type representing all allowed JSON object values.
      - `relations` RecursivePartialEntityRelation[] — The relations that this entity has with other entities.
        - `targetRef` string — The entity ref of the target of this relation.
        - `type` string — The type of the relation.
  - `existingEntityFiles` AnalyzeLocationExistingEntity[], required
    - `entity` Entity, required — The parts of the format that's common to all versions/kinds of entity.
      - `relations` EntityRelation[] — The relations that this entity has with other entities.
        - `targetRef` string, required — The entity ref of the target of this relation.
        - `type` string, required — The type of the relation.
      - `spec` JsonObject — A type representing all allowed JSON object values.
      - `metadata` EntityMeta, required — Metadata fields common to all versions/kinds of entity.
        - `links` EntityLink[] — A list of external hyperlinks related to the entity.
          - `type` string — An optional value to categorize links into specific groups
          - `icon` string — An optional semantic key that represents a visual icon.
          - `title` string — An optional descriptive title for the link.
          - `url` string, required — The url to the external site, document, etc.
        - `tags` string[] — A list of single-valued strings, to for example classify catalog entities in various ways.
        - `annotations` MapStringString — Construct a type with a set of properties K of type T
        - `labels` MapStringString — Construct a type with a set of properties K of type T
        - `description` string — A short (typically relatively few words, on one line) description of the entity.
        - `title` string — 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` string — The namespace that the entity belongs to.
        - `name` string, required — 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` string — 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` string — 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.
      - `kind` string, required — The high level entity type being described.
      - `apiVersion` string, required — The version of specification format for this particular entity that this is written against.
    - `isRegistered` boolean, required
    - `location` LocationSpec, required — Holds the entity location information.
      - `target` string, required
      - `type` string, required

## Other responses

- `400` — An error response from the backend.
- `default` — An error response from the backend.

## Changes

> 37 revisions in range; 1 not diffed, 6 could not be searched.

- **2026-02-28** `bd79839d3afe` — 1 breaking
  - response property `generateEntities/items/fields/items/value` list-of-types was widened by adding types `null` to media type `application/json` of response `200`
- **2023-08-30** `13d29b2e3f77` — 1 breaking, 2 warning, 1 info
  - the response property `generateEntities/items/fields/items/value` became nullable for the status `200`
  - removed the request property `location/presence`
  - removed the optional property `existingEntityFiles/items/location/presence` from the response with the `200` status
  - the request property `catalogFileName` became optional
- **2023-08-30** `7e046a76d0a1` — 2 breaking, 1 info
  - added the new required request property `location/presence`
  - the request property `catalogFileName` became required
  - added the optional property `existingEntityFiles/items/location/presence` to the response with the `200` status
- **2023-08-23** `a40f510242e1` — 1 info
  - the request property `catalogFileName` became optional
- **2023-07-16** `bbfd7e881417` — 1 info
  - added the non-success response with the status `400`

[Full history](https://skmtc.dev/backstage/apis/catalog/changes/analyze-location/post.md)

---

[API](https://skmtc.dev/backstage/apis/catalog.md) · [All operations](https://skmtc.dev/backstage/apis/catalog/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/backstage/catalog/revisions/cf26233702b7/schema)