Try Serpent Free
← Salesforce DevOps Glossary

Metadata API

Salesforce's API for retrieving and deploying org configuration, the foundation nearly every DevOps tool is built on.

Definition

The Metadata API is Salesforce's SOAP-based API for retrieving, deploying, creating, and deleting the configuration (metadata) that defines an org, things like custom objects, fields, flows, Apex classes, and layouts, as opposed to the records (data) those objects hold. It's the foundation nearly every Salesforce DevOps tool is built on: Salesforce CLI, change sets, and third-party release tools all ultimately call Metadata API operations to move configuration between orgs.

Deployments through Metadata API can be validated (check-only) before running for real, and support destructive changes via a dedicated manifest kept separate from what's being deployed. Because it's XML-manifest driven, deployments require an accurate package.xml listing every component type and name included.

A bad or incomplete manifest is one of the most common causes of failed Salesforce deployments, since anything left off the list is simply skipped rather than flagged. Our Salesforce DevOps guide covers how Metadata API deployments fit into a full release pipeline.

In practice

How it works in Serpent

Serpent uses standard Metadata API calls for every deployment, with zero footprint installed in your org, and builds the package manifest automatically from the components a task actually touched, so there's no hand-maintained package.xml to keep in sync. Org comparison and sync features read metadata state across sandboxes and production to flag drift before a deployment runs, catching mismatches Metadata API alone won't warn you about. See org management in Serpent for how metadata comparison works across your environments.

Git integration settings in Serpent
Common questions

Metadata API, answered

What's the difference between the Metadata API and the standard Salesforce API?
The standard REST or SOAP API reads and writes records, the data inside your objects. The Metadata API reads and writes the configuration that defines those objects, like fields, flows, and Apex classes.
Can I validate a Metadata API deployment without actually deploying it?
Yes, check-only deployments run all the same validation, including Apex tests, without committing any changes to the target org. It's the standard way to catch failures before a real deployment.
Why did my Metadata API deployment succeed but leave a component out?
Almost always an incomplete package.xml. Metadata API only touches what's listed in the manifest, so a component that isn't listed is silently skipped rather than flagged as an error.

Start free. No credit card, no install, no commitment.

Set up in under 15 minutes. No DevOps hire needed.

Curious about faster shipping before you dive in? Let's talk

Commitment free!