> ## 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.

<Update label="2026-07" description="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](/actionkit/api-reference)

  **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.

  <Check>
    **Existing pagination input parameter names will remain supported**

    If 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`.
  </Check>

  **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.

  <Note>
    **Breaking change**

    Actions that previously returned `false` or `""` for `nextPageCursor` at the end of pagination will now return `null`.
  </Note>

  ## 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](/actionkit/integrations/slack/overview).
  * 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.
</Update>

<Update label="2026-04" description="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.

  <Check>
    **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.
  </Check>

  ## 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.
</Update>

<Update label="2025-07" description="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](/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.
      <Expandable title="Example">
        ```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
        }
        ```
      </Expandable>

  * 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`

      <Expandable title="Example">
        ```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
        }
        ```
      </Expandable>

  **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.
</Update>