> ## Documentation Index
> Fetch the complete documentation index at: https://docs.useparagon.com/llms.txt
> Use this file to discover all available pages before exploring further.
# API Release Notes
> Release notes for new versions of the Paragon REST API.
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.
## 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 preserved**
Any 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.
## 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](/apis/proxy)
**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.
```diff theme={null}
{
"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`
```diff theme={null}
{
"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:
```diff theme={null}
- 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.