Skip to main content

API


Port's API is a generic interface to model your software catalog, ingest data, invoke actions, query scorecards and more.

💡 Common Port API usage

Since Port API is a generic interface, anything that can be done with Port is possible through the API, for example:

  • Update the software catalog using a script.
  • Import your existing asset inventory from a CSV file.
  • Integrate Port with your custom CI/CD.
  • Report the status of a running CI job.
  • Update the software catalog about a new build version for a microservice.
  • Get existing data from your software catalog.

Get API Token

In order to interact with the API you will need an API token.

Getting an API token involves 2 steps:

  1. Finding your Port API credentials.
  2. Making an API request to generate a valid token.

Find your Port credentials

To get your Port API credentials go to your Port application, click on the ... button in the top right corner, and select Credentials. Here you can view and copy your CLIENT_ID and CLIENT_SECRET:

Generate an API token

Here are some code examples showing how to generate an API token in various programming languages:

# Dependencies to install:
# $ python -m pip install requests

import requests

CLIENT_ID = 'YOUR_CLIENT_ID'
CLIENT_SECRET = 'YOUR_CLIENT_SECRET'

API_URL = 'https://api.getport.io/v1'

credentials = {'clientId': CLIENT_ID, 'clientSecret': CLIENT_SECRET}

token_response = requests.post(f'{API_URL}/auth/access_token', json=credentials)

access_token = token_response.json()['accessToken']

# You can now use the value in access_token when making further requests

Ingest data via API

Since Port is API-first it is possible to create and update entities using simple REST calls from any platform you use.

Setup

To use Port's REST API you need to perform the following steps:

  1. Find your Port credentials.
  2. Save them as secrets or in some other same manner such that you can reference them in your code or CI/CD flow.
  3. Make sure you have an HTTP-capable client.
    1. For example: cURL, python with the requests package, nodejs with fetch/axios, etc.

Usage

Since you are using Port's REST API directly, any method that the API provides is at your disposal.

We will focus on three specific use cases:

  • Get catalog entities - available by making HTTP GET requests to https://api.getport.io/v1/blueprints/{blueprint_identifier}/entities/{entity_identifier}, receives the identifier of an existing entity and retrieves it for use in your CI.
  • Create/Update catalog entities - available by making HTTP POST requests to https://api.getport.io/v1/blueprints/{blueprint_identifier}/entities/, receives the identifier and other properties of a new entity or an entity that needs to be updated.
  • Delete catalog entities - available by making HTTP DELETE requests to https://api.getport.io/v1/blueprints/{blueprint_identifier}/entities/{entity_identifier}, receives the identifier of an existing entity and deletes it.
# Dependencies to install:
# $ python -m pip install requests

import requests

CLIENT_ID = 'YOUR_CLIENT_ID'
CLIENT_SECRET = 'YOUR_CLIENT_SECRET'

API_URL = 'https://api.getport.io/v1'

credentials = {'clientId': CLIENT_ID, 'clientSecret': CLIENT_SECRET}

token_response = requests.post(f'{API_URL}/auth/access_token', json=credentials)

access_token = token_response.json()['accessToken']

# You can now use the value in access_token when making further requests

headers = {
'Authorization': f'Bearer {access_token}'
}

blueprint_id = 'MY_BLUEPRINT'
entity_id = 'MY_ENTITY_IDENTIFIER'

response = requests.get(f'{API_URL}/blueprints/{blueprint_id}/entities/{entity_id}', headers=headers)

# response.json() contains the content of the resulting entity