API Release Notes - Paragon Documentation

This page lists all breaking changes for the Paragon REST API. We make a best effort to keep our API endpoints backwards-compatible with existing usage, but in cases where that is not possible, we will provide advanced notice and guidance on how to adapt to the changes.

2026-04

Released April 2, 2026

Custom Integration identifiers are now immutable

Before this change, changing the display name of a Custom Integration would result in a change in the integration identifier/slug (used in paragon.connect) and the Paragraph source path (after a para pull). For example, changing “TaskLab” to “Apex Tasks” would result in a change from custom.tasklab to custom.apextasks.This identifier is now immutable and set at the time your Custom Integration is created. For existing Custom Integrations, the identifier will be set immutably to the same value it currently has in your project.

Existing Custom Integration identifiers are preservedAny hard-coded references you may use to existing Custom Integration identifiers will continue to work as expected, since the identifier has been set immutably to its current value. Any future changes to the display name will no longer impact this identifier.

What do I need to do?

Treat the slug returned by the API as the source of truth for Custom Integrations. If your application already uses the slug returned by the API as the source of truth for identifiers, no changes are required.
Replace any logic in your application that may derive Custom Integration identifiers from the display name with the slug property provided by the API. A published Custom Integration’s identifier will no longer change when its display name changes.
Upgrade the @useparagon/connect SDK to v2.3.1 or later.
- @useparagon/connect SDK versions < 2.3.1 (which derive the identifier from the integration name) will continue to use name-derived identifiers and work without issue. You can upgrade to v2.3.1 or later to use the current, immutable identifiers.
Upgrade @useparagon/paragraph to v1.1.1 or later.

When were these changes released?

These changes were released on April 2, 2026. Platform versions of >= v2026.0402 will include this update.

2025-07

Released July 7, 2025

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

{
    "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

{
    "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:
  - 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 were these changes released?

These changes were released on July 7, 2025.

Product Updates

Release Notes

​Custom Integration identifiers are now immutable

​What do I need to do?

​When were these changes released?

​Updates to GET /sdk/integrations and Proxy API

​What do I need to do?

​When were these changes released?

Custom Integration identifiers are now immutable

What do I need to do?

When were these changes released?

Updates to GET /sdk/integrations and Proxy API

What do I need to do?

When were these changes released?