The Entities API from Port — 11 operation(s) for entities.
openapi: 3.1.0
info:
title: Port Action Runs Entities API
version: '1.0'
tags:
- name: Entities
paths:
/v1/blueprints/{blueprint_identifier}/entities:
post:
summary: Create an entity
tags:
- Entities
description: This route allows you to create an entity in your software catalog based on an existing blueprint in your data model. It can also be used to overwrite or update an existing entity.<br/><br/>To learn more about entities, check out the [documentation](https://docs.port.io/build-your-software-catalog/sync-data-to-catalog/#entities).
requestBody:
content:
application/json:
schema:
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.
- $ref: '#/components/schemas/def-5'
title: Search query
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: Additional query
$ref: '#/components/schemas/def-6'
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/build-your-software-catalog/customize-integrations/configure-mapping#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'
- $ref: '#/components/schemas/def-6'
additionalProperties: true
example:
identifier: new-microservice
title: MyNewMicroservice
icon: Microservice
team: []
properties:
content: my content
relations: {}
parameters:
- schema:
type: boolean
default: false
in: query
name: upsert
required: true
description: If `true`, this call will override the entire entity/ies, if it/they already exist/s.
- schema:
type: boolean
default: false
in: query
name: validation_only
required: false
description: If `true`, this call will only validate the entity/ies and return the validation errors.
- schema:
type: boolean
default: false
in: query
name: create_missing_related_entities
required: false
description: If `true`, this call will also create missing related entities.<br/>This is useful when you want to create an entity and its related entities in one call, or if you want to create an entity whose related entity does not exist yet.
- schema:
type: boolean
default: false
in: query
name: merge
required: false
description: If `true` and `upsert` is also `true`, this call will update the entity/ies, if it/they already exist/s.
- schema:
type: string
in: query
name: run_id
required: false
description: You can provide a `run_id` to associate the created entities with a specific [action run](https://docs.port.io/create-self-service-experiences/reflect-action-progress/#tying-entities-to-an-action-run).
- schema:
type: string
in: query
name: ocean_info_resync_id
required: false
description: Resync run identifier. Only valid when `ocean_info_event_type` is `resync`.
- schema:
type: string
enum:
- http_request
- resync
- start
in: query
name: ocean_info_event_type
required: false
description: How the operation was triggered.
- schema:
type: string
minLength: 1
in: path
name: blueprint_identifier
required: true
description: The identifier of the blueprint to operate on.
security:
- bearer: []
responses:
'201':
description: Created successfully.
content:
application/json:
schema:
description: Created 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.
- $ref: '#/components/schemas/def-5'
title: Search query
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: Additional query
$ref: '#/components/schemas/def-6'
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/build-your-software-catalog/customize-integrations/configure-mapping#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'
- $ref: '#/components/schemas/def-6'
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
'413':
description: Request body is too large (limit is 1MiB)
content:
application/json:
schema:
properties:
ok:
const: false
error:
type: string
message:
type: string
required:
- ok
- error
additionalProperties: false
description: Request body is too large (limit is 1MiB)
'422':
description: The json provided does not match the route's schema
content:
application/json:
schema:
properties:
ok:
const: false
error:
type: string
message:
type: string
required:
- ok
- error
- message
additionalProperties: false
description: The json provided does not match the route's schema
get:
summary: Get all entities of a blueprint
tags:
- Entities
description: This route allows you to fetch all entities in your software catalog based on a given blueprint.<br/><br/>To learn more about entities, check out the [documentation](https://docs.port.io/build-your-software-catalog/sync-data-to-catalog/#entities).
parameters:
- schema:
type: boolean
default: false
in: query
name: exclude_calculated_properties
required: false
description: If `true`, [calculated properties](https://docs.getport.io/build-your-software-catalog/customize-integrations/configure-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/build-your-software-catalog/sync-data-to-catalog/#json-structure). Only these values will be returned in the response.<br/>For example: `{ "properties.propertyIdentifier","identifier"}`.'
- 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/build-your-software-catalog/sync-data-to-catalog/#json-structure) to be ommitted from the response.<br/>For example: `{ "properties.propertyIdentifier","identifier"}`'
- 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: blueprint_identifier
required: true
description: The identifier of the blueprint to operate on.
security:
- bearer:
- read:entities
responses:
'200':
description: Retrieved successfully.
content:
application/json:
schema:
description: Retrieved successfully.
type: object
properties:
ok:
enum:
- true
entities:
type: array
items:
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.
- $ref: '#/components/schemas/def-5'
title: Search query
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: Additional query
$ref: '#/components/schemas/def-6'
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/build-your-software-catalog/customize-integrations/configure-mapping#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'
- $ref: '#/components/schemas/def-6'
additionalProperties: false
required:
- entities
- 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
/v1/blueprints/{blueprint_identifier}/entities/bulk:
post:
summary: Create multiple entities
tags:
- Entities
description: This route allows you to create multiple entities (No more than 20 entities per request) in your software catalog based on an existing blueprint in your data model. It can also be used to overwrite or update existing entities.<br/><br/>To learn more about entities, check out the [documentation](https://docs.port.io/build-your-software-catalog/sync-data-to-catalog/#entities).<br/><br/> **Note:** A failure response does not necessarily mean that all entities failed. A `207 Multi-Status` response indicates that some entities were successfully created while others failed.
requestBody:
content:
application/json:
schema:
type: object
properties:
entities:
type: array
items:
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.
- $ref: '#/components/schemas/def-5'
title: Search query
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: Additional query
$ref: '#/components/schemas/def-6'
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/build-your-software-catalog/customize-integrations/configure-mapping#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'
- $ref: '#/components/schemas/def-6'
additionalProperties: true
description: Array of entities to create
minItems: 1
maxItems: 20
required:
- entities
additionalProperties: false
required: true
parameters:
- schema:
type: boolean
default: false
in: query
name: upsert
required: true
description: If `true`, this call will override the entire entity/ies, if it/they already exist/s.
- schema:
type: boolean
default: false
in: query
name: validation_only
required: false
description: If `true`, this call will only validate the entity/ies and return the validation errors.
- schema:
type: boolean
default: false
in: query
name: create_missing_related_entities
required: false
description: If `true`, this call will also create missing related entities.<br/>This is useful when you want to create an entity and its related entities in one call, or if you want to create an entity whose related entity does not exist yet.
- schema:
type: boolean
default: false
in: query
name: merge
required: false
description: If `true` and `upsert` is also `true`, this call will update the entity/ies, if it/they already exist/s.
- schema:
type: string
in: query
name: run_id
required: false
description: You can provide a `run_id` to associate the created entities with a specific [action run](https://docs.port.io/create-self-service-experiences/reflect-action-progress/#tying-entities-to-an-action-run).
- schema:
type: string
in: query
name: ocean_info_resync_id
required: false
description: Resync run identifier. Only valid when `ocean_info_event_type` is `resync`.
- schema:
type: string
enum:
- http_request
- resync
- start
in: query
name: ocean_info_event_type
required: false
description: How the operation was triggered.
- schema:
type: string
minLength: 1
in: path
name: blueprint_identifier
required: true
description: The identifier of the blueprint to operate on.
security:
- bearer: []
responses:
'200':
description: Created successfully.
content:
application/json:
schema:
description: Created successfully.
type: object
properties:
ok:
type: boolean
maxBulkSize:
type: number
entities:
type: array
items:
type: object
properties:
created:
type: boolean
identifier:
type: string
index:
type: number
additionalData:
type: object
additionalProperties: true
required:
- created
- identifier
- index
errors:
type: array
items:
type: object
properties:
identifier:
type: string
index:
type: number
statusCode:
type: number
error:
type: string
message:
type: string
required:
- identifier
- index
- statusCode
- error
- message
description: Failed entities with error details
required:
- ok
- entities
- errors
- ok
additionalProperties: false
'207':
description: Partially created successfully. Some entities were created while others failed.
content:
application/json:
schema:
description: Partially created successfully. Some entities were created while others failed.
type: object
properties:
ok:
type: boolean
maxBulkSize:
type: number
entities:
type: array
items:
type: object
properties:
created:
type: boolean
identifier:
type: string
index:
type: number
additionalData:
type: object
additionalProperties: true
required:
- created
- identifier
- index
errors:
type: array
items:
type: object
properties:
identifier:
type: string
index:
type: number
statusCode:
type: number
error:
type: string
message:
type: string
required:
- identifier
- index
- statusCode
- error
- message
description: Failed entities with error details
required:
- ok
- entities
- errors
- 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
'413':
description: Request body is too large (limit is 1MiB)
content:
application/json:
schema:
properties:
ok:
const: false
error:
type: string
message:
type: string
required:
- ok
- error
additionalProperties: false
description: Request body is too large (limit is 1MiB)
'422':
description: The json provided does not match the route's schema
content:
application/json:
schema:
properties:
ok:
const: false
error:
type: string
message:
type: string
required:
- ok
- error
- message
additionalProperties: false
description: The json provided does not match the route's schema
/v1/blueprints/{blueprint_identifier}/entities/{entity_identifier}:
patch:
summary: Update an entity
tags:
- Entities
description: This route allows you to edit a specific entity in your software catalog and update its properties.<br/><br/>To learn more about entities, check out the [documentation](https://docs.port.io/build-your-software-catalog/sync-data-to-catalog/#entities).
requestBody:
content:
application/json:
schema:
type: object
properties:
identifier:
type:
- string
pattern: ^(?!\.{1,2}$)[\p{L}0-9@_.+:\\/='-]+$
maxLength: 1000
description: The identifier of the entity.
title:
type:
- string
- 'null'
description: The title of the entity.
icon:
type:
- string
- 'null'
description: The icon of the entity.
team:
oneOf:
- type:
- string
- 'null'
- type: array
items:
type: string
- $ref: '#/components/schemas/def-6'
description: The Port team/s to which the entity will belong.
properties:
type: object
propertyNames:
pattern: ^[A-Za-z0-9@_=\\-]+$
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
descrip
# --- truncated at 32 KB (185 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/port/refs/heads/main/openapi/port-entities-api-openapi.yml