Create multiple entities
POST/v1/blueprints/:blueprint_identifier/entities/bulk
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.
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.
Request
Parameters (JSON)
{
"parameters": [
{
"schema": {
"type": "boolean",
"default": false
},
"in": "query",
"name": "upsert",
"required": true,
"description": "If `true`, this call will override the entire entity/ies, if it/they already exist/s."
},
{
"schema": {
"type": "boolean",
"default": false
},
"in": "query",
"name": "validation_only",
"required": false,
"description": "If `true`, this call will only validate the entity/ies and return the validation errors."
},
{
"schema": {
"type": "boolean",
"default": false
},
"in": "query",
"name": "create_missing_related_entities",
"required": false,
"description": "If `true`, this call will also create missing related entities.<br/>This is useful when you want to create an entity and its related entities in one call, or if you want to create an entity whose related entity does not exist yet."
},
{
"schema": {
"type": "boolean",
"default": false
},
"in": "query",
"name": "merge",
"required": false,
"description": "If `true` and `upsert` is also `true`, this call will update the entity/ies, if it/they already exist/s."
},
{
"schema": {
"type": "string"
},
"in": "query",
"name": "run_id",
"required": false,
"description": "You can provide a `run_id` to associate the created entities with a specific [action run](https://docs.port.io/workflows/actions-and-automations/reflect-action-progress/#tie-entities-to-action-run) or with a workflow run (`wfr_...`)."
},
{
"schema": {
"type": "string",
"pattern": "^wfnr_"
},
"in": "query",
"name": "node_run_identifier",
"required": false,
"description": "The identifier of the workflow node run (`wfnr_...`) that is changing the entities. Only used together with a workflow run `run_id`."
},
{
"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"
},
"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."
}
]
}Request body schema (JSON)
{
"title": "Body",
"body": {
"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."
},
{
"title": "Search identifier query",
"type": "object",
"properties": {
"combinator": {
"enum": [
"and",
"or"
]
},
"rules": {
"type": "array",
"description": "A search query to define the entity's identifier based on a property of the entity.<br/>Read more [here](https://docs.port.io/context-lake/ingestion/configure-mapping/overview#map-by-property).",
"items": {
"anyOf": [
{
"type": "object",
"title": "`=` rule",
"properties": {
"property": {
"type": "string"
},
"operator": {
"enum": [
"="
]
},
"value": {
"anyOf": [
{
"type": "string",
"title": "String"
},
{
"type": "number",
"title": "Number"
},
{
"type": "null"
}
]
}
},
"additionalProperties": false,
"required": [
"property",
"operator",
"value"
]
},
{
"type": "object",
"title": "`in` rule",
"properties": {
"property": {
"type": "string"
},
"operator": {
"enum": [
"in",
"containsAny"
]
},
"value": {
"type": "array",
"items": {
"type": "string"
},
"errorMessage": "must be an array of strings when the operator is 'in' or 'containsAny'"
}
},
"additionalProperties": false,
"required": [
"property",
"operator",
"value"
]
},
{
"type": "object",
"title": "`contains` rule",
"properties": {
"property": {
"type": "string"
},
"operator": {
"enum": [
"contains"
]
},
"value": {
"anyOf": [
{
"type": "string"
},
{
"type": "array",
"items": {
"type": "string"
}
},
{
"type": "null"
}
]
}
},
"additionalProperties": false,
"required": [
"property",
"operator",
"value"
]
},
{
"allOf": [
"circular(Search identifier query)",
{
"title": "Nested query"
}
]
}
]
}
}
},
"required": [
"combinator",
"rules"
],
"additionalProperties": false
}
]
},
"title": {
"type": "string",
"description": "The title of the entity."
},
"icon": {
"type": "string",
"description": "The icon of the entity."
},
"team": {
"oneOf": [
{
"title": "Team (Single)",
"type": "string",
"description": "The Port team/s to which the entity will belong."
},
{
"title": "Teams (Multiple)",
"type": "array",
"items": {
"type": "string"
},
"description": "The Port team/s to which the entity will belong."
},
{
"title": "Search relations query",
"type": "object",
"properties": {
"combinator": {
"enum": [
"and",
"or"
]
},
"rules": {
"type": "array",
"description": "A search query to define the entity's identifier based on a property of the entity.<br/>Read more [here](https://docs.port.io/context-lake/ingestion/configure-mapping/overview#map-by-property).",
"items": {
"anyOf": [
{
"type": "object",
"title": "`=` rule",
"properties": {
"property": {
"type": "string"
},
"operator": {
"enum": [
"="
]
},
"value": {
"anyOf": [
{
"type": "string",
"title": "String"
},
{
"type": "number",
"title": "Number"
},
{
"type": "null"
}
]
}
},
"additionalProperties": false,
"required": [
"property",
"operator",
"value"
]
},
{
"type": "object",
"title": "`in` rule",
"properties": {
"property": {
"type": "string"
},
"operator": {
"enum": [
"in",
"containsAny"
]
},
"value": {
"type": "array",
"items": {
"type": "string"
},
"errorMessage": "must be an array of strings when the operator is 'in' or 'containsAny'"
}
},
"additionalProperties": false,
"required": [
"property",
"operator",
"value"
]
},
{
"type": "object",
"title": "`contains` rule",
"properties": {
"property": {
"type": "string"
},
"operator": {
"enum": [
"contains"
]
},
"value": {
"anyOf": [
{
"type": "string"
},
{
"type": "array",
"items": {
"type": "string"
}
},
{
"type": "null"
}
]
}
},
"additionalProperties": false,
"required": [
"property",
"operator",
"value"
]
},
{
"allOf": [
"circular(Search relations query)",
{
"title": "Nested query"
}
]
}
]
}
}
},
"required": [
"combinator",
"rules"
],
"additionalProperties": false
},
{
"title": "Union source slice",
"description": "Only valid when the blueprint's \"ownership.union\" is enabled: a single source key mapped to that source's slice of owning teams, as in `{ \"<sourceKey>\": [\"team-a\"] }`. The slice may also be a search query.",
"type": "object",
"minProperties": 1,
"maxProperties": 1,
"additionalProperties": {
"anyOf": [
{
"type": [
"array",
"null"
],
"items": {
"type": "string"
}
},
{
"title": "Search relations query",
"type": "object",
"properties": {
"combinator": {
"enum": [
"and",
"or"
]
},
"rules": {
"type": "array",
"description": "A search query to define the entity's identifier based on a property of the entity.<br/>Read more [here](https://docs.port.io/context-lake/ingestion/configure-mapping/overview#map-by-property).",
"items": {
"anyOf": [
{
"type": "object",
"title": "`=` rule",
"properties": {
"property": {
"type": "string"
},
"operator": {
"enum": [
"="
]
},
"value": {
"anyOf": [
{
"type": "string",
"title": "String"
},
{
"type": "number",
"title": "Number"
},
{
"type": "null"
}
]
}
},
"additionalProperties": false,
"required": [
"property",
"operator",
"value"
]
},
{
"type": "object",
"title": "`in` rule",
"properties": {
"property": {
"type": "string"
},
"operator": {
"enum": [
"in",
"containsAny"
]
},
"value": {
"type": "array",
"items": {
"type": "string"
},
"errorMessage": "must be an array of strings when the operator is 'in' or 'containsAny'"
}
},
"additionalProperties": false,
"required": [
"property",
"operator",
"value"
]
},
{
"type": "object",
"title": "`contains` rule",
"properties": {
"property": {
"type": "string"
},
"operator": {
"enum": [
"contains"
]
},
"value": {
"anyOf": [
{
"type": "string"
},
{
"type": "array",
"items": {
"type": "string"
}
},
{
"type": "null"
}
]
}
},
"additionalProperties": false,
"required": [
"property",
"operator",
"value"
]
},
{
"allOf": [
"circular(Search relations query)",
{
"title": "Nested query"
}
]
}
]
}
}
},
"required": [
"combinator",
"rules"
],
"additionalProperties": false
}
]
}
}
]
},
"properties": {
"type": "object",
"default": {},
"description": "An object containing the properties of the entity, in `\"key\":\"value\"` pairs where the `key` is the property's identifier, and the `value` is its value."
},
"relations": {
"type": "object",
"description": "An object containing the relations of the entity, in `\"key\":\"value\"` pairs where the `key` is the relation's identifier, and the `value` is the related entity's identifier for single-relations, or an array of identifiers for many-relations.<br/>You can also use a [search query](https://docs.port.io/context-lake/ingestion/configure-mapping/configuration-methods/) to define relations based on a property of the related entity.",
"additionalProperties": {
"anyOf": [
{
"type": "string",
"pattern": "^(?!\\.{1,2}$)[\\p{L}0-9@_.+:\\\\/='-]+$",
"maxLength": 1000,
"title": "string"
},
{
"type": "array",
"items": {
"type": "string",
"pattern": "^(?!\\.{1,2}$)[\\p{L}0-9@_.+:\\\\/='-]+$"
},
"title": "array"
},
{
"type": "null",
"title": "null"
},
{
"title": "Search relations query",
"type": "object",
"properties": {
"combinator": {
"enum": [
"and",
"or"
]
},
"rules": {
"type": "array",
"description": "A search query to define the entity's identifier based on a property of the entity.<br/>Read more [here](https://docs.port.io/context-lake/ingestion/configure-mapping/overview#map-by-property).",
"items": {
"anyOf": [
{
"type": "object",
"title": "`=` rule",
"properties": {
"property": {
"type": "string"
},
"operator": {
"enum": [
"="
]
},
"value": {
"anyOf": [
{
"type": "string",
"title": "String"
},
{
"type": "number",
"title": "Number"
},
{
"type": "null"
}
]
}
},
"additionalProperties": false,
"required": [
"property",
"operator",
"value"
]
},
{
"type": "object",
"title": "`in` rule",
"properties": {
"property": {
"type": "string"
},
"operator": {
"enum": [
"in",
"containsAny"
]
},
"value": {
"type": "array",
"items": {
"type": "string"
},
"errorMessage": "must be an array of strings when the operator is 'in' or 'containsAny'"
}
},
"additionalProperties": false,
"required": [
"property",
"operator",
"value"
]
},
{
"type": "object",
"title": "`contains` rule",
"properties": {
"property": {
"type": "string"
},
"operator": {
"enum": [
"contains"
]
},
"value": {
"anyOf": [
{
"type": "string"
},
{
"type": "array",
"items": {
"type": "string"
}
},
{
"type": "null"
}
]
}
},
"additionalProperties": false,
"required": [
"property",
"operator",
"value"
]
},
{
"allOf": [
"circular(Search relations query)",
{
"title": "Nested query"
}
]
}
]
}
}
},
"required": [
"combinator",
"rules"
],
"additionalProperties": false
},
{
"title": "Union source slice",
"description": "Only valid for relations with \"union\" enabled: a single source key mapped to that source's slice of targets, as in `{ \"<sourceKey>\": [\"target-id\"] }`. The slice may also be a search query.",
"type": "object",
"minProperties": 1,
"maxProperties": 1,
"additionalProperties": {
"anyOf": [
{
"type": [
"array",
"null"
],
"items": {
"type": "string",
"pattern": "^(?!\\.{1,2}$)[\\p{L}0-9@_.+:\\\\/='-]+$"
}
},
{
"title": "Search relations query",
"type": "object",
"properties": {
"combinator": {
"enum": [
"and",
"or"
]
},
"rules": {
"type": "array",
"description": "A search query to define the entity's identifier based on a property of the entity.<br/>Read more [here](https://docs.port.io/context-lake/ingestion/configure-mapping/overview#map-by-property).",
"items": {
"anyOf": [
{
"type": "object",
"title": "`=` rule",
"properties": {
"property": {
"type": "string"
},
"operator": {
"enum": [
"="
]
},
"value": {
"anyOf": [
{
"type": "string",
"title": "String"
},
{
"type": "number",
"title": "Number"
},
{
"type": "null"
}
]
}
},
"additionalProperties": false,
"required": [
"property",
"operator",
"value"
]
},
{
"type": "object",
"title": "`in` rule",
"properties": {
"property": {
"type": "string"
},
"operator": {
"enum": [
"in",
"containsAny"
]
},
"value": {
"type": "array",
"items": {
"type": "string"
},
"errorMessage": "must be an array of strings when the operator is 'in' or 'containsAny'"
}
},
"additionalProperties": false,
"required": [
"property",
"operator",
"value"
]
},
{
"type": "object",
"title": "`contains` rule",
"properties": {
"property": {
"type": "string"
},
"operator": {
"enum": [
"contains"
]
},
"value": {
"anyOf": [
{
"type": "string"
},
{
"type": "array",
"items": {
"type": "string"
}
},
{
"type": "null"
}
]
}
},
"additionalProperties": false,
"required": [
"property",
"operator",
"value"
]
},
{
"allOf": [
"circular(Search relations query)",
{
"title": "Nested query"
}
]
}
]
}
}
},
"required": [
"combinator",
"rules"
],
"additionalProperties": false
}
]
}
}
]
}
}
},
"additionalProperties": true
},
"description": "Array of entities to create",
"minItems": 1,
"maxItems": 50
}
},
"required": [
"entities"
],
"additionalProperties": false
}
}
},
"required": true
}
}Responses
- 200
- 207
- 401
- 404
- 413
- 422
Created successfully.
Partially created successfully. Some entities were created while others failed.
Default Response
A resource with the provided identifier was not found
Request body is too large (limit is 1MiB)
The json provided does not match the route's schema
Responses (JSON)
{
"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"
},
"updated": {
"type": "boolean"
},
"identifier": {
"type": "string"
},
"index": {
"type": "number"
},
"additionalData": {
"type": "object",
"additionalProperties": true
}
},
"required": [
"created",
"updated",
"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"
},
"updated": {
"type": "boolean"
},
"identifier": {
"type": "string"
},
"index": {
"type": "number"
},
"additionalData": {
"type": "object",
"additionalProperties": true
}
},
"required": [
"created",
"updated",
"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"
}
}
}
}
}
}