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.
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.
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.
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.
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.
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.
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.
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.
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.
To learn more about entities, check out the [documentation](https://docs.port.io/build-your-software-catalog/sync-data-to-catalog/#entities).
**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.
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.
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.
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
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.
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
- type: array
items:
type: string
pattern: ^(?!\.{1,2}$)[\p{L}0-9@_.+:\\/='-]+$
- type: 'null'
- $ref: '#/components/schemas/def-6'
additionalProperties: false
parameters:
- 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.
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: 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: 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.
security:
- bearer: []
responses:
'200':
description: Updated successfully.
content:
application/json:
schema:
description: Updated 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.
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
put:
summary: Change an entity
tags:
- Entities
description: This route allows you to edit a specific entity in your software catalog and update its properties.
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
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'
description: The Port team/s to which the entity will belong.
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.
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
- type: array
items:
type: string
pattern: ^(?!\.{1,2}$)[\p{L}0-9@_.+:\\/='-]+$
- type: 'null'
- $ref: '#/components/schemas/def-6'
additionalProperties: true
parameters:
- 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.
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: 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: 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.
security:
- bearer: []
responses:
'200':
description: Updated successfully.
content:
application/json:
schema:
description: Updated 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.
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 an entity
tags:
- Entities
description: This route allows you to fetch a specific entity in your software catalog.
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.
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.
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: 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.
security:
- bearer:
- read:entities
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.
- $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.
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
delete:
summary: Delete an entity
tags:
- Entities
description: This route allows you to delete a specific entity in your software catalog.
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: delete_dependents
required: true
description: If `true`, this call will also delete all entities with a relation to the deleted entity.
- 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: 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.
security:
- bearer: []
responses:
'200':
description: Entities deleted successfully
content:
application/json:
schema:
description: Entities deleted successfully
properties:
ok:
enum:
- true
required:
- 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-count:
get:
summary: Get a blueprint's entity count
tags:
- Entities
description: This route allows you to count the number of entities in a specific blueprint in your software catalog.
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: string
minLength: 1
in: path
name: blueprint_identifier
required: true
description: The identifier of the blueprint to operate on.
security:
- bearer: []
responses:
'200':
description: Retrieved successfully.
content:
application/json:
schema:
description: Retrieved successfully.
properties:
ok:
enum:
- true
count:
type: number
required:
- 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}/all-entities:
delete:
summary: Delete all entities of a blueprint
tags:
- Entities
description: This route allows you to delete all entities of a specific blueprint in your software catalog.
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: string
in: query
name: run_id
required: false
description: You can provide a `run_id` to associate the deleted 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: boolean
in: query
name: delete_blueprint
required: false
description: If `true`, this call will also delete the blueprint itself.
- 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: Entities deleted successfully
content:
application/json:
schema:
description: Entities deleted successfully
properties:
ok:
enum:
- true
required:
- 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}/bulk/entities/delete:
post:
summary: Delete multiple entities
tags:
- Entities
description: This route allows you to delete multiple entities (up to 100 entities per request) from a specific blueprint in your software catalog. All entities must belong to the same blueprint.
If any entity has dependent entities and delete_dependents is false, the entire operation will fail and no entities will be deleted.
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:
entities:
type: array
items:
type: string
description: Array of entity identifiers to delete
minItems: 1
maxItems: 100
required:
- entities
additionalProperties: false
required: true
parameters:
- schema:
type: boolean
default: false
in: query
name: delete_dependents
required: true
description: If `true`, this call will also delete all entities with a relation to the deleted entity.
- 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: Entities deleted successfully.
content:
application/json:
schema:
description: Entities deleted successfully.
type: object
properties:
ok:
enum:
- true
deletedEntities:
type: array
items:
type: string
description: Array of deleted entity IDs
maxBulkSize:
type: number
required:
- deletedEntities
- 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/entities/search:
post:
summary: Search entities
tags:
- Entities
description: This route allows you to search for entities in your software catalog based on a given set of rules.
To learn more about entities, check out the [documentation](https://docs.port.io/build-your-software-catalog/sync-data-to-catalog/#entities).
For more details about Port's search mechanism, rules, and operators - see the [search & query documentation](https://docs.port.io/search-and-query/overview).
requestBody:
content:
application/json:
schema:
type: object
properties:
combinator:
enum:
- and
- or
description: The combinator to use for the rules.
rules:
type: array
items:
anyOf:
- type: object
title: Date Rule
properties:
property:
oneOf:
- type: string
- type: object
properties:
property:
type: string
context:
type: string
enum:
- user
- userTeams
required:
- property
- context
operator:
enum:
- between
- notBetween
- '='
value:
type: object
oneOf:
- type: object
title: Date Range
properties:
from:
type: string
format: date-time
to:
type: string
format: date-time
required:
- from
- to
- type: object
title: Date Preset
properties:
preset:
type: string
enum:
- today
- tomorrow
- yesterday
- lastDay
- lastWeek
- last2Weeks
- lastMonth
- last3Months
- last6Months
- last12Months
- last2Years
- last3Years
- nextDay
- nextWeek
- next2Weeks
- nextMonth
- next3Months
- next6Months
- next12Months
required:
- preset
- type: object
properties:
property:
type: string
context:
type: string
enum:
- user
- userTeams
required:
- property
- context
required:
- property
- operator
- value
additionalProperties: false
- type: object
title: Empty Rule
oneOf:
- type: object
title: Empty Rule
properties:
operator:
enum:
- isEmpty
- isNotEmpty
property:
type: string
required:
- operator
- property
additionalProperties: false
- type: object
title: Number Rule
properties:
property:
oneOf:
- type: string
- type: object
properties:
property:
type: string
context:
type: string
enum:
- user
- userTeams
required:
- property
- context
operator:
enum:
- '>'
- '>='
- <
- <=
value:
anyOf:
- type: number
title: number
- type: string
format: date-time
title: date-time
- type: object
properties:
property:
type: string
context:
type: string
enum:
- user
- userTeams
required:
- property
- context
required:
- property
- operator
- value
additionalProperties: false
- type: object
title: Expired Rule
oneOf:
- type: object
title: Expired Rule
properties:
operator:
enum:
- isExpired
- isNotExpired
property:
type: string
required:
- operator
- property
additionalProperties: false
- type: object
title: String Rule
oneOf:
- type: object
title: String Rule
properties:
property:
oneOf:
- type: string
- type: object
properties:
property:
type: string
context:
type: string
enum:
- user
- userTeams
required:
- property
- context
operator:
enum:
- '='
- '!='
- containsAny
- contains
- doesNotContains
- beginsWith
- doesNotBeginsWith
- endsWith
- doesNotEndsWith
- in
- notIn
value:
anyOf:
- type: 'null'
title: 'null'
- type: string
title: string
- type: number
title: number
- type: boolean
title: boolean
- type: string
format: date-time
title: date-time
- type: array
items:
type: string
title: array
- type: array
items:
type: number
title: array
- type: array
items:
type: boolean
title: array
- type: array
items:
type: string
format: date-time
title: array
- type: object
properties:
property:
type: string
context:
type: string
enum:
- user
- userTeams
required:
- property
- context
additionalProperties: false
required:
- property
- operator
- value
- type: object
title: Relation Rule
properties:
operator:
enum:
- relatedTo
blueprint:
type: string
value:
anyOf:
- type: string
title: string
- type: array
items:
type: string
title: array
direction:
enum:
- upstream
- downstream
required:
type: boolean
additionalProperties: false
required:
- operator
- value
- blueprint
- type: object
title: Property schema rule
properties:
propertySchema:
type: object
properties:
type:
type: string
format:
type: string
items:
type: object
properties:
type:
type: string
format:
type: string
required:
- type
required:
- type
additionalProperties: false
operator:
enum:
- '='
- '!='
- contains
value:
anyOf:
- type: 'null'
title: 'null'
- type: string
title: string
- type: number
title: number
- type: boolean
title: boolean
required:
- operator
- propertySchema
additionalProperties: false
- type: object
title: matchAny Rule
anyOf:
- type: object
properties:
property:
oneOf:
- type: object
properties:
path:
type: array
items:
anyOf:
- type: string
- type: object
properties:
relation:
type: string
maxHops:
type: number
minimum: 1
maximum: 15
fromBlueprint:
type: string
required:
- path
additionalProperties: false
- oneOf:
- type: string
- type: object
properties:
property:
type: string
context:
type: string
enum:
- user
- userTeams
required:
- property
- context
operator:
type: string
enum:
- matchAny
value:
anyOf:
- type: array
items:
type: string
- oneOf:
- type: string
- type: object
properties:
property:
type: string
context:
type: string
enum:
- user
- userTeams
required:
- property
- context
required:
- property
- operator
- value
additionalProperties: false
- $ref: '#/components/schemas/def-1'
required:
- combinator
- rules
additionalProperties: false
example:
combinator: and
rules:
- property: $blueprint
operator: '='
value: service
- combinator: or
rules:
- property: environment
operator: '='
value: production
- property: environment
operator: '='
value: staging
required: true
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.
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.
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.
security:
- bearer:
- read:entities
responses:
'200':
description: Retrieved successfully (this response can be compressed).
content:
application/json:
schema:
description: Retrieved successfully (this response can be compressed).
type: object
properties:
ok:
enum:
- true
matchingBlueprints:
type: array
items:
type: string
failedBlueprints:
type: array
items:
type: string
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.
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
'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/search:
post:
summary: Search a blueprint's entities
tags:
- Entities
description: This route allows you to search your software catalog for a specific blueprint's entities, based on a given set of rules.
The returned entities are paginated for improved performance.
To learn more about entities, check out the [entity documentation](https://docs.port.io/build-your-software-catalog/sync-data-to-catalog/#entities).
For more details about Port's search mechanism, rules, and operators - see the [search & query documentation](https://docs.port.io/search-and-query/overview).
requestBody:
content:
application/json:
schema:
type: object
properties:
query:
$ref: '#/components/schemas/def-7'
description: A [search query](https://docs.getport.io/search-and-query/overview) used to filter the returned entities.
include:
type: array
items:
type: string
description: An array of [properties](https://docs.getport.io/build-your-software-catalog/customize-integrations/configure-data-model/setup-blueprint/properties) and/or [relations](https://docs.getport.io/build-your-software-catalog/customize-integrations/configure-data-model/setup-blueprint/relations) to include in the search, using their identifiers.
Note that for [meta-properties](https://docs.getport.io/build-your-software-catalog/customize-integrations/configure-data-model/setup-blueprint/properties/meta-properties) (e.g. `$createdAt`, `$updatedAt`), the `$` prefix must be used.
exclude:
type: array
items:
type: string
description: An array of [properties](https://docs.getport.io/build-your-software-catalog/customize-integrations/configure-data-model/setup-blueprint/properties) and/or [relations](https://docs.getport.io/build-your-software-catalog/customize-integrations/configure-data-model/setup-blueprint/relations) to exclude from the search, using their identifiers.
Note that for [meta-properties](https://docs.getport.io/build-your-software-catalog/customize-integrations/configure-data-model/setup-blueprint/properties/meta-properties) (e.g. `$createdAt`, `$updatedAt`), the `$` prefix must be used.
limit:
type: number
minimum: 1
maximum: 1000
default: 200
description: The maximum number of entities to return.
from:
type: string
description: A string hash of the `next` value that was returned in the previous response. This is used to paginate through the results.
additionalProperties: false
example:
query:
combinator: and
rules:
- property: $blueprint
operator: '='
value: service
- combinator: or
rules:
- property: environment
operator: '='
value: production
- property: environment
operator: '='
value: staging
include:
- $identifier
- $title
- $createdAt
parameters:
- schema:
type: string
minLength: 1
in: path
name: blueprint_identifier
required: true
description: The identifier of the blueprint whose entities you want to search.
security:
- bearer:
- read:entities
responses:
'200':
description: Retrieved successfully (this response can be compressed).
content:
application/json:
schema:
description: Retrieved successfully (this response can be compressed).
type: object
properties:
ok:
type: boolean
next:
type: string
description: A string hash of the next page of results. This is used to paginate through the results.
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.
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
description: The entities that match the search query.
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
'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/entities/aggregate:
post:
summary: Aggregate entities
tags:
- Entities
description: This route allows you to perform an aggregation function on a blueprint's entities based on a given set of rules.
To learn more about entities, check out the [documentation](https://docs.port.io/build-your-software-catalog/sync-data-to-catalog/#entities).
For more details about Port's search mechanism, rules, and operators - see the [search & query documentation](https://docs.port.io/search-and-query/overview).
requestBody:
content:
application/json:
schema:
type: object
oneOf:
- type: object
title: Count entities
properties:
func:
type: string
enum:
- average
- count
averageOf:
type: string
enum:
- hour
- day
- week
- month
- total
measureTimeBy:
type: string
description: A property of type `datetime`, by which the average will be calculated. Relevant only for the `average` function.
calculationBy:
type: string
query:
$ref: '#/components/schemas/def-1'
description: A [search query](https://docs.getport.io/search-and-query/overview) used to filter the entities before the aggregation is calculated.
additionalProperties: false
required:
- func
- query
- type: object
title: Aggregate by property
properties:
property:
type: string
description: A property of type `number`, by which the aggregation will be calculated.
func:
type: string
enum:
- sum
- average
- min
- max
- median
averageOf:
type: string
enum:
- hour
- day
- week
- month
- total
measureTimeBy:
type: string
description: A property of type `datetime`, by which the average will be calculated. Relevant only for the `average` function.
calculationBy:
type: string
query:
$ref: '#/components/schemas/def-1'
description: A [search query](https://docs.getport.io/search-and-query/overview) used to filter the entities before the aggregation is calculated.
additionalProperties: false
required:
- func
- property
- query
- type: object
title: Count values
oneOf:
- type: object
title: Group by property
properties:
func:
enum:
- countValues
query:
$ref: '#/components/schemas/def-1'
property:
type: string
required:
- func
- query
- property
additionalProperties: false
- type: object
title: Group by relation
properties:
func:
enum:
- countValues
query:
$ref: '#/components/schemas/def-1'
relation:
type: string
required:
- func
- query
- relation
additionalProperties: false
- type: object
title: Group by scorecard
properties:
func:
enum:
- countValues
query:
$ref: '#/components/schemas/def-1'
scorecard:
type: string
required:
- func
- query
- scorecard
additionalProperties: false
- type: object
title: Group by scorecard rule
properties:
func:
enum:
- countValues
query:
$ref: '#/components/schemas/def-1'
rule:
type: string
scorecard:
type: string
required:
- func
- query
- rule
- scorecard
additionalProperties: false
security:
- bearer:
- read:entities
responses:
'200':
description: Retrieved successfully (this response can be compressed).
content:
application/json:
schema:
description: Retrieved successfully (this response can be compressed).
type: object
properties:
ok:
enum:
- true
matchingBlueprints:
type: array
items:
type: string
failedBlueprints:
type: array
items:
type: string
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.
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
'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/entities/aggregate-over-time:
post:
summary: Aggregate entities over time
tags:
- Entities
description: This route allows you to perform an aggregation function on a blueprint's entities over a given time range.
To learn more about entities, check out the [entity documentation](https://docs.port.io/build-your-software-catalog/sync-data-to-catalog/#entities).
For more details about Port's search mechanism, rules, and operators - see the [search & query documentation](https://docs.port.io/search-and-query/overview).
requestBody:
content:
application/json:
schema:
type: object
required:
- blueprint
- timeRange
- timeInterval
- query
- measureTimeBy
- aggregationType
oneOf:
- title: Aggregate property
properties:
blueprint:
type: string
description: The blueprint whose entities you wish to aggregate.
timeRange:
type: object
properties:
preset:
type: string
enum:
- today
- yesterday
- lastDay
- lastWeek
- last2Weeks
- lastMonth
- last3Months
- last6Months
- last12Months
- last2Years
- last3Years
- specific
timeZone:
type: string
required:
- preset
additionalProperties: false
timeInterval:
type: string
enum:
- hour
- day
- isoWeek
- month
- quarter
query:
$ref: '#/components/schemas/def-1'
description: A [search query](https://docs.getport.io/search-and-query/overview) used to filter the entities before the aggregation is calculated.
measureTimeBy:
type: string
description: A property of type `datetime` by which the aggregation will be calculated.
specificTimeRange:
type: array
items:
type: number
minItems: 2
maxItems: 2
description: A specific time range [min,max] to aggregate over. If not provided, the time range will be used.
aggregationType:
enum:
- aggregatePropertiesValues
func:
type: string
enum:
- average
- sum
- min
- max
- median
- last
properties:
type: array
items:
type: string
description: A list of properties of type `number` on which the aggregation will be calculated.
required:
- func
- properties
additionalProperties: false
allOf:
- if:
type: object
properties:
timeRange:
type: object
properties:
preset:
enum:
- last2Years
- last3Years
then:
type: object
properties:
timeInterval:
enum:
- quarter
- if:
type: object
properties:
timeRange:
type: object
properties:
preset:
enum:
- specific
required:
- timeRange
then:
type: object
properties:
specificTimeRange:
type: array
items:
type: number
minItems: 2
maxItems: 2
description: A specific time range [min,max] to aggregate over. If not provided, the time range will be used.
required:
- specificTimeRange
- title: Count entities
properties:
blueprint:
type: string
description: The blueprint whose entities you wish to aggregate.
timeRange:
type: object
properties:
preset:
type: string
enum:
- today
- yesterday
- lastDay
- lastWeek
- last2Weeks
- lastMonth
- last3Months
- last6Months
- last12Months
- last2Years
- last3Years
- specific
timeZone:
type: string
required:
- preset
additionalProperties: false
timeInterval:
type: string
enum:
- hour
- day
- isoWeek
- month
- quarter
query:
$ref: '#/components/schemas/def-1'
description: A [search query](https://docs.getport.io/search-and-query/overview) used to filter the entities before the aggregation is calculated.
measureTimeBy:
type: string
description: A property of type `datetime` by which the aggregation will be calculated.
specificTimeRange:
type: array
items:
type: number
minItems: 2
maxItems: 2
description: A specific time range [min,max] to aggregate over. If not provided, the time range will be used.
aggregationType:
enum:
- countEntities
func:
type: string
enum:
- count
- average
breakdownProperty:
type: string
description: A blueprint's property by which you want to break down the data.
required:
- func
additionalProperties: false
allOf:
- if:
type: object
properties:
timeRange:
type: object
properties:
preset:
enum:
- last2Years
- last3Years
then:
type: object
properties:
timeInterval:
enum:
- quarter
- if:
type: object
properties:
timeRange:
type: object
properties:
preset:
enum:
- specific
required:
- timeRange
then:
type: object
properties:
specificTimeRange:
type: array
items:
type: number
minItems: 2
maxItems: 2
description: A specific time range [min,max] to aggregate over. If not provided, the time range will be used.
required:
- specificTimeRange
required: true
security:
- bearer:
- read:entities
responses:
'200':
description: Retrieved successfully.
content:
application/json:
schema:
description: Retrieved successfully.
type: object
properties:
ok:
enum:
- true
result:
type: object
properties:
minDate:
type: number
maxDate:
type: number
data:
type: array
items:
object:
type: object
properties:
date:
type: number
additionalProperties:
type: number
required:
- 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/entities/properties-history:
post:
summary: Fetch the history of an entity's properties
tags:
- Entities
description: This route allows you to retrieve historical values for a selected list of an entity's properties over a given time range.
To learn more about entities, check out the [entity documentation](https://docs.port.io/build-your-software-catalog/sync-data-to-catalog/#entities).
requestBody:
content:
application/json:
schema:
type: object
properties:
entityIdentifier:
type: string
description: The identifier of the entity you want to operate on.
blueprintIdentifier:
type: string
description: The identifier of the blueprint you want to operate on.
propertyNames:
type: array
items:
type: string
description: An array of property names to fetch historical records for.
timeInterval:
type: string
enum:
- hour
- day
- isoWeek
- month
- quarter
timeRange:
type: object
properties:
preset:
type: string
enum:
- today
- yesterday
- lastDay
- lastWeek
- last2Weeks
- lastMonth
- last3Months
- last6Months
- last12Months
- last2Years
- last3Years
timeZone:
type: string
enum:
- Africa/Abidjan
- Africa/Accra
- Africa/Addis_Ababa
- Africa/Algiers
- Africa/Asmera
- Africa/Bamako
- Africa/Bangui
- Africa/Banjul
- Africa/Bissau
- Africa/Blantyre
- Africa/Brazzaville
- Africa/Bujumbura
- Africa/Cairo
- Africa/Casablanca
- Africa/Ceuta
- Africa/Conakry
- Africa/Dakar
- Africa/Dar_es_Salaam
- Africa/Djibouti
- Africa/Douala
- Africa/El_Aaiun
- Africa/Freetown
- Africa/Gaborone
- Africa/Harare
- Africa/Johannesburg
- Africa/Juba
- Africa/Kampala
- Africa/Khartoum
- Africa/Kigali
- Africa/Kinshasa
- Africa/Lagos
- Africa/Libreville
- Africa/Lome
- Africa/Luanda
- Africa/Lubumbashi
- Africa/Lusaka
- Africa/Malabo
- Africa/Maputo
- Africa/Maseru
- Africa/Mbabane
- Africa/Mogadishu
- Africa/Monrovia
- Africa/Nairobi
- Africa/Ndjamena
- Africa/Niamey
- Africa/Nouakchott
- Africa/Ouagadougou
- Africa/Porto-Novo
- Africa/Sao_Tome
- Africa/Tripoli
- Africa/Tunis
- Africa/Windhoek
- America/Adak
- America/Anchorage
- America/Anguilla
- America/Antigua
- America/Araguaina
- America/Argentina/La_Rioja
- America/Argentina/Rio_Gallegos
- America/Argentina/Salta
- America/Argentina/San_Juan
- America/Argentina/San_Luis
- America/Argentina/Tucuman
- America/Argentina/Ushuaia
- America/Aruba
- America/Asuncion
- America/Bahia
- America/Bahia_Banderas
- America/Barbados
- America/Belem
- America/Belize
- America/Blanc-Sablon
- America/Boa_Vista
- America/Bogota
- America/Boise
- America/Buenos_Aires
- America/Cambridge_Bay
- America/Campo_Grande
- America/Cancun
- America/Caracas
- America/Catamarca
- America/Cayenne
- America/Cayman
- America/Chicago
- America/Chihuahua
- America/Ciudad_Juarez
- America/Coral_Harbour
- America/Cordoba
- America/Costa_Rica
- America/Coyhaique
- America/Creston
- America/Cuiaba
- America/Curacao
- America/Danmarkshavn
- America/Dawson
- America/Dawson_Creek
- America/Denver
- America/Detroit
- America/Dominica
- America/Edmonton
- America/Eirunepe
- America/El_Salvador
- America/Fort_Nelson
- America/Fortaleza
- America/Glace_Bay
- America/Godthab
- America/Goose_Bay
- America/Grand_Turk
- America/Grenada
- America/Guadeloupe
- America/Guatemala
- America/Guayaquil
- America/Guyana
- America/Halifax
- America/Havana
- America/Hermosillo
- America/Indiana/Knox
- America/Indiana/Marengo
- America/Indiana/Petersburg
- America/Indiana/Tell_City
- America/Indiana/Vevay
- America/Indiana/Vincennes
- America/Indiana/Winamac
- America/Indianapolis
- America/Inuvik
- America/Iqaluit
- America/Jamaica
- America/Jujuy
- America/Juneau
- America/Kentucky/Monticello
- America/Kralendijk
- America/La_Paz
- America/Lima
- America/Los_Angeles
- America/Louisville
- America/Lower_Princes
- America/Maceio
- America/Managua
- America/Manaus
- America/Marigot
- America/Martinique
- America/Matamoros
- America/Mazatlan
- America/Mendoza
- America/Menominee
- America/Merida
- America/Metlakatla
- America/Mexico_City
- America/Miquelon
- America/Moncton
- America/Monterrey
- America/Montevideo
- America/Montserrat
- America/Nassau
- America/New_York
- America/Nome
- America/Noronha
- America/North_Dakota/Beulah
- America/North_Dakota/Center
- America/North_Dakota/New_Salem
- America/Ojinaga
- America/Panama
- America/Paramaribo
- America/Phoenix
- America/Port-au-Prince
- America/Port_of_Spain
- America/Porto_Velho
- America/Puerto_Rico
- America/Punta_Arenas
- America/Rankin_Inlet
- America/Recife
- America/Regina
- America/Resolute
- America/Rio_Branco
- America/Santarem
- America/Santiago
- America/Santo_Domingo
- America/Sao_Paulo
- America/Scoresbysund
- America/Sitka
- America/St_Barthelemy
- America/St_Johns
- America/St_Kitts
- America/St_Lucia
- America/St_Thomas
- America/St_Vincent
- America/Swift_Current
- America/Tegucigalpa
- America/Thule
- America/Tijuana
- America/Toronto
- America/Tortola
- America/Vancouver
- America/Whitehorse
- America/Winnipeg
- America/Yakutat
- Antarctica/Casey
- Antarctica/Davis
- Antarctica/DumontDUrville
- Antarctica/Macquarie
- Antarctica/Mawson
- Antarctica/McMurdo
- Antarctica/Palmer
- Antarctica/Rothera
- Antarctica/Syowa
- Antarctica/Troll
- Antarctica/Vostok
- Arctic/Longyearbyen
- Asia/Aden
- Asia/Almaty
- Asia/Amman
- Asia/Anadyr
- Asia/Aqtau
- Asia/Aqtobe
- Asia/Ashgabat
- Asia/Atyrau
- Asia/Baghdad
- Asia/Bahrain
- Asia/Baku
- Asia/Bangkok
- Asia/Barnaul
- Asia/Beirut
- Asia/Bishkek
- Asia/Brunei
- Asia/Calcutta
- Asia/Chita
- Asia/Colombo
- Asia/Damascus
- Asia/Dhaka
- Asia/Dili
- Asia/Dubai
- Asia/Dushanbe
- Asia/Famagusta
- Asia/Gaza
- Asia/Hebron
- Asia/Hong_Kong
- Asia/Hovd
- Asia/Irkutsk
- Asia/Jakarta
- Asia/Jayapura
- Asia/Jerusalem
- Asia/Kabul
- Asia/Kamchatka
- Asia/Karachi
- Asia/Katmandu
- Asia/Khandyga
- Asia/Krasnoyarsk
- Asia/Kuala_Lumpur
- Asia/Kuching
- Asia/Kuwait
- Asia/Macau
- Asia/Magadan
- Asia/Makassar
- Asia/Manila
- Asia/Muscat
- Asia/Nicosia
- Asia/Novokuznetsk
- Asia/Novosibirsk
- Asia/Omsk
- Asia/Oral
- Asia/Phnom_Penh
- Asia/Pontianak
- Asia/Pyongyang
- Asia/Qatar
- Asia/Qostanay
- Asia/Qyzylorda
- Asia/Rangoon
- Asia/Riyadh
- Asia/Saigon
- Asia/Sakhalin
- Asia/Samarkand
- Asia/Seoul
- Asia/Shanghai
- Asia/Singapore
- Asia/Srednekolymsk
- Asia/Taipei
- Asia/Tashkent
- Asia/Tbilisi
- Asia/Tehran
- Asia/Thimphu
- Asia/Tokyo
- Asia/Tomsk
- Asia/Ulaanbaatar
- Asia/Urumqi
- Asia/Ust-Nera
- Asia/Vientiane
- Asia/Vladivostok
- Asia/Yakutsk
- Asia/Yekaterinburg
- Asia/Yerevan
- Atlantic/Azores
- Atlantic/Bermuda
- Atlantic/Canary
- Atlantic/Cape_Verde
- Atlantic/Faeroe
- Atlantic/Madeira
- Atlantic/Reykjavik
- Atlantic/South_Georgia
- Atlantic/St_Helena
- Atlantic/Stanley
- Australia/Adelaide
- Australia/Brisbane
- Australia/Broken_Hill
- Australia/Darwin
- Australia/Eucla
- Australia/Hobart
- Australia/Lindeman
- Australia/Lord_Howe
- Australia/Melbourne
- Australia/Perth
- Australia/Sydney
- Europe/Amsterdam
- Europe/Andorra
- Europe/Astrakhan
- Europe/Athens
- Europe/Belgrade
- Europe/Berlin
- Europe/Bratislava
- Europe/Brussels
- Europe/Bucharest
- Europe/Budapest
- Europe/Busingen
- Europe/Chisinau
- Europe/Copenhagen
- Europe/Dublin
- Europe/Gibraltar
- Europe/Guernsey
- Europe/Helsinki
- Europe/Isle_of_Man
- Europe/Istanbul
- Europe/Jersey
- Europe/Kaliningrad
- Europe/Kiev
- Europe/Kirov
- Europe/Lisbon
- Europe/Ljubljana
- Europe/London
- Europe/Luxembourg
- Europe/Madrid
- Europe/Malta
- Europe/Mariehamn
- Europe/Minsk
- Europe/Monaco
- Europe/Moscow
- Europe/Oslo
- Europe/Paris
- Europe/Podgorica
- Europe/Prague
- Europe/Riga
- Europe/Rome
- Europe/Samara
- Europe/San_Marino
- Europe/Sarajevo
- Europe/Saratov
- Europe/Simferopol
- Europe/Skopje
- Europe/Sofia
- Europe/Stockholm
- Europe/Tallinn
- Europe/Tirane
- Europe/Ulyanovsk
- Europe/Vaduz
- Europe/Vatican
- Europe/Vienna
- Europe/Vilnius
- Europe/Volgograd
- Europe/Warsaw
- Europe/Zagreb
- Europe/Zurich
- Indian/Antananarivo
- Indian/Chagos
- Indian/Christmas
- Indian/Cocos
- Indian/Comoro
- Indian/Kerguelen
- Indian/Mahe
- Indian/Maldives
- Indian/Mauritius
- Indian/Mayotte
- Indian/Reunion
- Pacific/Apia
- Pacific/Auckland
- Pacific/Bougainville
- Pacific/Chatham
- Pacific/Easter
- Pacific/Efate
- Pacific/Enderbury
- Pacific/Fakaofo
- Pacific/Fiji
- Pacific/Funafuti
- Pacific/Galapagos
- Pacific/Gambier
- Pacific/Guadalcanal
- Pacific/Guam
- Pacific/Honolulu
- Pacific/Kiritimati
- Pacific/Kosrae
- Pacific/Kwajalein
- Pacific/Majuro
- Pacific/Marquesas
- Pacific/Midway
- Pacific/Nauru
- Pacific/Niue
- Pacific/Norfolk
- Pacific/Noumea
- Pacific/Pago_Pago
- Pacific/Palau
- Pacific/Pitcairn
- Pacific/Ponape
- Pacific/Port_Moresby
- Pacific/Rarotonga
- Pacific/Saipan
- Pacific/Tahiti
- Pacific/Tarawa
- Pacific/Tongatapu
- Pacific/Truk
- Pacific/Wake
- Pacific/Wallis
required:
- preset
- timeZone
additionalProperties: false
additionalProperties: false
required:
- entityIdentifier
- blueprintIdentifier
- propertyNames
if:
type: object
properties:
timeRange:
type: object
properties:
preset:
enum:
- last2Years
- last3Years
then:
type: object
properties:
timeInterval:
enum:
- quarter
required: true
security:
- bearer:
- read:entities
responses:
'200':
description: Retrieved successfully.
content:
application/json:
schema:
description: Retrieved successfully.
properties:
ok:
enum:
- true
result:
type: object
properties:
minDate:
type: number
maxDate:
type: number
data:
type: array
items:
type: number
required:
- 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
components:
schemas:
def-6:
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.
Read more [here](https://docs.port.io/build-your-software-catalog/customize-integrations/configure-mapping#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
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
- $ref: '#/components/schemas/def-6'
required:
- combinator
- rules
additionalProperties: false
title: /schemas/searchRelationsQuerySchema
def-5:
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.
Read more [here](https://docs.port.io/build-your-software-catalog/customize-integrations/configure-mapping#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
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
- $ref: '#/components/schemas/def-5'
required:
- combinator
- rules
additionalProperties: false
title: /schemas/searchIdentifierQuerySchema
def-1:
type: object
properties:
combinator:
enum:
- and
- or
description: The combinator to use for the rules.
rules:
type: array
items:
anyOf:
- type: object
title: Date Rule
properties:
property:
oneOf:
- type: string
- type: object
properties:
property:
type: string
context:
type: string
enum:
- user
- userTeams
required:
- property
- context
operator:
enum:
- between
- notBetween
- '='
value:
type: object
oneOf:
- type: object
title: Date Range
properties:
from:
type: string
format: date-time
to:
type: string
format: date-time
required:
- from
- to
- type: object
title: Date Preset
properties:
preset:
type: string
enum:
- today
- tomorrow
- yesterday
- lastDay
- lastWeek
- last2Weeks
- lastMonth
- last3Months
- last6Months
- last12Months
- last2Years
- last3Years
- nextDay
- nextWeek
- next2Weeks
- nextMonth
- next3Months
- next6Months
- next12Months
required:
- preset
- type: object
properties:
property:
type: string
context:
type: string
enum:
- user
- userTeams
required:
- property
- context
required:
- property
- operator
- value
additionalProperties: false
- type: object
title: Empty Rule
oneOf:
- type: object
title: Empty Rule
properties:
operator:
enum:
- isEmpty
- isNotEmpty
property:
type: string
required:
- operator
- property
additionalProperties: false
- type: object
title: Number Rule
properties:
property:
oneOf:
- type: string
- type: object
properties:
property:
type: string
context:
type: string
enum:
- user
- userTeams
required:
- property
- context
operator:
enum:
- '>'
- '>='
- <
- <=
value:
anyOf:
- type: number
title: number
- type: string
format: date-time
title: date-time
- type: object
properties:
property:
type: string
context:
type: string
enum:
- user
- userTeams
required:
- property
- context
required:
- property
- operator
- value
additionalProperties: false
- type: object
title: Expired Rule
oneOf:
- type: object
title: Expired Rule
properties:
operator:
enum:
- isExpired
- isNotExpired
property:
type: string
required:
- operator
- property
additionalProperties: false
- type: object
title: String Rule
oneOf:
- type: object
title: String Rule
properties:
property:
oneOf:
- type: string
- type: object
properties:
property:
type: string
context:
type: string
enum:
- user
- userTeams
required:
- property
- context
operator:
enum:
- '='
- '!='
- containsAny
- contains
- doesNotContains
- beginsWith
- doesNotBeginsWith
- endsWith
- doesNotEndsWith
- in
- notIn
value:
anyOf:
- type: 'null'
title: 'null'
- type: string
title: string
- type: number
title: number
- type: boolean
title: boolean
- type: string
format: date-time
title: date-time
- type: array
items:
type: string
title: array
- type: array
items:
type: number
title: array
- type: array
items:
type: boolean
title: array
- type: array
items:
type: string
format: date-time
title: array
- type: object
properties:
property:
type: string
context:
type: string
enum:
- user
- userTeams
required:
- property
- context
additionalProperties: false
required:
- property
- operator
- value
- type: object
title: Relation Rule
properties:
operator:
enum:
- relatedTo
blueprint:
type: string
value:
anyOf:
- type: string
title: string
- type: array
items:
type: string
title: array
direction:
enum:
- upstream
- downstream
required:
type: boolean
additionalProperties: false
required:
- operator
- value
- blueprint
- type: object
title: Property schema rule
properties:
propertySchema:
type: object
properties:
type:
type: string
format:
type: string
items:
type: object
properties:
type:
type: string
format:
type: string
required:
- type
required:
- type
additionalProperties: false
operator:
enum:
- '='
- '!='
- contains
value:
anyOf:
- type: 'null'
title: 'null'
- type: string
title: string
- type: number
title: number
- type: boolean
title: boolean
required:
- operator
- propertySchema
additionalProperties: false
- type: object
title: matchAny Rule
anyOf:
- type: object
properties:
property:
oneOf:
- type: object
properties:
path:
type: array
items:
anyOf:
- type: string
- type: object
properties:
relation:
type: string
maxHops:
type: number
minimum: 1
maximum: 15
fromBlueprint:
type: string
required:
- path
additionalProperties: false
- oneOf:
- type: string
- type: object
properties:
property:
type: string
context:
type: string
enum:
- user
- userTeams
required:
- property
- context
operator:
type: string
enum:
- matchAny
value:
anyOf:
- type: array
items:
type: string
- oneOf:
- type: string
- type: object
properties:
property:
type: string
context:
type: string
enum:
- user
- userTeams
required:
- property
- context
required:
- property
- operator
- value
additionalProperties: false
- $ref: '#/components/schemas/def-1'
required:
- combinator
- rules
additionalProperties: false
example:
combinator: and
rules:
- property: $blueprint
operator: '='
value: service
- combinator: or
rules:
- property: environment
operator: '='
value: production
- property: environment
operator: '='
value: staging
title: /schemas/entitiesQuery
def-7:
type: object
properties:
combinator:
enum:
- and
- or
rules:
type: array
items:
anyOf:
- type: object
title: Date Rule
properties:
property:
oneOf:
- type: string
- type: object
properties:
property:
type: string
context:
type: string
enum:
- user
- userTeams
required:
- property
- context
operator:
enum:
- between
- notBetween
- '='
value:
type: object
oneOf:
- type: object
title: Date Range
properties:
from:
type: string
format: date-time
to:
type: string
format: date-time
required:
- from
- to
- type: object
title: Date Preset
properties:
preset:
type: string
enum:
- today
- tomorrow
- yesterday
- lastDay
- lastWeek
- last2Weeks
- lastMonth
- last3Months
- last6Months
- last12Months
- last2Years
- last3Years
- nextDay
- nextWeek
- next2Weeks
- nextMonth
- next3Months
- next6Months
- next12Months
required:
- preset
- type: object
properties:
property:
type: string
context:
type: string
enum:
- user
- userTeams
required:
- property
- context
required:
- property
- operator
- value
additionalProperties: false
- type: object
title: Empty Rule
oneOf:
- properties:
operator:
enum:
- isEmpty
- isNotEmpty
property:
type: string
required:
- operator
- property
additionalProperties: false
- properties:
operator:
enum:
- isEmpty
- isNotEmpty
targetProperty:
type: string
enum:
- $title
- $identifier
relation:
type: string
required:
- operator
- relation
additionalProperties: false
- properties:
operator:
enum:
- isEmpty
- isNotEmpty
scorecardRule:
type: string
scorecard:
type: string
required:
- operator
- scorecard
additionalProperties: false
- type: object
title: Expired Rule
oneOf:
- type: object
title: Expired Rule
properties:
operator:
enum:
- isExpired
- isNotExpired
property:
type: string
required:
- operator
- property
additionalProperties: false
- type: object
title: Number Rule
properties:
property:
oneOf:
- type: string
- type: object
properties:
property:
type: string
context:
type: string
enum:
- user
- userTeams
required:
- property
- context
operator:
enum:
- '>'
- '>='
- <
- <=
value:
anyOf:
- type: number
title: number
- type: string
format: date-time
title: date-time
- type: object
properties:
property:
type: string
context:
type: string
enum:
- user
- userTeams
required:
- property
- context
required:
- property
- operator
- value
additionalProperties: false
- type: object
title: String Rule
oneOf:
- type: object
properties:
property:
oneOf:
- type: string
- type: object
properties:
property:
type: string
context:
type: string
enum:
- user
- userTeams
required:
- property
- context
operator:
enum:
- '='
- '!='
- containsAny
- contains
- doesNotContains
- beginsWith
- doesNotBeginsWith
- endsWith
- doesNotEndsWith
- in
- notIn
value:
anyOf:
- type: 'null'
- type: string
title: string
- type: number
title: number
- type: boolean
title: boolean
- type: array
items:
type: string
title: array
- type: array
items:
type: number
title: array
- type: array
items:
type: boolean
title: array
- type: array
items:
type: string
format: date-time
title: array
- type: string
format: date-time
title: date-time
- type: object
properties:
property:
type: string
context:
type: string
enum:
- user
- userTeams
required:
- property
- context
additionalProperties: false
required:
- property
- operator
- value
- type: object
properties:
relation:
type: string
targetProperty:
type: string
enum:
- $title
- $identifier
operator:
enum:
- '='
- '!='
- containsAny
- contains
- doesNotContains
- beginsWith
- doesNotBeginsWith
- endsWith
- doesNotEndsWith
- in
- notIn
value:
anyOf:
- type: 'null'
- type: string
title: string
- type: number
title: number
- type: boolean
title: boolean
- type: array
items:
type: string
title: array
- type: array
items:
type: number
title: array
- type: array
items:
type: boolean
title: array
- type: array
items:
type: string
format: date-time
title: array
- type: string
format: date-time
title: date-time
additionalProperties: false
required:
- relation
- operator
- value
- type: object
properties:
scorecard:
type: string
scorecardRule:
type: string
operator:
enum:
- '='
- '!='
- containsAny
- contains
- doesNotContains
- beginsWith
- doesNotBeginsWith
- endsWith
- doesNotEndsWith
- in
- notIn
value:
anyOf:
- type: 'null'
- type: string
title: string
- type: number
title: number
- type: boolean
title: boolean
- type: array
items:
type: string
title: array
- type: array
items:
type: number
title: array
- type: array
items:
type: boolean
title: array
- type: array
items:
type: string
format: date-time
title: array
- type: string
format: date-time
title: date-time
additionalProperties: false
required:
- scorecard
- operator
- value
- type: object
title: Relation Rule
properties:
operator:
enum:
- relatedTo
blueprint:
type: string
value:
anyOf:
- type: string
title: string
- type: array
items:
type: string
title: array
direction:
enum:
- upstream
- downstream
required:
type: boolean
additionalProperties: false
required:
- operator
- value
- blueprint
- type: object
title: Property schema rule
properties:
propertySchema:
type: object
properties:
type:
type: string
format:
type: string
items:
type: object
properties:
type:
type: string
format:
type: string
required:
- type
required:
- type
additionalProperties: false
operator:
enum:
- '='
- '!='
- contains
value:
anyOf:
- type: 'null'
title: 'null'
- type: string
title: string
- type: number
title: number
- type: boolean
title: boolean
required:
- operator
- propertySchema
additionalProperties: false
- type: object
title: matchAny Rule
anyOf:
- type: object
properties:
property:
oneOf:
- type: object
properties:
path:
type: array
items:
anyOf:
- type: string
- type: object
properties:
relation:
type: string
maxHops:
type: number
minimum: 1
maximum: 15
fromBlueprint:
type: string
required:
- path
additionalProperties: false
- oneOf:
- type: string
- type: object
properties:
property:
type: string
context:
type: string
enum:
- user
- userTeams
required:
- property
- context
operator:
type: string
enum:
- matchAny
value:
anyOf:
- type: array
items:
type: string
- oneOf:
- type: string
- type: object
properties:
property:
type: string
context:
type: string
enum:
- user
- userTeams
required:
- property
- context
required:
- property
- operator
- value
additionalProperties: false
- $ref: '#/components/schemas/def-7'
required:
- combinator
- rules
additionalProperties: false
title: /schemas/entitiesQueryV2
securitySchemes:
bearer:
type: apiKey
name: Authorization
in: header