Update an integration
PATCH/v1/integration/:identifier
This route allows you to modify an integration in your Port organization.
To learn more about integrations, check out the documentation.
Permission requirements
To use this endpoint, you must have an admin role in your Port organization.
Note: The moderator role does not include the required update:integrations scope. Requests without this scope return 403 Forbidden.
To learn more about the different roles and permissions, please refer to the documentation.
Note: To trigger a resync of an integration without changing its mapping, simply provide its identifier and leave the body empty.
Port-hosted spec updates return 202 Accepted while the change is applied. Other updates return 200.
Request
Parameters (JSON)
{
"parameters": [
{
"schema": {
"type": "string"
},
"in": "path",
"name": "identifier",
"required": true,
"description": "The unique identifier of the resource you want to operate on."
}
]
}Request body schema (JSON)
{
"title": "Body",
"body": {
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"nullable": true,
"description": "The title of the integration. This will be displayed in the [connectors page](https://app.port.io/settings/data-sources) of your Port account."
},
"installationAppType": {
"type": "string",
"description": "The name of the integrated tool/platform (e.g. `kubernetes`,`pagerduty`)."
},
"version": {
"type": "string",
"description": "The version of the integration."
},
"pinnedVersion": {
"type": [
"string",
"null"
],
"description": "The pinned version of the integration. Set to `null` to remove the pin and run the latest version."
},
"spec": {
"type": "object",
"properties": {
"appSpec": {
"type": "object",
"additionalProperties": true
},
"integrationSpec": {
"type": "object",
"additionalProperties": true
}
},
"additionalProperties": false
},
"actionsProcessingEnabled": {
"type": "boolean",
"description": "If `true`, This integration will be able to process actions runs"
},
"incrementalSyncEnabled": {
"type": "boolean",
"description": "If `true`, This integration will run incremental syncs on a schedule"
},
"processingMode": {
"type": "string",
"enum": [
"ocean-core",
"dsp"
],
"description": "The processing mode for the integration. `ocean_core` uses Ocean core processing, `dsp` uses the data source processor."
},
"config": {
"type": [
"object",
"null"
],
"additionalProperties": true,
"description": "Various configuration options for the integration.",
"properties": {
"deleteDependentEntities": {
"type": "boolean",
"description": "If `true`, deleting an entity will also delete its dependent entities."
},
"createMissingRelatedEntities": {
"type": "boolean",
"description": "If `true`, creating an entity with a relation to a non-existing entity will also create the related entity."
},
"resources": {
"type": "array",
"description": "The mapping definition of resources from the integrated tool/platform into Port. For more information and examples, check out the [documentation](https://docs.port.io/context-lake/ingestion/configure-mapping/overview).",
"items": {
"type": "object",
"required": [
"kind",
"selector",
"port"
],
"properties": {
"kind": {
"type": "string",
"description": "The kind of resource to map, as defined in API of the integrated tool/platorm."
},
"selector": {
"type": "object",
"properties": {
"query": {
"type": "string",
"description": "A `jq` query used to specify which resources to fetch from the integrated tool/platform. If set to `\"true\"`, all resources of the specified `kind` will be ingested. For more information and examples, check out the [documentation](https://docs.port.io/context-lake/ingestion/configure-mapping/overview#how-does-mapping-work)."
}
}
},
"port": {
"type": "object",
"required": [
"entity"
],
"description": "An object containing the mapping definitions of the `kind` resource into Port.",
"properties": {
"entity": {
"type": "object",
"required": [
"mappings"
],
"properties": {
"mappings": {
"description": "The mapping definitions used to map the resource fields into Port entities. For more information and examples, check out the [documentation](https://docs.port.io/context-lake/ingestion/configure-mapping/overview#mapping-concepts).",
"oneOf": [
{
"type": "array",
"title": "array",
"items": {
"type": "object",
"required": [
"identifier",
"blueprint"
],
"properties": {
"identifier": {
"oneOf": [
{
"type": "string",
"title": "String identifier",
"description": "A `jq` expression used to get data from the integrated tool's API, to be used as an identifier for the entity."
},
{
"type": "object",
"properties": {
"combinator": {
"type": "string"
},
"rules": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": true
}
}
},
"additionalProperties": false,
"required": [
"combinator",
"rules"
],
"title": "Search query identifier",
"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)."
}
]
},
"title": {
"type": "string",
"description": "A `jq` expression used to get data from the integrated tool's API, to be used as the title of the entity."
},
"icon": {
"type": "string",
"description": "A `jq` expression used to get data from the integrated tool's API, to be used as the icon of the entity."
},
"team": {
"oneOf": [
{
"type": "string",
"description": "A `jq` expression used to get data from the integrated tool's API, to be used as the team of the entity."
},
{
"type": "object",
"properties": {
"combinator": {
"type": "string"
},
"rules": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": true
}
}
},
"additionalProperties": false,
"required": [
"combinator",
"rules"
],
"title": "Search query team"
}
]
},
"blueprint": {
"type": "string",
"description": "The identifier of the blueprint to map the data into."
},
"properties": {
"type": "object",
"additionalProperties": true,
"description": "An object containing the properties of the entity and their values. For more information and examples, check out the [documentation](https://docs.port.io/context-lake/ingestion/configure-mapping/overview#mapping-concepts)."
},
"relations": {
"type": "object",
"additionalProperties": true,
"description": "An object containing the relations of the entity and their values. For more information and examples, check out the [documentation](https://docs.port.io/context-lake/ingestion/configure-mapping/overview#mapping-concepts)."
}
}
}
},
{
"type": "object",
"required": [
"identifier",
"blueprint"
],
"properties": {
"identifier": {
"oneOf": [
{
"type": "string",
"title": "String identifier",
"description": "A `jq` expression used to get data from the integrated tool's API, to be used as an identifier for the entity."
},
{
"type": "object",
"properties": {
"combinator": {
"type": "string"
},
"rules": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": true
}
}
},
"additionalProperties": false,
"required": [
"combinator",
"rules"
],
"title": "Search query identifier",
"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)."
}
]
},
"title": {
"type": "string",
"description": "A `jq` expression used to get data from the integrated tool's API, to be used as the title of the entity."
},
"icon": {
"type": "string",
"description": "A `jq` expression used to get data from the integrated tool's API, to be used as the icon of the entity."
},
"team": {
"oneOf": [
{
"type": "string",
"description": "A `jq` expression used to get data from the integrated tool's API, to be used as the team of the entity."
},
{
"type": "object",
"properties": {
"combinator": {
"type": "string"
},
"rules": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": true
}
}
},
"additionalProperties": false,
"required": [
"combinator",
"rules"
],
"title": "Search query team"
}
]
},
"blueprint": {
"type": "string",
"description": "The identifier of the blueprint to map the data into."
},
"properties": {
"type": "object",
"additionalProperties": true,
"description": "An object containing the properties of the entity and their values. For more information and examples, check out the [documentation](https://docs.port.io/context-lake/ingestion/configure-mapping/overview#mapping-concepts)."
},
"relations": {
"type": "object",
"additionalProperties": true,
"description": "An object containing the relations of the entity and their values. For more information and examples, check out the [documentation](https://docs.port.io/context-lake/ingestion/configure-mapping/overview#mapping-concepts)."
}
},
"title": "object"
}
]
}
}
}
}
}
}
}
}
}
},
"oauthBrokerUrl": {
"type": "string",
"format": "uri",
"description": "The base URL of the OAuth broker hosted by this integration. Port uses this URL to build the re-authentication link sent to users when the integration requires a new token."
},
"changelogDestination": {
"type": "object",
"description": "The destination of the integration's changelog.",
"properties": {
"type": {
"type": "string",
"enum": [
"WEBHOOK",
"KAFKA"
]
}
},
"oneOf": [
{
"type": "object",
"properties": {},
"additionalProperties": false
},
{
"type": "object",
"title": "Kafka",
"description": "The changelog will be sent to the Kafka topic connected to your Port account.",
"properties": {
"type": {
"type": "string",
"enum": [
"KAFKA"
]
}
},
"required": [
"type"
],
"additionalProperties": false
},
{
"type": "object",
"title": "Webhook",
"description": "The changelog will be sent to the specified webhook.",
"properties": {
"type": {
"type": "string",
"enum": [
"WEBHOOK"
]
},
"agent": {
"type": "boolean",
"description": "If `true`, Port's execution agent will be used to send the changelog."
},
"url": {
"type": "string",
"format": "uri",
"description": "The URL of the webhook."
}
},
"required": [
"url",
"type"
],
"additionalProperties": false
}
]
},
"arePortResourcesInitialized": {
"type": "boolean",
"description": "Whether the Port resources are initialized for the integration."
}
},
"additionalProperties": true
}
}
}
}
}Responses
- 401
- 404
- 413
- 422
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": {
"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"
}
}
}
}
}
}