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-07

Scheduled for July 31, 2026

Standardized ActionKit pagination parameters

We are standardizing pagination across ActionKit so developers and agents can use one consistent pagination pattern across list and search actions, regardless of whether the underlying provider uses cursors, page numbers, offsets, or skip tokens.Affected API:

ActionKit Tools API

What’s changing:Pagination input parameters:

Paginated ActionKit actions will support paginationParameters.pageCursor as the standard way to request the next page of results. Treat this value as an opaque string, even when the underlying integration uses a numeric page number or offset.
Actions that support page sizing will support paginationParameters.limit as the standard page size parameter.

Existing pagination input parameter names will remain supportedIf your application already passes action-specific pagination input keys (such as page, pageNo, and pageNumber), those requests will continue to work.For new implementations, we recommend using paginationParameters.pageCursor and, when supported, paginationParameters.limit.

Pagination response parameters:

Paginated responses will standardize on nextPageCursor as a string when another page is available, and null when there are no more pages.

Breaking changeActions that previously returned false or "" for nextPageCursor at the end of pagination will now return null.

What do I need to do?

Handle the breaking change in response parameters:

If you currently check for nextPageCursor === false or nextPageCursor === "" to detect the end of pagination, update that logic to handle nextPageCursor === null.

(Optional) Standardize your pagination code:

For all ActionKit pagination code, pass the returned nextPageCursor value into paginationParameters.pageCursor on the next request.
Treat nextPageCursor as an opaque string. Avoid parsing it as a number or calculating the next page value in your application code.

When will these changes be released?

Changes to set nextPageCursor as null will begin on July 31, 2026 and will gradually roll out across all ActionKit integrations. Updates will be propagated to the Tool-specific docs in the ActionKit Integration Reference.
We recommend updating your application code to handle nextPageCursor === null (or falsey values) as a possible condition for the end of pagination during this transition period.

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.

​Standardized ActionKit pagination parameters

​What do I need to do?

​When will these changes be 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?

Standardized ActionKit pagination parameters

What do I need to do?

When will these changes be 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?