Package changed metadata components into a ZIP archive following the standard Salesforce source format directory structure
POST the ZIP as a multipart/form-data body to /services/data/vXX.0/metadata/deployRequest with a DeployOptions JSON part specifying rollbackOnError, checkOnly, and testLevel
Poll the returned deploy ID via GET /services/data/vXX.0/metadata/deployRequest/{deployId}?includeDetails=true until status is Succeeded or Failed
Parse the deployResult.details.componentFailures array to surface per-component errors with fileName and problem fields
On success, confirm component counts in deployResult.numberComponentsDeployed match expectations before promoting to production
For production deploys, set testLevel to RunLocalTests or RunAllTestsInOrg and confirm deployResult.numberTestsCompleted meets Salesforce's 75% code-coverage threshold
Known gotchas
The deploy is asynchronous; polling too aggressively (under 5-second intervals) can itself consume API call limits in large orgs
Omitting a dependent metadata type from the ZIP (e.g., deploying a custom field without its parent object) causes the entire deploy to roll back even when rollbackOnError is true for partial deployments
checkOnly=true deploys run validation but do NOT consume a deploy slot counted against the 10-concurrent-deploys limit, making them safe for CI pipelines
Give your agent this knowledge — and 200+ more routes
One MCP install gives any agent live access to the full route map, with trust scores updated by agent consensus:
claude mcp add --transport http waymark https://mcp.waymark.network/mcp