Integration Information

Use the REST API to fetch integration information including settings and errors

Authenticating

To begin, you will need to authenticate to the Polarity Server to obtain a reusable bearer token that will be used with subsequent authenticated requests.

See Authentication for information on how to authenticate to the Polarity Platform and acquire an authentication token. The authentication token will be used in all the requests outlined below and is referenced in examples as <AUTH_TOKEN>.

Get Integrations

You can retrieve information about integrations by using the GET /api/integrations endpoint. This endpoint will return information about integrations installed on your server to include running status, integration option values, and references to any integration errors.

Examples

curl

curl -v -X GET \
https://<POLARITY_HOSTNAME>/api/integrations \
--header 'Authorization: Bearer <AUTH_TOKEN>' \
--header 'Content-Type: application/vnd.api+json'

python

import requests
import json

def get_integrations(token, host):
    url = f'{host}/api/integrations'

    headers = {
        'Content-Type': 'application/vnd.api+json',
        'Authorization': f'Bearer {token}'
    }

    response = requests.request('GET', url, headers=headers)
    response.raise_for_status()

    return response.json()
    
integrations = get_integrations('my-auth-token', 'https://my-server')    

Replace <POLARITY_HOSTNAME> with the hostname of your Polarity server and <AUTH_TOKEN> with the value of your bearer token.

Paging

The default page size for the endpoint is 100 which means if you have more than 100 installed integrations you will need to increase the page size or page through the results using the page[size] and page[number] query parameters. The parameter page[size] tells the endpoint the maximum number of results to return and the parameter page[number] tells the endpoint which page of results to return.

curl

Paging

curl -v -X GET -G \
'https://<POLARITY_HOSTNAME>/api/integrations' \
--header 'Authorization: Bearer <AUTH_TOKEN>' \
--header 'Content-Type: application/vnd.api+json' \
-d page[size]=200 \
-d page[number]=1

python

Paging

import requests
import json

def get_integrations(token, host):
    url = f'{host}/api/integrations'

    params = {
        'page[size]': 200,
        'page[number]': 1
    }
    
    headers = {
        'Content-Type': 'application/vnd.api+json',
        'Authorization': f'Bearer {token}'
    }

    response = requests.request('GET', url, headers=headers, params=params)
    response.raise_for_status()

    return response.json()
    
integrations = get_integrations('my-auth-token', 'https://my-server')    

Filtering

Integration Status

You can return only integrations that are running by using the query parameter filter[integration.status]=running

curl

Filtering Status

curl -v -X GET -G \
'https://<POLARITY_HOSTNAME>/api/integrations' \
--header 'Authorization: Bearer <AUTH_TOKEN>' \
--header 'Content-Type: application/vnd.api+json' \
-d filter[integration.status]=running

python

Filtering Status

import requests
import json

def get_integrations(token, host):
    url = f'{host}/api/integrations'

    params = {
        'filter[integration.status]': 'running'
    }
    
    headers = {
        'Content-Type': 'application/vnd.api+json',
        'Authorization': f'Bearer {token}'
    }

    response = requests.request('GET', url, headers=headers, params=params)
    response.raise_for_status()

    return response.json()
    
integrations = get_integrations('my-auth-token', 'https://my-server')  

Integration Errors

You can return only integrations with errors using the filter[integration.integration-errors]=true query parameter.

curl

Filtering Errors

curl -v -X GET -G \
'https://<POLARITY_HOSTNAME>/api/integrations' \
--header 'Authorization: Bearer <AUTH_TOKEN>' \
--header 'Content-Type: application/vnd.api+json' \
-d filter[integration.integration-errors]=true

python

Filtering Errors

import requests
import json

def get_integrations_with_errors(token, host):
    url = f'{host}/api/integrations'

    params = {
        'filter[integration.integration-errors]': true
    }
    
    headers = {
        'Content-Type': 'application/vnd.api+json',
        'Authorization': f'Bearer {token}'
    }

    response = requests.request('GET', url, headers=headers, params=params)
    response.raise_for_status()

    return response.json()
    
integrations = get_integrations_with_errors('my-auth-token', 'https://my-server')  

Return Payload Format

The endpoint will return a JSON payload with a list of integration models as part of a top level data key. In addition, there will be a top level meta key which contains paging information including the page.total attribute which indicates the total number of integrations that could be returned by the endpoint given the applied filtering.

Return Data Example

{
  "data": [
     // one or more integration models
   ],
   "meta": {
     "page": {
       "number": 1, // current page number
       "size": 100, // number of integrations returned per page
       "total": 135 // total number of integrations matching the filter criteria
     }
   }
}  

Each integration model contained within data will have the following structure:

Integration Model

{
  "attributes": {
    // integration model attributes
  },
  "id": "<INTEGRATION_ID>",
  "links": {
    "self": "/api/integrations/<INTEGRATION_ID>"
  },
  "relationships": {
    "integration-errors": {
      "data": [
        // list of integration errors (empty if there are no errors
       ]
      "links": {
        "self": "/api/integration-errors?filter[integration.id]=<INTEGRATION_ID>"
      }
    },
    "integration-options": {
      "data": [
        // list of integration options
      ],
      "links": {
        "self": "/api/integration-options?filter[integration.id]=<INTEGRATION_ID>
      }
  },
  "type": "integrations"
}

Integration Attributes

To view a full list of integration attributes returned by the fetch integration endpoints see the Integration Attributes page.

Integration Attributes

Get Integration Errors

You can fetch all integration errors using the GET /api/integrations/errors endpoint. Only integration managers and Polarity admins are able to view errors for integrations.

Examples

curl

curl -v -X GET \
https://<POLARITY_HOSTNAME>/api/integrations/errors \
--header 'Authorization: Bearer <AUTH_TOKEN>' \
--header 'Content-Type: application/vnd.api+json'

python

import requests
import json

def get_integration_errors(token, host):
    url = f'{host}/api/integrations/errors'

    headers = {
        'Content-Type': 'application/vnd.api+json',
        'Authorization': f'Bearer {token}'
    }

    response = requests.request('GET', url, headers=headers)
    response.raise_for_status()

    return response.json()
    
integration_errors = get_integration_errors('my-auth-token', 'https://my-server')    

This endpoint does not support paging and will return all available errors.

Return Payload Format

The errors endpoint will return an array of error models within a top level data attribute.

{
  "data": [
    // Zero or more error models
  ],
  "jsonapi": {
    "version": "1.0"
  }
}  

The error model has the following format:

Error Model

{
  "attributes": {
    // error attributes
  },
  "id": "<ERROR_ID>",
  "links": {
    "self": "/api/integration/<INTEGRATION_ID>/errors/<ERROR_ID>"
  },
  "relationships": {
    "integration": {
      "data": {
        "id": "<INTEGRATION_ID>"
        "type": "integrations"
      }
    }
  },
  "type": "integration-errors"
}

Error Attributes

Each error model has fixed attributes common to all errors and then also includes a meta attribute which contains integration specific error information.

attribute	type	description
code	string	A short error description
title	string	A title for the error
detail	string	A more detailed description of the error
error-count	number	The number of times the specific error has occurred.
integration-id	string	The id of the integration that returned the error
meta	object	An object containing integration specific error details. This meta property typically contains detailed information to include stack traces and integration specific REST API error information including HTTP status codes returned by the REST API the integration is accessing.
meta.affected_users	object	The meta.affected_users attribute contains one or more user objects. The user objects include a user id and username attribute for Polarity users that triggered/caused the specific error. This attribute, when available, can be used to determine which users are affected by a specific error.
occurred-on	string	An ISO 8601 formatted date-time string detailing the the last time the error occurred (e.g., 2024-04-08 14:20:07.834943Z)
status	number	An HTTP status code associated with the error