Create an integration
POST/v1/integration
This route allows you to create an integration in your Port organization.
To learn more about integrations, check out the documentation.
Port-hosted integrations return 202 Accepted because the integration is not fully up until it is applied.
For self-hosted integrations, this endpoint only registers the integration resource in Port and returns 201 Created. It does not deploy or run the integration application; you must deploy it separately for the integration to ingest data.
Request
Parameters (JSON)
{
"parameters": [
{
"schema": {
"type": "boolean",
"default": false
},
"in": "query",
"name": "upsert",
"required": false,
"description": "If `true`, the integration will be updated if it already exists."
},
{
"schema": {
"type": "array",
"items": {
"type": "string",
"enum": [
"create_resources"
]
},
"default": []
},
"in": "query",
"name": "integration_modes",
"required": false,
"style": "form",
"explode": true
}
]
}Request body schema (JSON)
{
"title": "Body",
"body": {
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"installationId": {
"type": "string",
"minLength": 1,
"maxLength": 53,
"description": "A unique identifier which will be used to identify the integration when using the Port API. Must match the pattern ^[a-z0-9-_]+$.",
"pattern": "^[a-z0-9-_]+$"
},
"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."
},
"installationType": {
"type": "string",
"enum": [
"OnPrem",
"Saas",
"SaasOAuth2",
"CustomGithubApp",
"EnterpriseGithubApp"
],
"default": "OnPrem"
},
"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",
"description": "The pinned version of the integration. If provided, the integration will be pinned to this specific version in the Kubernetes manifest."
},
"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."
},
"createPortResourcesOrigin": {
"type": "string",
"enum": [
"Empty",
"Port",
"Ocean",
"Default"
],
"description": "Specifies where the Port's resources creation originates from"
},
"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
}
]
}
},
"additionalProperties": false,
"required": [
"installationId"
],
"if": {
"properties": {
"installationType": {
"enum": [
"Saas",
"SaasOAuth2"
]
}
},
"required": [
"installationType"
]
},
"then": {
"properties": {
"installationId": {
"type": "string",
"minLength": 1,
"maxLength": 20,
"pattern": "^[a-z][a-z0-9-]*[a-z0-9]$"
}
}
}
}
}
},
"required": 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"
}
}
}
}
}
}