CatalogedApiVersion Metadata Type in SFDX

Architectural Overview#

Enterprise APIs evolve through major and minor versions (v1, v2) as request payloads and endpoints change. Within the Salesforce API Catalog, the CatalogedApiVersion metadata type represents a specific version of a parent CatalogedApi asset.

Architecturally, CatalogedApiVersion acts as the bridge between the high-level API catalog entry (CatalogedApi), its underlying OpenAPI or RAML specification artifact (CatalogedApiArtifactVersionInfo), and the generated Salesforce ExternalServiceRegistration that exposes invocable actions to Flow, ApexClass, and Agentforce.

Directory Location and File Suffix#

In Salesforce DX source format, CatalogedApiVersion components are stored in the catalogedApiVersions directory.

Key Metadata Fields#

The following table lists the key fields on CatalogedApiVersion as of API version 68.0 (Winter ’27):

Declarative Metadata Example#

The following example defines version v1 of the ERP_Order_Status_API cataloged API:

<?xml version="1.0" encoding="UTF-8"?>
<CatalogedApiVersion xmlns="http://soap.sforce.com/2006/04/metadata">
    <apiVersion>v1</apiVersion>
    <catalogedApi>ERP_Order_Status_API</catalogedApi>
    <description>Initial production version of the ERP Order Status REST API supporting order lookup by number.</description>
    <masterLabel>ERP Order Status System API v1</masterLabel>
    <status>Active</status>
</CatalogedApiVersion>

Package Manifest (package.xml)#

<?xml version="1.0" encoding="UTF-8"?>
<Package xmlns="http://soap.sforce.com/2006/04/metadata">
    <types>
        <members>ERP_Order_Status_API</members>
        <name>CatalogedApi</name>
    </types>
    <types>
        <members>ERP_Order_Status_API_v1</members>
        <name>CatalogedApiVersion</name>
    </types>
    <version>68.0</version>
</Package>

Tooling API Queries and SFDX CLI Commands#

Use the Salesforce CLI (sf) to retrieve and deploy CatalogedApiVersion metadata:

# Retrieve all CatalogedApiVersion components
sf project retrieve start --metadata CatalogedApiVersion

# Deploy a specific CatalogedApiVersion alongside its parent CatalogedApi
sf project deploy start --metadata CatalogedApi:ERP_Order_Status_API,CatalogedApiVersion:ERP_Order_Status_API_v1

You can also query CatalogedApiVersion via the Tooling API (sf data query --use-tooling-api):

SELECT Id, DeveloperName, MasterLabel, ApiVersion, Status
FROM CatalogedApiVersion
ORDER BY DeveloperName ASC

Architect Best Practices and Gotchas#

• Parent-Child Deployment Integrity: Always include the parent CatalogedApi and child CatalogedApiArtifactVersionInfo in the same deployment package when promoting a new CatalogedApiVersion across sandboxes.
• Lifecycle Hygiene: Mark older CatalogedApiVersion entries as deprecated once all dependent Flows and Apex classes have been cut over to the new version, before attempting destructive removal.

Frequently asked questions

What is the relationship between CatalogedApi and CatalogedApiVersion?

CatalogedApi represents the top-level API entry in the Salesforce API Catalog, while CatalogedApiVersion represents a specific semantic version (such as v1 or v2) of that API.

Why should architects maintain multiple CatalogedApiVersion records?

Maintaining separate CatalogedApiVersion records allows existing Flows and Agentforce actions to continue calling v1 of an external API while new automations are built and tested against v2.

Where are CatalogedApiVersion files stored in an SFDX project?

They are stored in force-app/main/default/catalogedApiVersions/ with the file extension .catalogedApiVersion-meta.xml.

What happens if the parent CatalogedApi is missing during deployment?

Deploying a CatalogedApiVersion without its referenced parent CatalogedApi in the target org or deployment manifest fails with a missing dependency error.