XChange ​

Use this resource to manage XChange packages programmatically. You can browse and author packages and versions, review and approve submitted versions, publish to the private library, distribute packages to workspaces, manage sharing links, and view installation analytics.

Ensure the necessary API client permissions are enabled to access these endpoints.

Rate limits ​

XChange resources have the following rate limit:

Quick reference ​

Browse & create ​

The following endpoints let you list, view, create, import, and update packages and versions, and download a version export.

List packages ​

Lists the packages visible to the caller.

GET https://YOUR_DATA_CENTER/api/xchange/packages

Query parameters ​

Sample request ​

curl  -X GET 'https://YOUR_DATA_CENTER/api/xchange/packages?text=sales&page[number]=1&page[size]=100' \
      -H 'Authorization: Bearer <api_token>'

List a package's versions ​

Lists a package's versions with per-version installation counts. These counts are a lightweight, counts-only surface. For the full statistics surface, use Get package installation statistics.

GET https://YOUR_DATA_CENTER/api/xchange/packages/:package_id/versions

URL parameters ​

Query parameters ​

Sample request ​

curl  -X GET 'https://YOUR_DATA_CENTER/api/xchange/packages/:package_id/versions?exclude_rejected=true' \
      -H 'Authorization: Bearer <api_token>'

Get a package version ​

Shows one version.

GET https://YOUR_DATA_CENTER/api/xchange/versions/:version_id

URL parameters ​

Sample request ​

curl  -X GET 'https://YOUR_DATA_CENTER/api/xchange/versions/:version_id' \
      -H 'Authorization: Bearer <api_token>'

Update a version's metadata ​

Updates an existing version's editable metadata. The endpoint re-fetches and returns the full version.

PUT https://YOUR_DATA_CENTER/api/xchange/versions/:version_id

URL parameters ​

Payload ​

Only version, description, and release_notes are permitted. The endpoint ignores any other field in the request body.

Sample request ​

curl  -X PUT 'https://YOUR_DATA_CENTER/api/xchange/versions/:version_id' \
      -H 'Authorization: Bearer <api_token>' \
      -H "Content-Type: application/json" \
      -d '{
            "release_notes": "Adds the invoice sync recipe and fixes a connection timeout."
         }'

Import a new package from a .zip ​

Imports a .zip as a net-new package and its first version. The endpoint validates the file extension and a 100 MB size cap synchronously, then stages and enqueues an asynchronous import job. Poll the job's progress with Get version creation status.

There's no name parameter. The draft package name comes from the uploaded filename. If you omit version, it defaults to v1.0.

POST https://YOUR_DATA_CENTER/api/xchange/packages/import

Request body ​

Send the request as multipart/form-data.

Sample request ​

curl  -X POST 'https://YOUR_DATA_CENTER/api/xchange/packages/import' \
      -H 'Authorization: Bearer <api_token>' \
      -F 'file=@/path/to/marketing_sync.zip' \
      -F 'version=v1.0' \
      -F 'description=Recipes for marketing and CRM sync.'

Import a new package version from a .zip ​

Imports a .zip as a new version of an existing package, using the same asynchronous pipeline as a net-new package import.

POST https://YOUR_DATA_CENTER/api/xchange/packages/:package_id/versions/import

URL parameters ​

Request body ​

Send the request as multipart/form-data.

Sample request ​

curl  -X POST 'https://YOUR_DATA_CENTER/api/xchange/packages/:package_id/versions/import' \
      -H 'Authorization: Bearer <api_token>' \
      -F 'file=@/path/to/sales_automation_v1.3.zip' \
      -F 'version=1.3.0' \
      -F 'release_notes=Adds the invoice sync recipe.'

Get version creation status ​

Polls the status of a version draft created by a .zip import. The response returns draft status only. It doesn't include generated asset contents or a diff.

GET https://YOUR_DATA_CENTER/api/xchange/versions/:draft_id/version_draft

URL parameters ​

Sample request ​

curl  -X GET 'https://YOUR_DATA_CENTER/api/xchange/versions/:draft_id/version_draft' \
      -H 'Authorization: Bearer <api_token>'

Get a version .zip download URL ​

Gets a short-lived, presigned download URL for a package version's .zip. The API doesn't stream the file directly. It returns a URL you can use to download it.

GET https://YOUR_DATA_CENTER/api/xchange/packages/versions/:version_id/export

URL parameters ​

Sample request ​

curl  -X GET 'https://YOUR_DATA_CENTER/api/xchange/packages/versions/:version_id/export' \
      -H 'Authorization: Bearer <api_token>'

Review and approval ​

The following endpoints let the package owner approve, reject, reset, or comment on a submitted version:

Approve a package version ​

Approves a submitted package version.

POST https://YOUR_DATA_CENTER/api/xchange/versions/:version_id/approve

URL parameters ​

Payload ​

Sample request ​

curl  -X POST 'https://YOUR_DATA_CENTER/api/xchange/versions/:version_id/approve' \
      -H 'Authorization: Bearer <api_token>' \
      -H "Content-Type: application/json" \
      -d '{
            "comments": "Approved for distribution."
         }'

Response ​

The response returns the full package version. The response includes private_library_publication only when the version is published to the private library.

{
    "data": {
        "id": "9f8c2b1e-4a6d-4c2f-9e3a-7b5d1c0a8f21",
        "version": "1.2.0",
        "status": "approved",
        "builder_id": 45231,
        "description": "Sales automation starter package.",
        "release_notes": "Adds the invoice sync recipe.",
        "created_at": "2026-07-10T09:15:32.000-07:00",
        "project_handles": ["sales-automation"],
        "package": {
            "id": "1d2e3f4a-5b6c-4d7e-8f90-a1b2c3d4e5f6",
            "name": "Sales automation",
            "description": "Recipes and connections for sales automation."
        },
        "content": {
            "counters": {},
            "connectors": []
        },
        "projects": [
            {
                "id": "7a8b9c0d-1e2f-4a3b-8c4d-5e6f7a8b9c0d",
                "name": "Sales automation",
                "folder_id": 27180380
            }
        ],
        "installations": {
            "direct": 12,
            "private_library": 4
        },
        "review": {
            "id": "3c4d5e6f-7a8b-4c9d-8e0f-1a2b3c4d5e6f",
            "status": "approved",
            "comments": "Approved for distribution.",
            "updated_at": "2026-07-16T11:02:10.000-07:00",
            "author": {}
        },
        "builder": {
            "id": 45231,
            "name": "Ariel",
            "avatar_url": "https://www.workato.com/assets/avatars/ariel.png"
        }
    }
}

Reject a package version ​

Rejects a submitted package version.

POST https://YOUR_DATA_CENTER/api/xchange/versions/:version_id/reject

URL parameters ​

Payload ​

Sample request ​

curl  -X POST 'https://YOUR_DATA_CENTER/api/xchange/versions/:version_id/reject' \
      -H 'Authorization: Bearer <api_token>' \
      -H "Content-Type: application/json" \
      -d '{
            "comments": "Update the connection descriptions before you resubmit."
         }'

Response ​

The response returns the full package version in the same format as the Approve a package version endpoint, with the version and review status reflecting the rejection.

Reset a version review ​

Resets a submitted version's review to its pre-review state. The request takes no body.

POST https://YOUR_DATA_CENTER/api/xchange/versions/:version_id/reset

URL parameters ​

Sample request ​

curl  -X POST 'https://YOUR_DATA_CENTER/api/xchange/versions/:version_id/reset' \
      -H 'Authorization: Bearer <api_token>'

Update a review comment ​

Updates an existing review comment.

PUT https://YOUR_DATA_CENTER/api/xchange/versions/:version_id/comment/:review_id

URL parameters ​

Payload ​

Sample request ​

curl  -X PUT 'https://YOUR_DATA_CENTER/api/xchange/versions/:version_id/comment/:review_id' \
      -H 'Authorization: Bearer <api_token>' \
      -H "Content-Type: application/json" \
      -d '{
            "comments": "Approved. Nice work on the connection cleanup."
         }'

Private Library ​

The following endpoints let the package owner publish or unpublish a version to the Discovery Layer's private library.

Publish a version ​

Publishes an approved version to the private library.

PUT https://YOUR_DATA_CENTER/api/xchange/packages/:package_id/versions/:version_id/publish

URL parameters ​

Payload ​

Sample request ​

curl  -X PUT 'https://YOUR_DATA_CENTER/api/xchange/packages/:package_id/versions/:version_id/publish' \
      -H 'Authorization: Bearer <api_token>' \
      -H "Content-Type: application/json" \
      -d '{
            "card_description": "A starter package for sales automation."
         }'

Unpublish a version ​

Removes the package's private library publication. Existing installations remain.

PUT https://YOUR_DATA_CENTER/api/xchange/packages/:package_id/versions/:version_id/unpublish

URL parameters ​

Sample request ​

curl  -X PUT 'https://YOUR_DATA_CENTER/api/xchange/packages/:package_id/versions/:version_id/unpublish' \
      -H 'Authorization: Bearer <api_token>'

Direct Distribution ​

The following endpoints let the package owner mass-distribute a version to workspaces and list who consumes the package:

List package consumers ​

Returns the consumers of a package. You can filter consumers by installation status and search by name or external ID.

GET https://YOUR_DATA_CENTER/api/xchange/packages/:package_id/consumers

URL parameters ​

Query parameters ​

Sample request ​

This request retrieves consumers of the package that installed a specific version.

curl  -X GET 'https://YOUR_DATA_CENTER/api/xchange/packages/:package_id/consumers?installation_status=installed&version_id=:version_id' \
      -H 'Authorization: Bearer <api_token>'

Response ​

The avatar_url and external_id parameters must be set for the consumer to be included in the response.

{
    "data": [
        {
            "id": 45231,
            "name": "Acme West",
            "avatar_url": "https://www.workato.com/assets/avatars/acme-west.png",
            "external_id": "acme-west-01"
        },
        {
            "id": 45232,
            "name": "Acme East"
        }
    ],
    "page": {
        "number": 1,
        "size": 100,
        "total": 2
    }
}

Create a distribution batch ​

Creates a distribution batch for a package version and enqueues it for processing.

POST https://YOUR_DATA_CENTER/api/xchange/distributions

Payload ​

Sample request ​

The following sample request distributes the package version to two target environments:

curl  -X POST 'https://YOUR_DATA_CENTER/api/xchange/distributions' \
      -H 'Authorization: Bearer <api_token>' \
      -H "Content-Type: application/json" \
      -d '{
            "version_id": ":version_id",
            "environment_ids": [40012, 40018]
         }'

Response ​

The endpoint returns a 201 response with the UUID of the new batch. Use the Get a distribution batch by ID endpoint to monitor the batch status.

{
    "data": {
        "id": "6b7c8d9e-0f1a-4b2c-9d3e-4f5a6b7c8d9e"
    }
}

List distribution batches ​

Returns a list of distribution batches, optionally scoped to a package.

GET https://YOUR_DATA_CENTER/api/xchange/distributions

Query parameters ​

Sample request ​

The following sample request retrieves active distribution batches for a package version:

curl  -X GET 'https://YOUR_DATA_CENTER/api/xchange/distributions?version_id=:version_id&active=true' \
      -H 'Authorization: Bearer <api_token>'

Response ​

{
    "data": [
        {
            "id": "6b7c8d9e-0f1a-4b2c-9d3e-4f5a6b7c8d9e",
            "version_id": "9f8c2b1e-4a6d-4c2f-9e3a-7b5d1c0a8f21",
            "version": "1.2.0",
            "status": "in_progress",
            "target_workspaces": {
                "total": 2,
                "pending": 1,
                "completed": 1,
                "failed": 0
            },
            "created_at": "2026-07-16T08:30:00.000-07:00"
        }
    ],
    "page": {
        "number": 1,
        "size": 100,
        "total": 1
    }
}

Get a distribution batch by ID ​

Returns a distribution batch, optionally with per-target distribution details.

GET https://YOUR_DATA_CENTER/api/xchange/distributions/:id

URL parameters ​

Query parameters ​

Sample request ​

The following sample request retrieves a distribution batch with per-target details:

curl  -X GET 'https://YOUR_DATA_CENTER/api/xchange/distributions/:id?include_details=true' \
      -H 'Authorization: Bearer <api_token>'

Response ​

The response includes the details array and the top-level page and total fields only when include_details is set to true. Each detail includes error only when the detail status is failed.

{
    "data": {
        "id": "6b7c8d9e-0f1a-4b2c-9d3e-4f5a6b7c8d9e",
        "version_id": "9f8c2b1e-4a6d-4c2f-9e3a-7b5d1c0a8f21",
        "version": "1.2.0",
        "status": "completed",
        "target_workspaces": {
            "total": 2,
            "pending": 0,
            "completed": 1,
            "failed": 1
        },
        "created_at": "2026-07-16T08:30:00.000-07:00",
        "details": [
            {
                "id": "0a1b2c3d-4e5f-4a6b-8c7d-8e9f0a1b2c3d",
                "environment_id": 40012,
                "environment_name": "Acme West - prod",
                "environment_external_id": "acme-west-01",
                "status": "completed",
                "updated_at": "2026-07-16T08:41:15.000-07:00"
            },
            {
                "id": "5f6a7b8c-9d0e-4f1a-8b2c-3d4e5f6a7b8c",
                "environment_id": 40018,
                "environment_name": "Acme East - prod",
                "environment_external_id": "acme-east-01",
                "status": "failed",
                "error": "Connector version conflict in the target environment.",
                "updated_at": "2026-07-16T08:42:03.000-07:00"
            }
        ]
    },
    "page": 1,
    "total": 2
}

Retry failed distributions ​

Retries and re-enqueues failed distributions in a batch for processing. The endpoint returns a 422 error if the batch doesn't contain failed distributions.

POST https://YOUR_DATA_CENTER/api/xchange/distributions/:id/retry_failed

URL parameters ​

Sample request ​

curl  -X POST 'https://YOUR_DATA_CENTER/api/xchange/distributions/:id/retry_failed' \
      -H 'Authorization: Bearer <api_token>'

Response ​

{
    "data": {
        "id": "6b7c8d9e-0f1a-4b2c-9d3e-4f5a6b7c8d9e"
    }
}

Link sharing ​

The following endpoints let the package owner manage a package's sharing links and its shared-link version:

List sharing links ​

Lists a package's sharing links.

GET https://YOUR_DATA_CENTER/api/xchange/packages/:package_id/sharing/links

URL parameters ​

Query parameters ​

Sample request ​

curl  -X GET 'https://YOUR_DATA_CENTER/api/xchange/packages/:package_id/sharing/links?status=active' \
      -H 'Authorization: Bearer <api_token>'

Create sharing links ​

Creates one public link, or one or more workspace-scoped links.

POST https://YOUR_DATA_CENTER/api/xchange/packages/:package_id/sharing/links

URL parameters ​

Payload ​

Sample request ​

curl  -X POST 'https://YOUR_DATA_CENTER/api/xchange/packages/:package_id/sharing/links' \
      -H 'Authorization: Bearer <api_token>' \
      -H "Content-Type: application/json" \
      -d '{
            "kind": "public",
            "name": "Sales automation - partner preview"
         }'

Activate a sharing link ​

Sets a link's status to active. You can call this endpoint multiple times without changing the result.

POST https://YOUR_DATA_CENTER/api/xchange/packages/:package_id/sharing/links/:link_id/activate

URL parameters ​

Sample request ​

curl  -X POST 'https://YOUR_DATA_CENTER/api/xchange/packages/:package_id/sharing/links/:link_id/activate' \
      -H 'Authorization: Bearer <api_token>'

Deactivate a sharing link ​

Sets a link's status to inactive. You can call this endpoint multiple times without changing the result.

POST https://YOUR_DATA_CENTER/api/xchange/packages/:package_id/sharing/links/:link_id/deactivate

URL parameters ​

Sample request ​

curl  -X POST 'https://YOUR_DATA_CENTER/api/xchange/packages/:package_id/sharing/links/:link_id/deactivate' \
      -H 'Authorization: Bearer <api_token>'

Delete a sharing link ​

Permanently deletes a sharing link.

DELETE https://YOUR_DATA_CENTER/api/xchange/packages/:package_id/sharing/links/:link_id

URL parameters ​

Sample request ​

curl  -X DELETE 'https://YOUR_DATA_CENTER/api/xchange/packages/:package_id/sharing/links/:link_id' \
      -H 'Authorization: Bearer <api_token>'

Set the package's shared-link version ​

Marks a version that's approved or published as the package's shared-link version.

PUT https://YOUR_DATA_CENTER/api/xchange/packages/:package_id/versions/:version_id/share

URL parameters ​

Sample request ​

curl  -X PUT 'https://YOUR_DATA_CENTER/api/xchange/packages/:package_id/versions/:version_id/share' \
      -H 'Authorization: Bearer <api_token>'

Clear the package's shared-link version ​

Clears the package's shared-link version. This only succeeds when version_id in the URL matches the current shared-link version.

DELETE https://YOUR_DATA_CENTER/api/xchange/packages/:package_id/versions/:version_id/share

URL parameters ​

Sample request ​

curl  -X DELETE 'https://YOUR_DATA_CENTER/api/xchange/packages/:package_id/versions/:version_id/share' \
      -H 'Authorization: Bearer <api_token>'

Analytics ​

The following endpoints return a package's installation statistics and per-workspace installation report:

Get package installation statistics ​

Returns a package's installation statistics. The summary block is package-wide and isn't affected by the version_id filter or pagination. by_version is the paginated per-version breakdown.

GET https://YOUR_DATA_CENTER/api/xchange/packages/:package_id/stats

URL parameters ​

Query parameters ​

Sample request ​

curl  -X GET 'https://YOUR_DATA_CENTER/api/xchange/packages/:package_id/stats' \
      -H 'Authorization: Bearer <api_token>'

Get per-workspace installation report ​

Returns a package's per-workspace installation report.

GET https://YOUR_DATA_CENTER/api/xchange/packages/:package_id/installations

URL parameters ​

Query parameters ​

Sample request ​

curl  -X GET 'https://YOUR_DATA_CENTER/api/xchange/packages/:package_id/installations?version_id=:version_id' \
      -H 'Authorization: Bearer <api_token>'