Get an entity
GET/v1/blueprints/:blueprint_identifier/entities/:entity_identifier
This route allows you to fetch a specific entity in your software catalog.
To learn more about entities, check out the documentation.
Request
Parameters (JSON)
{
"parameters": [
{
"schema": {
"type": "boolean",
"default": false
},
"in": "query",
"name": "exclude_calculated_properties",
"required": false,
"description": "If `true`, [calculated properties](https://docs.port.io/context-lake/data-model/setup-blueprint/properties/calculation-property/) will be excluded from the entities."
},
{
"schema": {
"type": "array",
"items": {
"type": "string"
}
},
"in": "query",
"name": "include",
"required": false,
"description": "An array of values from the [entity JSON](https://docs.port.io/context-lake/ingestion/ingest-data-into-port/native-integrations/overview/#json-structure). Only these values will be returned in the response.<br/>For example: `{ \"properties.propertyIdentifier\",\"identifier\"}`.",
"style": "form",
"explode": true
},
{
"schema": {
"type": "array",
"items": {
"type": "string"
}
},
"in": "query",
"name": "exclude",
"required": false,
"description": "An array of values from the [entity JSON](https://docs.port.io/context-lake/ingestion/ingest-data-into-port/native-integrations/overview/#json-structure) to be ommitted from the response.<br/>For example: `{ \"properties.propertyIdentifier\",\"identifier\"}`",
"style": "form",
"explode": true
},
{
"schema": {
"type": "boolean",
"default": false
},
"in": "query",
"name": "attach_title_to_relation",
"required": false
},
{
"schema": {
"type": "boolean",
"default": false
},
"in": "query",
"name": "attach_identifier_to_title_mirror_properties",
"required": false
},
{
"schema": {
"type": "boolean",
"default": false
},
"in": "query",
"name": "allow_partial_results",
"required": false,
"description": "When enabled allows some of the blueprint searches to fail without failing the full request."
},
{
"schema": {
"type": "string",
"minLength": 1
},
"in": "path",
"name": "entity_identifier",
"required": true,
"description": "The identifier of the entity to operate on."
},
{
"schema": {
"type": "string",
"minLength": 1
},
"in": "path",
"name": "blueprint_identifier",
"required": true,
"description": "The identifier of the blueprint to operate on."
}
]
}Request body schema (JSON)
{
"title": "Body"
}Responses
- 200
- 401
- 404
Retrieved successfully.
Default Response
A resource with the provided identifier was not found
Responses (JSON)
{
"responses": {
"200": {
"description": "Retrieved successfully.",
"content": {
"application/json": {
"schema": {
"description": "Retrieved successfully.",
"type": "object",
"properties": {
"ok": {
"enum": [
true
]
},
"entity": {
"type": "object",
"properties": {
"identifier": {
"oneOf": [
{
"type": [
"string"
],
"pattern": "^(?!\\.{1,2}$)[\\p{L}0-9@_.+:\\\\/='-]+$",
"maxLength": 1000,
"title": "String identifier",
"description": "The identifier of the entity."
},
{
"title": "Search identifier query",
"type": "object",
"properties": {
"combinator": {
"enum": [
"and",
"or"
]
},
"rules": {
"type": "array",
"description": "A search query to define the entity's identifier based on a property of the entity.<br/>Read more [here](https://docs.port.io/context-lake/ingestion/configure-mapping/overview#map-by-property).",
"items": {
"anyOf": [
{
"type": "object",
"title": "`=` rule",
"properties": {
"property": {
"type": "string"
},
"operator": {
"enum": [
"="
]
},
"value": {
"anyOf": [
{
"type": "string",
"title": "String"
},
{
"type": "number",
"title": "Number"
},
{
"type": "null"
}
]
}
},
"additionalProperties": false,
"required": [
"property",
"operator",
"value"
]
},
{
"type": "object",
"title": "`in` rule",
"properties": {
"property": {
"type": "string"
},
"operator": {
"enum": [
"in",
"containsAny"
]
},
"value": {
"type": "array",
"items": {
"type": "string"
},
"errorMessage": "must be an array of strings when the operator is 'in' or 'containsAny'"
}
},
"additionalProperties": false,
"required": [
"property",
"operator",
"value"
]
},
{
"type": "object",
"title": "`contains` rule",
"properties": {
"property": {
"type": "string"
},
"operator": {
"enum": [
"contains"
]
},
"value": {
"anyOf": [
{
"type": "string"
},
{
"type": "array",
"items": {
"type": "string"
}
},
{
"type": "null"
}
]
}
},
"additionalProperties": false,
"required": [
"property",
"operator",
"value"
]
},
{
"allOf": [
"circular(Search identifier query)",
{
"title": "Nested query"
}
]
}
]
}
}
},
"required": [
"combinator",
"rules"
],
"additionalProperties": false
}
]
},
"title": {
"type": "string",
"description": "The title of the entity."
},
"icon": {
"type": "string",
"description": "The icon of the entity."
},
"team": {
"oneOf": [
{
"title": "Team (Single)",
"type": "string",
"description": "The Port team/s to which the entity will belong."
},
{
"title": "Teams (Multiple)",
"type": "array",
"items": {
"type": "string"
},
"description": "The Port team/s to which the entity will belong."
},
{
"title": "Search relations query",
"type": "object",
"properties": {
"combinator": {
"enum": [
"and",
"or"
]
},
"rules": {
"type": "array",
"description": "A search query to define the entity's identifier based on a property of the entity.<br/>Read more [here](https://docs.port.io/context-lake/ingestion/configure-mapping/overview#map-by-property).",
"items": {
"anyOf": [
{
"type": "object",
"title": "`=` rule",
"properties": {
"property": {
"type": "string"
},
"operator": {
"enum": [
"="
]
},
"value": {
"anyOf": [
{
"type": "string",
"title": "String"
},
{
"type": "number",
"title": "Number"
},
{
"type": "null"
}
]
}
},
"additionalProperties": false,
"required": [
"property",
"operator",
"value"
]
},
{
"type": "object",
"title": "`in` rule",
"properties": {
"property": {
"type": "string"
},
"operator": {
"enum": [
"in",
"containsAny"
]
},
"value": {
"type": "array",
"items": {
"type": "string"
},
"errorMessage": "must be an array of strings when the operator is 'in' or 'containsAny'"
}
},
"additionalProperties": false,
"required": [
"property",
"operator",
"value"
]
},
{
"type": "object",
"title": "`contains` rule",
"properties": {
"property": {
"type": "string"
},
"operator": {
"enum": [
"contains"
]
},
"value": {
"anyOf": [
{
"type": "string"
},
{
"type": "array",
"items": {
"type": "string"
}
},
{
"type": "null"
}
]
}
},
"additionalProperties": false,
"required": [
"property",
"operator",
"value"
]
},
{
"allOf": [
"circular(Search relations query)",
{
"title": "Nested query"
}
]
}
]
}
}
},
"required": [
"combinator",
"rules"
],
"additionalProperties": false
},
{
"title": "Union source slice",
"description": "Only valid when the blueprint's \"ownership.union\" is enabled: a single source key mapped to that source's slice of owning teams, as in `{ \"<sourceKey>\": [\"team-a\"] }`. The slice may also be a search query.",
"type": "object",
"minProperties": 1,
"maxProperties": 1,
"additionalProperties": {
"anyOf": [
{
"type": [
"array",
"null"
],
"items": {
"type": "string"
}
},
{
"title": "Search relations query",
"type": "object",
"properties": {
"combinator": {
"enum": [
"and",
"or"
]
},
"rules": {
"type": "array",
"description": "A search query to define the entity's identifier based on a property of the entity.<br/>Read more [here](https://docs.port.io/context-lake/ingestion/configure-mapping/overview#map-by-property).",
"items": {
"anyOf": [
{
"type": "object",
"title": "`=` rule",
"properties": {
"property": {
"type": "string"
},
"operator": {
"enum": [
"="
]
},
"value": {
"anyOf": [
{
"type": "string",
"title": "String"
},
{
"type": "number",
"title": "Number"
},
{
"type": "null"
}
]
}
},
"additionalProperties": false,
"required": [
"property",
"operator",
"value"
]
},
{
"type": "object",
"title": "`in` rule",
"properties": {
"property": {
"type": "string"
},
"operator": {
"enum": [
"in",
"containsAny"
]
},
"value": {
"type": "array",
"items": {
"type": "string"
},
"errorMessage": "must be an array of strings when the operator is 'in' or 'containsAny'"
}
},
"additionalProperties": false,
"required": [
"property",
"operator",
"value"
]
},
{
"type": "object",
"title": "`contains` rule",
"properties": {
"property": {
"type": "string"
},
"operator": {
"enum": [
"contains"
]
},
"value": {
"anyOf": [
{
"type": "string"
},
{
"type": "array",
"items": {
"type": "string"
}
},
{
"type": "null"
}
]
}
},
"additionalProperties": false,
"required": [
"property",
"operator",
"value"
]
},
{
"allOf": [
"circular(Search relations query)",
{
"title": "Nested query"
}
]
}
]
}
}
},
"required": [
"combinator",
"rules"
],
"additionalProperties": false
}
]
}
}
]
},
"properties": {
"type": "object",
"default": {},
"description": "An object containing the properties of the entity, in `\"key\":\"value\"` pairs where the `key` is the property's identifier, and the `value` is its value."
},
"relations": {
"type": "object",
"description": "An object containing the relations of the entity, in `\"key\":\"value\"` pairs where the `key` is the relation's identifier, and the `value` is the related entity's identifier for single-relations, or an array of identifiers for many-relations.<br/>You can also use a [search query](https://docs.port.io/context-lake/ingestion/configure-mapping/configuration-methods#mapping-relations-using-search-queries) to define relations based on a property of the related entity.",
"additionalProperties": {
"anyOf": [
{
"type": "string",
"pattern": "^(?!\\.{1,2}$)[\\p{L}0-9@_.+:\\\\/='-]+$",
"maxLength": 1000,
"title": "string"
},
{
"type": "array",
"items": {
"type": "string",
"pattern": "^(?!\\.{1,2}$)[\\p{L}0-9@_.+:\\\\/='-]+$"
},
"title": "array"
},
{
"type": "null",
"title": "null"
},
{
"title": "Search relations query",
"type": "object",
"properties": {
"combinator": {
"enum": [
"and",
"or"
]
},
"rules": {
"type": "array",
"description": "A search query to define the entity's identifier based on a property of the entity.<br/>Read more [here](https://docs.port.io/context-lake/ingestion/configure-mapping/overview#map-by-property).",
"items": {
"anyOf": [
{
"type": "object",
"title": "`=` rule",
"properties": {
"property": {
"type": "string"
},
"operator": {
"enum": [
"="
]
},
"value": {
"anyOf": [
{
"type": "string",
"title": "String"
},
{
"type": "number",
"title": "Number"
},
{
"type": "null"
}
]
}
},
"additionalProperties": false,
"required": [
"property",
"operator",
"value"
]
},
{
"type": "object",
"title": "`in` rule",
"properties": {
"property": {
"type": "string"
},
"operator": {
"enum": [
"in",
"containsAny"
]
},
"value": {
"type": "array",
"items": {
"type": "string"
},
"errorMessage": "must be an array of strings when the operator is 'in' or 'containsAny'"
}
},
"additionalProperties": false,
"required": [
"property",
"operator",
"value"
]
},
{
"type": "object",
"title": "`contains` rule",
"properties": {
"property": {
"type": "string"
},
"operator": {
"enum": [
"contains"
]
},
"value": {
"anyOf": [
{
"type": "string"
},
{
"type": "array",
"items": {
"type": "string"
}
},
{
"type": "null"
}
]
}
},
"additionalProperties": false,
"required": [
"property",
"operator",
"value"
]
},
{
"allOf": [
"circular(Search relations query)",
{
"title": "Nested query"
}
]
}
]
}
}
},
"required": [
"combinator",
"rules"
],
"additionalProperties": false
},
{
"title": "Union source slice",
"description": "Only valid for relations with \"union\" enabled: a single source key mapped to that source's slice of targets, as in `{ \"<sourceKey>\": [\"target-id\"] }`. The slice may also be a search query.",
"type": "object",
"minProperties": 1,
"maxProperties": 1,
"additionalProperties": {
"anyOf": [
{
"type": [
"array",
"null"
],
"items": {
"type": "string",
"pattern": "^(?!\\.{1,2}$)[\\p{L}0-9@_.+:\\\\/='-]+$"
}
},
{
"title": "Search relations query",
"type": "object",
"properties": {
"combinator": {
"enum": [
"and",
"or"
]
},
"rules": {
"type": "array",
"description": "A search query to define the entity's identifier based on a property of the entity.<br/>Read more [here](https://docs.port.io/context-lake/ingestion/configure-mapping/overview#map-by-property).",
"items": {
"anyOf": [
{
"type": "object",
"title": "`=` rule",
"properties": {
"property": {
"type": "string"
},
"operator": {
"enum": [
"="
]
},
"value": {
"anyOf": [
{
"type": "string",
"title": "String"
},
{
"type": "number",
"title": "Number"
},
{
"type": "null"
}
]
}
},
"additionalProperties": false,
"required": [
"property",
"operator",
"value"
]
},
{
"type": "object",
"title": "`in` rule",
"properties": {
"property": {
"type": "string"
},
"operator": {
"enum": [
"in",
"containsAny"
]
},
"value": {
"type": "array",
"items": {
"type": "string"
},
"errorMessage": "must be an array of strings when the operator is 'in' or 'containsAny'"
}
},
"additionalProperties": false,
"required": [
"property",
"operator",
"value"
]
},
{
"type": "object",
"title": "`contains` rule",
"properties": {
"property": {
"type": "string"
},
"operator": {
"enum": [
"contains"
]
},
"value": {
"anyOf": [
{
"type": "string"
},
{
"type": "array",
"items": {
"type": "string"
}
},
{
"type": "null"
}
]
}
},
"additionalProperties": false,
"required": [
"property",
"operator",
"value"
]
},
{
"allOf": [
"circular(Search relations query)",
{
"title": "Nested query"
}
]
}
]
}
}
},
"required": [
"combinator",
"rules"
],
"additionalProperties": false
}
]
}
}
]
}
}
},
"additionalProperties": false
}
},
"required": [
"entity",
"ok"
],
"additionalProperties": false
}
}
}
},
"401": {
"description": "Default Response",
"content": {
"application/json": {
"schema": {
"properties": {
"ok": {
"const": false
},
"error": {
"type": "string"
},
"message": {
"type": "string"
}
},
"required": [
"ok",
"error"
],
"additionalProperties": false
}
}
}
},
"404": {
"description": "A resource with the provided identifier was not found",
"content": {
"application/json": {
"schema": {
"properties": {
"ok": {
"const": false
},
"error": {
"type": "string"
},
"message": {
"type": "string"
}
},
"required": [
"ok",
"error",
"message"
],
"additionalProperties": false,
"description": "A resource with the provided identifier was not found"
}
}
}
}
}
}