API Release Notes

​

Updates to GET /sdk/integrations and Proxy API

To improve the ergonomics of the API, we are introducing a few changes to the GET /projects/:projectId/sdk/integrations and Proxy API endpoints for Custom Integrations.

We are also removing some unnecessary fields from the response of the GET /projects/:projectId/sdk/integrations endpoint to improve performance. Please review these changes to ensure that your application is not using any of the fields scheduled for removal.

Affected endpoints:

• GET /projects/:projectId/sdk/integrations
• Proxy API

Breaking changes:

• In GET /projects/:projectId/sdk/integrations, the type field of Custom Integrations will now be the full slug that is used in paragon.connect() calls.

  Show Example

  Copy

  Ask AI

  {
      "id": "77210f70-4f20-4eac-bded-825732b229c3",
      "projectId": "1ea8024c-23a7-4885-b925-c50d0faf9318",
      "customIntegrationId": "d8fe6169-8119-4cb0-a7a9-c2b18aff2c07",
      "name": "Example",
  -   "type": "custom",
  +   "type": "custom.example",
      "isActive": true,
      "configs": [...],
      "workflows": [...],
      "customIntegration": {
          "id": "d8fe6169-8119-4cb0-a7a9-c2b18aff2c07",
          "projectId": "1ea8024c-23a7-4885-b925-c50d0faf9318",
          "name": "Example",
          "isPublished": true,
          "slug": "custom.example"
      },
      "hasCredential": true,
      "connectedUserLimitOnDevCred": 0,
      "connectedUserLimitReached": false,
      "brandColor": "#000000",
      "needPreOauthInputs": false,
      "authenticationType": "oauth",
      "sdkIntegrationConfig": null
  }
  

• In GET /projects/:projectId/sdk/integrations, some unnecessary fields are being removed from Integrations:

  • To optimize the performance of this endpoint, some fields of Integrations are being removed. Please ensure that the following fields are not in use by your application:
    • integration.dateCreated
    • integration.dateUpdated
    • integration.resourceId
    • integration.configs[].dateCreated
    • integration.configs[].dateUpdated
    • integration.configs[].integrationId
    • integration.workflows[].dateCreated
    • integration.workflows[].dateUpdated
    • integration.workflows[].teamId
    • integration.workflows[].isOnboardingWorkflow
    • integration.workflows[].workflowVersion
    • integration.customIntegration.dateCreated
    • integration.customIntegration.dateUpdated
    • integration.customIntegration.projectId
    • integration.customIntegration.oauthScopes
    • integration.customIntegration.oauthIncludeClientAuthorizationHeader
    • integration.customIntegration.usePKCEInCodeExchange
    • integration.customIntegration.apiBaseUrl
    • integration.customIntegration.testEndpointPath
    • integration.customIntegration.isTestEndpointVerified
    • integration.customIntegration.apiAuthorization
    • integration.customIntegration.userProfileConfig

  Show Example

  Copy

  Ask AI

  {
      "id": "f02dba2f-d149-4664-958d-138d546d987b",
  -   "dateCreated": "2023-10-23T17:03:16.211Z",
  -   "dateUpdated": "2023-10-23T17:03:16.211Z",
      "projectId": "1ea8024c-23a7-4885-b925-c50d0faf9318",
      "customIntegrationId": "208d5d99-bbb4-4147-b991-83e220da192c",
  -   "resourceId": null,
      "type": "custom.spotify",
      "isActive": false,
      "configs": [
          {
              "id": "70c9c3f6-f68c-4e06-921e-0ee678bc6a9f",
  -           "dateCreated": "2023-10-23T17:03:16.211Z",
  -           "dateUpdated": "2023-10-23T17:03:16.211Z",
  -           "integrationId": "f02dba2f-d149-4664-958d-138d546d987b",
              "values": {
                  "accentColor": "#000000",
                  "description": "play music",
                  "workflowMeta": {}
              }
          }
      ],
      "workflows": [
          {
              "id": "0d6660ac-2396-4442-98a3-4321fa6ce42b",
  -           "dateCreated": "2024-06-04T13:16:32.660Z",
  -           "dateUpdated": "2024-06-04T13:17:03.374Z",
              "description": "Example Workflow",
              "projectId": "1ea8024c-23a7-4885-b925-c50d0faf9318",
  -           "teamId": "72c5150b-6bfa-4972-9845-1350f3ee18bc",
  -           "isOnboardingWorkflow": false,
              "integrationId": "b62baf56-5030-4105-9c78-dbf307e1ee94",
  -           "workflowVersion": 1,
              "steps": []
          }
      ],
      "customIntegration": {
          "id": "208d5d99-bbb4-4147-b991-83e220da192c",
  -       "dateCreated": "2023-10-23T17:03:16.211Z",
  -       "dateUpdated": "2023-10-23T17:03:16.211Z",
  -       "projectId": "1ea8024c-23a7-4885-b925-c50d0faf9318",
          "name": "Spotify",
          "authenticationType": "oauth",
          "inputFields": [],
          "oauthAuthorizationUrl": { "type": "TOKENIZED", "parts": [{ "type": "VALUE", "value": "https://accounts.spotify.com/authorize", "dataType": "STRING" }], "dataType": "STRING" },
          "oauthAccessTokenUrl": { "type": "TOKENIZED", "parts": [{ "type": "VALUE", "value": "https://accounts.spotify.com/api/token", "dataType": "STRING" }], "dataType": "STRING" },
  -       "oauthScopes": "user-read-private",
  -       "oauthIncludeClientAuthorizationHeader": true,
  -       "usePKCEInCodeExchange": false,
  -       "apiBaseUrl": { "type": "TOKENIZED", "parts": [ { "type": "VALUE", "value": "https://api.spotify.com/v1", "dataType": "STRING" } ], "dataType": "STRING" },
  -       "testEndpointPath": { "type": "TOKENIZED", "parts": [], "dataType": "STRING" },
  -       "isTestEndpointVerified": false,
  -       "apiAuthorization": { "type": "bearer", "token": { "type": "TOKENIZED", "parts": [ { "type": "CONNECT_CREDENTIAL_FIELD", "fieldType": "OAUTH_ACCESS_TOKEN" } ] } },
          "isPublished": true,
  -       "userProfileConfig": {},
          "slug": "custom.spotify"
      },
      "hasCredential": true,
      "connectedUserLimitOnDevCred": 0,
      "connectedUserLimitReached": false,
      "name": "Spotify",
      "brandColor": "#000000",
      "needPreOauthInputs": false,
      "authenticationType": "oauth",
      "sdkIntegrationConfig": null
  }
  

Other non-breaking changes:

• Proxy API now supports using the custom.name format when sending Proxy requests for Custom Integrations

  • Instead of passing in a customIntegrationId, you will now be able to pass in custom.name (the same slug used for paragon.connect) directly to the Proxy API.

  • Example:

    Copy

    Ask AI

    - https://proxy.useparagon.com/projects/:projectId/sdk/proxy/custom/:customIntegrationId/:path
    + https://proxy.useparagon.com/projects/:projectId/sdk/proxy/custom.integrationName/:path
    
    

​

What do I need to do?

• Verify that your use of integrations.type for Custom Integrations does not rely on the value being exactly "custom". The new type field will include the full slug value, e.g. custom.integrationName.
• Verify that you are not using any of the fields scheduled for removal from the API.

​

When are these changes being released?

• These changes will be released on July 7, 2025.