Product UpdatesStatus PageWorkato Academy
English
日本語
Get a trial
Developer API
Resources

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.

AVAILABILITY

XChange APIs are available for workspaces with XChange enabled. Requests from workspaces without owner or contributor access to XChange return a 404 error.

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

Rate limits ​

XChange resources have the following rate limit:

TypeResourceQuota
AllAll XChange endpoints60 requests per second

Quick reference ​

TypeResourceDescription
GET/api/xchange/packagesList packages visible to the caller.
GET/api/xchange/packages/:package_id/versionsList a package's versions.
GET/api/xchange/versions/:version_idGet a package version.
PUT/api/xchange/versions/:version_idUpdate a version's metadata.
POST/api/xchange/packages/importImport a new package from a .zip.
POST/api/xchange/packages/:package_id/versions/importImport a new package version from a .zip.
GET/api/xchange/versions/:draft_id/version_draftGet version creation status.
GET/api/xchange/packages/versions/:version_id/exportGet a version .zip download URL.
POST/api/xchange/versions/:version_id/approveApprove a package version.
POST/api/xchange/versions/:version_id/rejectReject a package version.
POST/api/xchange/versions/:version_id/resetReset a version review.
PUT/api/xchange/versions/:version_id/comment/:review_idUpdate a review comment.
PUT/api/xchange/packages/:package_id/versions/:version_id/publishPublish a version.
PUT/api/xchange/packages/:package_id/versions/:version_id/unpublishUnpublish a version.
GET/api/xchange/packages/:package_id/consumersList the consumers of a package.
POST/api/xchange/distributionsCreate and enqueue a distribution batch.
GET/api/xchange/distributionsList distribution batches.
GET/api/xchange/distributions/:idGet a distribution batch by ID.
POST/api/xchange/distributions/:id/retry_failedRetry failed distributions in a batch.
GET/api/xchange/packages/:package_id/sharing/linksList a package's sharing links.
POST/api/xchange/packages/:package_id/sharing/linksCreate sharing links.
POST/api/xchange/packages/:package_id/sharing/links/:link_id/activateActivate a sharing link.
POST/api/xchange/packages/:package_id/sharing/links/:link_id/deactivateDeactivate a sharing link.
DELETE/api/xchange/packages/:package_id/sharing/links/:link_idDelete a sharing link.
PUT/api/xchange/packages/:package_id/versions/:version_id/shareSet the package's shared-link version.
DELETE/api/xchange/packages/:package_id/versions/:version_id/shareClear the package's shared-link version.
GET/api/xchange/packages/:package_id/statsGet package installation statistics.
GET/api/xchange/packages/:package_id/installationsGet per-workspace installation report.

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 ​

NameTypeDescription
statusstring
optional		Filters packages by the status of their versions or publications.
builder_idnumber
optional		Filters packages by builder user ID.
tenant_builder_idnumber
optional		Filters packages by tenant-builder workspace ID.
textstring
optional		Searches packages by name.
sortstring
optional		The field to sort by. Add a leading - to sort in descending order.
page[number]number
optional		Page number.
page[size]number
optional		Number of items per page.
Sample request ​
shell
curl  -X GET 'https://YOUR_DATA_CENTER/api/xchange/packages?text=sales&page[number]=1&page[size]=100' \
      -H 'Authorization: Bearer <api_token>'
Response ​
json
{
    "data": [
        {
            "id": "1d2e3f4a-5b6c-4d7e-8f90-a1b2c3d4e5f6",
            "name": "Sales automation",
            "description": "Recipes and connections for sales automation.",
            "is_own": true,
            "is_published": true,
            "last_version": {
                "version": "1.2.0",
                "status": "published",
                "release_notes": "- New: Invoice sync recipe.\n- Improved: Connection error messages.",
                "connectors": [
                    "salesforce",
                    "netsuite"
                ]
            },
            "latest_activity": {
                "user_id": 45231,
                "user_name": "Ariel",
                "event_type": "package_version_created",
                "timestamp": "2026-07-10T09:15:32.000-07:00"
            }
        },
        {
            "id": "2e3f4a5b-6c7d-4e8f-9a0b-1c2d3e4f5a6b",
            "name": "Marketing sync",
            "description": "Recipes for marketing and CRM sync.",
            "is_own": true,
            "is_published": false,
            "last_version": {
                "version": "1.0.0",
                "status": "pending_review",
                "release_notes": "- Added: Lead sync recipe.\n- Improved: Field mapping.",
                "connectors": [
                    "hubspot"
                ]
            },
            "latest_activity": {
                "user_id": 45455,
                "user_name": "Dana",
                "event_type": "package_version_created",
                "timestamp": "2026-08-20T10:05:00.000-07:00"
            }
        }
    ],
    "page": {
        "number": 1,
        "size": 100
    },
    "total": 2
}

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 ​

NameTypeDescription
package_idstring
required		The UUID of the package.

Query parameters ​

NameTypeDescription
builder_idnumber
optional		Filters versions by the builder who created them.
created_at_fromstring
optional		Returns versions created on or after this date. Format: YYYY-MM-DD.
created_at_tostring
optional		Returns versions created on or before this date. Format: YYYY-MM-DD.
exclude_rejectedboolean
optional		Set to true to exclude rejected versions from the response.
page[number]number
optional		Page number.
page[size]number
optional		Number of items per page.
Sample request ​
shell
curl  -X GET 'https://YOUR_DATA_CENTER/api/xchange/packages/:package_id/versions?exclude_rejected=true' \
      -H 'Authorization: Bearer <api_token>'
Response ​
json
{
    "data": [
        {
            "id": "9f8c2b1e-4a6d-4c2f-9e3a-7b5d1c0a8f21",
            "version": "1.2.0",
            "status": "published",
            "release_notes": "- New: Invoice sync recipe.\n- Improved: Connection error messages.\n- Fixed: Timeout on large syncs.",
            "created_at": "2026-07-10T09:15:32.000-07:00",
            "last_installed_at": "2026-07-16T08:41:15.000-07:00",
            "installations": {
                "direct": 12,
                "private_library": 4,
                "sharing_link": 1
            }
        },
        {
            "id": "8e7d6c5b-4a3f-4c2d-9e1a-0b8c7d6e5f4a",
            "version": "1.1.0",
            "status": "approved",
            "release_notes": "- Added: Initial CRM sync recipe.",
            "created_at": "2026-06-02T09:00:00.000-07:00",
            "last_installed_at": null,
            "installations": {
                "direct": 0,
                "private_library": 0,
                "sharing_link": 0
            }
        }
    ],
    "max_installations_count": 12,
    "page": {
        "number": 1,
        "size": 100
    },
    "total": 2
}

Get a package version ​

Shows one version.

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

URL parameters ​

NameTypeDescription
version_idstring
required		The UUID of the version.
Sample request ​
shell
curl  -X GET 'https://YOUR_DATA_CENTER/api/xchange/versions/:version_id' \
      -H 'Authorization: Bearer <api_token>'
Response ​

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

json
{
    "data": {
        "id": "9f8c2b1e-4a6d-4c2f-9e3a-7b5d1c0a8f21",
        "version": "1.2.0",
        "status": "published",
        "builder_id": 45231,
        "builder": {
            "id": 45231,
            "name": "Ariel",
            "avatar_url": "https://www.workato.com/assets/avatars/ariel.png"
        },
        "description": "Sales automation starter package.",
        "release_notes": "- New: Invoice sync recipe.\n- Improved: Connection error messages.\n- Fixed: Timeout on large syncs.",
        "created_at": "2026-07-10T09:15:32.000-07:00",
        "project_handles": ["sales-automation"],
        "content": {
            "counters": {
                "recipe": 6
            },
            "connectors": [
                "salesforce",
                "netsuite"
            ]
        },
        "package": {
            "id": "1d2e3f4a-5b6c-4d7e-8f90-a1b2c3d4e5f6",
            "name": "Sales automation",
            "description": "Recipes and connections for sales automation."
        },
        "projects": [
            {
                "id": 7801234,
                "name": "Sales automation",
                "folder_id": 27180380
            }
        ],
        "installations": {
            "direct": 12,
            "private_library": 4,
            "sharing_link": 1
        },
        "private_library_publication": {
            "id": "4d5e6f7a-8b9c-4d0e-8f1a-2b3c4d5e6f7a",
            "card_description": "A starter package for sales automation.",
            "version": {
                "id": "9f8c2b1e-4a6d-4c2f-9e3a-7b5d1c0a8f21",
                "version": "1.2.0"
            }
        },
        "review": {
            "id": "3c4d5e6f-7a8b-4c9d-8e0f-1a2b3c4d5e6f",
            "status": "approved",
            "comments": "Approved for distribution.",
            "updated_at": "2026-07-16T11:02:10.000-07:00",
            "author": {
                "id": 45301,
                "name": "Bola",
                "avatar_url": "https://www.workato.com/assets/avatars/bola.png"
            }
        }
    }
}

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 ​

NameTypeDescription
version_idstring
required		The UUID of the version to update.

Payload ​

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

NameTypeDescription
versionstring
optional		The version label, for example 1.3.0.
descriptionstring
optional		The package version's description.
release_notesstring
optional		The version's release notes.
Sample request ​
shell
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."
         }'
Response ​

The response returns the full version in the same format as the Get a package version endpoint, with release_notes reflecting the update. The response includes private_library_publication only when the version is published to the private library.

json
{
    "data": {
        "id": "9f8c2b1e-4a6d-4c2f-9e3a-7b5d1c0a8f21",
        "version": "1.2.0",
        "status": "published",
        "builder_id": 45231,
        "builder": {
            "id": 45231,
            "name": "Ariel",
            "avatar_url": "https://www.workato.com/assets/avatars/ariel.png"
        },
        "description": "Sales automation starter package.",
        "release_notes": "Adds the invoice sync recipe and fixes a connection timeout.",
        "created_at": "2026-07-10T09:15:32.000-07:00",
        "project_handles": ["sales-automation"],
        "content": {
            "counters": {
                "recipe": 6
            },
            "connectors": [
                "salesforce",
                "netsuite"
            ]
        },
        "package": {
            "id": "1d2e3f4a-5b6c-4d7e-8f90-a1b2c3d4e5f6",
            "name": "Sales automation",
            "description": "Recipes and connections for sales automation."
        },
        "projects": [
            {
                "id": 7801234,
                "name": "Sales automation",
                "folder_id": 27180380
            }
        ],
        "installations": {
            "direct": 12,
            "private_library": 4,
            "sharing_link": 1
        },
        "private_library_publication": {
            "id": "4d5e6f7a-8b9c-4d0e-8f1a-2b3c4d5e6f7a",
            "card_description": "A starter package for sales automation.",
            "version": {
                "id": "9f8c2b1e-4a6d-4c2f-9e3a-7b5d1c0a8f21",
                "version": "1.2.0"
            }
        },
        "review": {
            "id": "3c4d5e6f-7a8b-4c9d-8e0f-1a2b3c4d5e6f",
            "status": "approved",
            "comments": "Approved for distribution.",
            "updated_at": "2026-07-16T11:02:10.000-07:00",
            "author": {
                "id": 45301,
                "name": "Bola",
                "avatar_url": "https://www.workato.com/assets/avatars/bola.png"
            }
        }
    }
}

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.

NameTypeDescription
filefile
required		The package .zip file. Maximum size is 100 MB.
versionstring
optional		The version label for the first version. Defaults to v1.0.
descriptionstring
optional		The package's description.
release_notesstring
optional		The first version's release notes.
Sample request ​
shell
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.'
Response ​

The response returns the new draft's ID and a link to poll its status. Use Get version creation status to monitor the import.

json
{
    "data": {
        "version_draft_id": 1576,
        "link": "/api/xchange/versions/1576/version_draft"
    }
}

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

REQUIRED VERSION

version is required for this endpoint. A missing version returns a 400 error before the draft is created. An inaccessible or unknown package_id returns a 404 error.

URL parameters ​

NameTypeDescription
package_idstring
required		The UUID of the package to add the version to.

Request body ​

Send the request as multipart/form-data.

NameTypeDescription
filefile
required		The package .zip file. Maximum size is 100 MB.
versionstring
required		The version label, for example 1.3.0.
descriptionstring
optional		The version's description.
release_notesstring
optional		The version's release notes.
Sample request ​
shell
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.'
Response ​

On success, the response returns the same shape as Import a new package from a .zip. A missing version returns a 400 error instead:

json
{
    "errors": [
        {
            "code": 400,
            "title": "A version is required"
        }
    ]
}

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

DRAFT OWNERSHIP

A draft is scoped to the caller's environment and builder. A draft that isn't owned by the caller in the current environment returns a 404 error.

URL parameters ​

NameTypeDescription
draft_idinteger
required		The version_draft_id returned by the import endpoint.
Sample request ​
shell
curl  -X GET 'https://YOUR_DATA_CENTER/api/xchange/versions/:draft_id/version_draft' \
      -H 'Authorization: Bearer <api_token>'
Response ​

error_message is populated only when status is failed.

json
{
    "data": {
        "version_draft_id": 1576,
        "status": "completed",
        "error_message": null,
        "package_id": "01a086c1-ae0a-7057-b66b-ee4d6b66467c",
        "version_id": "01a0b04e-e2d4-7694-855a-94aa08a4071e"
    }
}

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 ​

NameTypeDescription
version_idstring
required		The UUID of the version to export.
Sample request ​
shell
curl  -X GET 'https://YOUR_DATA_CENTER/api/xchange/packages/versions/:version_id/export' \
      -H 'Authorization: Bearer <api_token>'
Response ​
json
{
    "data": {
        "version_id": "01a086d3-de39-7e8a-85c2-35437eed7de4",
        "download_url": "https://file-storage.workato.com/sharing/files?sign=eyJ0eXAiOiJKV1QiLCJhbGciOiJFUzI1NiJ9...<truncated>"
    }
}

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

SELF-REVIEW RESTRICTION

Builders can't approve or reject their own package versions unless auto-approval is enabled for the hub. A self-review attempt returns a 404 error.

URL parameters ​

NameTypeDescription
version_idstring
required		The UUID of the package version to approve.

Payload ​

NameTypeDescription
commentsstring
required		Review comments to record with the approval.

Sample request ​

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

json
{
    "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": 7801234,
                "name": "Sales automation",
                "folder_id": 27180380
            }
        ],
        "installations": {
            "direct": 12,
            "private_library": 4,
            "sharing_link": 1
        },
        "review": {
            "id": "3c4d5e6f-7a8b-4c9d-8e0f-1a2b3c4d5e6f",
            "status": "approved",
            "comments": "Approved for distribution.",
            "updated_at": "2026-07-16T11:02:10.000-07:00",
            "author": {
                "id": 45301,
                "name": "Bola",
                "avatar_url": "https://www.workato.com/assets/avatars/bola.png"
            }
        },
        "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

SELF-REVIEW RESTRICTION

Builders can't approve or reject their own package versions unless auto-approval is enabled for the hub. A self-review attempt returns a 404 error.

URL parameters ​

NameTypeDescription
version_idstring
required		The UUID of the package version to reject.

Payload ​

NameTypeDescription
commentsstring
required		Review comments to record with the rejection.

Sample request ​

shell
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 ​

NameTypeDescription
version_idstring
required		The UUID of the version to reset.
Sample request ​
shell
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 ​

NameTypeDescription
version_idstring
required		The UUID of the version.
review_idstring
required		The ID of the review to update.

Payload ​

NameTypeDescription
commentsstring
required		The updated review comments.
Sample request ​
shell
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 ​

NameTypeDescription
package_idstring
required		The UUID of the package.
version_idstring
required		The UUID of the version to publish.

Payload ​

NameTypeDescription
card_descriptionstring
optional		The description shown on the package's private library card.
Sample request ​
shell
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."
         }'
Response ​

The response returns the full version, including a private_library_publication object.

json
{
    "data": {
        "id": "9f8c2b1e-4a6d-4c2f-9e3a-7b5d1c0a8f21",
        "version": "1.2.0",
        "status": "published",
        "builder_id": 45231,
        "builder": {
            "id": 45231,
            "name": "Ariel",
            "avatar_url": "https://www.workato.com/assets/avatars/ariel.png"
        },
        "description": "Sales automation starter package.",
        "release_notes": "- New: Invoice sync recipe.\n- Improved: Connection error messages.\n- Fixed: Timeout on large syncs.",
        "created_at": "2026-07-10T09:15:32.000-07:00",
        "project_handles": ["sales-automation"],
        "content": {
            "counters": {
                "recipe": 6
            },
            "connectors": [
                "salesforce",
                "netsuite"
            ]
        },
        "package": {
            "id": "1d2e3f4a-5b6c-4d7e-8f90-a1b2c3d4e5f6",
            "name": "Sales automation",
            "description": "Recipes and connections for sales automation."
        },
        "projects": [
            {
                "id": 7801234,
                "name": "Sales automation",
                "folder_id": 27180380
            }
        ],
        "installations": {
            "direct": 12,
            "private_library": 4,
            "sharing_link": 1
        },
        "private_library_publication": {
            "id": "4d5e6f7a-8b9c-4d0e-8f1a-2b3c4d5e6f7a",
            "card_description": "A starter package for sales automation.",
            "version": {
                "id": "9f8c2b1e-4a6d-4c2f-9e3a-7b5d1c0a8f21",
                "version": "1.2.0"
            }
        },
        "review": {
            "id": "3c4d5e6f-7a8b-4c9d-8e0f-1a2b3c4d5e6f",
            "status": "approved",
            "comments": "Approved for distribution.",
            "updated_at": "2026-07-16T11:02:10.000-07:00",
            "author": {
                "id": 45301,
                "name": "Bola",
                "avatar_url": "https://www.workato.com/assets/avatars/bola.png"
            }
        }
    }
}

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 ​

NameTypeDescription
package_idstring
required		The UUID of the package.
version_idstring
required		The UUID of the published version.
Sample request ​
shell
curl  -X PUT 'https://YOUR_DATA_CENTER/api/xchange/packages/:package_id/versions/:version_id/unpublish' \
      -H 'Authorization: Bearer <api_token>'
Response ​

The response returns the full version with status reverted to approved and private_library_publication removed.

json
{
    "data": {
        "id": "9f8c2b1e-4a6d-4c2f-9e3a-7b5d1c0a8f21",
        "version": "1.2.0",
        "status": "approved",
        "builder_id": 45231,
        "builder": {
            "id": 45231,
            "name": "Ariel",
            "avatar_url": "https://www.workato.com/assets/avatars/ariel.png"
        },
        "description": "Sales automation starter package.",
        "release_notes": "- New: Invoice sync recipe.\n- Improved: Connection error messages.\n- Fixed: Timeout on large syncs.",
        "created_at": "2026-07-10T09:15:32.000-07:00",
        "project_handles": ["sales-automation"],
        "content": {
            "counters": {
                "recipe": 6
            },
            "connectors": [
                "salesforce",
                "netsuite"
            ]
        },
        "package": {
            "id": "1d2e3f4a-5b6c-4d7e-8f90-a1b2c3d4e5f6",
            "name": "Sales automation",
            "description": "Recipes and connections for sales automation."
        },
        "projects": [
            {
                "id": 7801234,
                "name": "Sales automation",
                "folder_id": 27180380
            }
        ],
        "installations": {
            "direct": 12,
            "private_library": 4,
            "sharing_link": 1
        },
        "review": {
            "id": "3c4d5e6f-7a8b-4c9d-8e0f-1a2b3c4d5e6f",
            "status": "approved",
            "comments": "Approved for distribution.",
            "updated_at": "2026-07-16T11:02:10.000-07:00",
            "author": {
                "id": 45301,
                "name": "Bola",
                "avatar_url": "https://www.workato.com/assets/avatars/bola.png"
            }
        }
    }
}

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 ​

NameTypeDescription
package_idstring
required		The UUID of the package.

Query parameters ​

NameTypeDescription
installation_statusstring
optional		Filters consumers by installation status. Accepted values: not_installed, installed.
version_idstring
optional		The UUID of the package version. Required when installation_status is set to installed.
textstring
optional		Searches consumers by name or external ID.
page[number]number
optional		Page number.
page[size]number
optional		Number of items per page. Maximum is 500.
Sample request ​

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

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

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

NameTypeDescription
version_idstring
required		The UUID of the package version to distribute.
environment_idsarray of integers
required		The IDs of the target environments.
Sample request ​

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

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

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

NameTypeDescription
package_idstring
optional		The UUID of a package. Omit this parameter to list batches across all packages.
version_idstring
optional		The UUID of a package version.
fromtimestamp
optional		Returns batches created after this ISO 8601 timestamp.
totimestamp
optional		Returns batches created before this ISO 8601 timestamp.
statusstring
optional		Filters batches by status. Accepted values: pending, in_progress, completed.
activeboolean
optional		Set to true to return only pending and in_progress batches.
page[number]number
optional		Page number.
page[size]number
optional		Number of items per page.
Sample request ​

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

shell
curl  -X GET 'https://YOUR_DATA_CENTER/api/xchange/distributions?version_id=:version_id&active=true' \
      -H 'Authorization: Bearer <api_token>'
Response ​
json
{
    "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 ​

NameTypeDescription
idstring
required		The UUID of the distribution batch.

Query parameters ​

NameTypeDescription
include_detailsboolean
optional		Set to true to include the per-target distribution details in the response.
page[number]number
optional		Page number for the details list. Only applies when include_details is set to true.
page[size]number
optional		Number of details per page. Only applies when include_details is set to true.
Sample request ​

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

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

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

NameTypeDescription
idstring
required		The UUID of the distribution batch.
Sample request ​
shell
curl  -X POST 'https://YOUR_DATA_CENTER/api/xchange/distributions/:id/retry_failed' \
      -H 'Authorization: Bearer <api_token>'
Response ​
json
{
    "data": {
        "id": "6b7c8d9e-0f1a-4b2c-9d3e-4f5a6b7c8d9e"
    }
}

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

Lists a package's sharing links.

GET https://YOUR_DATA_CENTER/api/xchange/packages/:package_id/sharing/links
NameTypeDescription
package_idstring
required		The UUID of the package.
NameTypeDescription
statusstring
optional		Filters links by status. Accepted values: active, inactive.
created_bynumber
optional		The numeric user ID of the link creator.
page[number]number
optional		Page number.
page[size]number
optional		Number of items per page.
shell
curl  -X GET 'https://YOUR_DATA_CENTER/api/xchange/packages/:package_id/sharing/links?status=active' \
      -H 'Authorization: Bearer <api_token>'

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

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

PUBLIC VS. WORKSPACE LINKS

name is required for public links and rejected for workspace links. workspace_ids is required for workspace links, up to a maximum of 200, and rejected for public links.

NameTypeDescription
package_idstring
required		The UUID of the package.
NameTypeDescription
kindstring
required		The type of link to create. Accepted values: public, workspace.
namestring
required for public links		A name for the public link.
workspace_idsarray of integers
required for workspace links		The workspace IDs to create links for. Maximum 200.
shell
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"
         }'

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
NameTypeDescription
package_idstring
required		The UUID of the package.
link_idstring
required		The ID of the sharing link.
shell
curl  -X POST 'https://YOUR_DATA_CENTER/api/xchange/packages/:package_id/sharing/links/:link_id/activate' \
      -H 'Authorization: Bearer <api_token>'

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
NameTypeDescription
package_idstring
required		The UUID of the package.
link_idstring
required		The ID of the sharing link.
shell
curl  -X POST 'https://YOUR_DATA_CENTER/api/xchange/packages/:package_id/sharing/links/:link_id/deactivate' \
      -H 'Authorization: Bearer <api_token>'

Permanently deletes a sharing link.

DELETE https://YOUR_DATA_CENTER/api/xchange/packages/:package_id/sharing/links/:link_id
NameTypeDescription
package_idstring
required		The UUID of the package.
link_idstring
required		The ID of the sharing link to delete.
shell
curl  -X DELETE 'https://YOUR_DATA_CENTER/api/xchange/packages/:package_id/sharing/links/:link_id' \
      -H 'Authorization: Bearer <api_token>'

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
NameTypeDescription
package_idstring
required		The UUID of the package.
version_idstring
required		The UUID of the version to set as the shared-link version.
shell
curl  -X PUT 'https://YOUR_DATA_CENTER/api/xchange/packages/:package_id/versions/:version_id/share' \
      -H 'Authorization: Bearer <api_token>'

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

ACTIVE LINKS REMAIN

Active sharing links remain in place after you clear the shared-link version. Consumer-side link resolution returns a 404 error until you set a new shared-link version. Passing a version_id that isn't the current shared-link version also returns a 404 error.

NameTypeDescription
package_idstring
required		The UUID of the package.
version_idstring
required		The UUID of the current shared-link version.
shell
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 ​

NameTypeDescription
package_idstring
required		The UUID of the package.

Query parameters ​

NameTypeDescription
version_idstring
optional		Filters the by_version breakdown to a single version. Doesn't affect summary.
page[number]number
optional		Page number for the by_version breakdown.
page[size]number
optional		Number of items per page for the by_version breakdown.
Sample request ​
shell
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 ​

NameTypeDescription
package_idstring
required		The UUID of the package.

Query parameters ​

NameTypeDescription
version_idstring
optional		Filters installations by version.
customer_idsarray of integers
optional		Filters installations by consumer workspace ID. Omit this parameter to return all installations. An explicit empty array returns an empty page.
page[number]number
optional		Page number.
page[size]number
optional		Number of items per page.
Sample request ​
shell
curl  -X GET 'https://YOUR_DATA_CENTER/api/xchange/packages/:package_id/installations?version_id=:version_id' \
      -H 'Authorization: Bearer <api_token>'

Last updated: