CatalogedApiArtifactVersionInfo Metadata Guide

Architectural Overview#

Within the Salesforce API Catalog architecture, an API version (CatalogedApiVersion) is backed by one or more concrete specification artifacts—such as an OpenAPI 3.0 JSON/YAML document or a MuleSoft Exchange FAT-RAML archive. The CatalogedApiArtifactVersionInfo metadata type captures the exact artifact version, classifier, and specification payload link for a cataloged API version.

By tracking CatalogedApiArtifactVersionInfo as distinct metadata, Salesforce can detect when an upstream specification artifact in MuleSoft Anypoint Exchange has been patched or re-published, enabling controlled schema updates for downstream External Services, Flow callouts, and Agentforce actions.

Directory Location and File Suffix#

In Salesforce DX projects, CatalogedApiArtifactVersionInfo files are stored in the catalogedApiArtifactVersionInfos directory.

Key Metadata Fields#

The following table summarizes the XML fields of CatalogedApiArtifactVersionInfo in API version 68.0 (Winter ’27):

Declarative Metadata Example#

The following metadata file links an OpenAPI 3.0 specification artifact (1.2.0) to its parent ERP_Order_Status_API_v1 version record.

<?xml version="1.0" encoding="UTF-8"?>
<CatalogedApiArtifactVersionInfo xmlns="http://soap.sforce.com/2006/04/metadata">
    <artifactId>erp-order-status-system-api</artifactId>
    <artifactVersion>1.2.0</artifactVersion>
    <catalogedApiVersion>ERP_Order_Status_API_v1</catalogedApiVersion>
    <classifier>oas3</classifier>
    <mainFile>erp-order-status-api.yaml</mainFile>
    <masterLabel>ERP Order Status OAS 1.2.0</masterLabel>
    <packaging>zip</packaging>
</CatalogedApiArtifactVersionInfo>

Package Manifest (package.xml)#

Always include the parent CatalogedApi and CatalogedApiVersion alongside CatalogedApiArtifactVersionInfo:

<?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>
    <types>
        <members>ERP_Order_Status_OAS_1_2_0</members>
        <name>CatalogedApiArtifactVersionInfo</name>
    </types>
    <version>68.0</version>
</Package>

Tooling API Queries and SFDX CLI Commands#

Retrieve and deploy artifact version metadata using the Salesforce CLI:

# Retrieve all CatalogedApiArtifactVersionInfo metadata
sf project retrieve start --metadata CatalogedApiArtifactVersionInfo

# Deploy the complete API Catalog chain together
sf project deploy start --metadata CatalogedApi,CatalogedApiVersion,CatalogedApiArtifactVersionInfo

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

SELECT Id, DeveloperName, MasterLabel, ArtifactId, ArtifactVersion, Classifier, MainFile
FROM CatalogedApiArtifactVersionInfo
ORDER BY ArtifactId ASC, ArtifactVersion DESC

Architect Best Practices and Gotchas#

• Strict Parent Ordering: In CI/CD deployments, CatalogedApiArtifactVersionInfo has a hard foreign-key dependency on CatalogedApiVersion. Never deploy artifact version info files in a separate job prior to their parent API version.
• Immutable Artifact Versions: Treat each artifactVersion (1.2.0, 1.2.1) as immutable once promoted to production so audit trails clearly reflect which OpenAPI contract version backed a given release.

Frequently asked questions

What is the purpose of CatalogedApiArtifactVersionInfo in Salesforce API Catalog?

It records the specific specification artifact details, such as the OpenAPI YAML or JSON file reference, artifact version, and classification, associated with a parent CatalogedApiVersion.

Can CatalogedApiArtifactVersionInfo be deployed without CatalogedApiVersion?

No, CatalogedApiArtifactVersionInfo depends on its parent CatalogedApiVersion and CatalogedApi records. Deploying it in isolation fails with a missing parent reference error.

Why does Salesforce separate CatalogedApiVersion from CatalogedApiArtifactVersionInfo?

A single API version in an enterprise catalog like MuleSoft Exchange can have multiple associated artifacts, such as an OAS 3.0 specification, RAML fragments, or metadata descriptor files.

How should architects handle CatalogedApiArtifactVersionInfo in Git repositories?

Retrieve and commit CatalogedApiArtifactVersionInfo alongside CatalogedApi and CatalogedApiVersion whenever an API specification is synced or upgraded in the API Catalog.