Master Data API provides a structured way to store, retrieve, and manage data. It is organized into two categories:

• Data Plane: Manages records, enabling tasks such as searching and accessing documents.
• Control Plane: Defines the structure of records and access configurations.

The Data Plane stores and retrieves documents. Designed for high-volume operations, the Data Plane ensures quick and reliable data access for store operations.

The /documents endpoint is used to store and retrieve individual Documents. To retrieve a Document, you must provide the id value of the desired document, which serves as the unique identifier of the Document.

When the id of a document is unknown, you can use the following APIs to locate it using Searchable fields or Indexes:

• /search: Retrieves documents using Index fields. Learn more about Indices in Components.
• /scroll: Handles large datasets, enabling bulk document retrieval through Searchable fields.

Searchable fields are configured to work with the /search and /scroll endpoints. In Master Data V1, they are defined using the Is Filter property. In Master Data V2, they use the v-indexed property.

The Control Plane manages the structure and behavior of the Data Plane. It enables developers to configure data validation, searchable fields and triggers within Data Entities. Control Plane operations are less frequent but crucial for defining data structures.

Master Data V1 does not provide a Control Plane API. All configurations are handled via the VTEX Admin through the Dynamic Storage at Store Settings > Storefront > Master Data > ⚙ > Data structure (https://{{account}}.ds.vtexcrm.com.br).

Master Data V2 has the /schema and /indices endpoints, allowing for the creation and management of JSON Schemas for Data Entities. These schemas define the structure of stored data and directly influence how the Data Plane processes and validates documents.

JSON Schemas are exclusive to Master Data V2.

The table below summarizes the available endpoints, their categories, descriptions, and supported versions.

Endpoint	Category	Description	V1 Documentation	V2 Documentation
/schemas	Control Plane	Creates and manages schemas for a Data Entity. The use of schemas enables searches with custom fields and to add rules when managing documents. Learn more in Schema Lifecycle.	N/A	Get schemas Get schema by name Save schema by name Delete schema by name
/indices	Control Plane	Manages indices for fast Document access via fields other than id. Learn more in Components.	N/A	Get indices Put indices Get index by name Delete index by name
/documents	Data Plane	Manages individual Documents using their id.	Create new document Create document with custom ID or Update entire document Create or update partial document Get document Update entire document Update partial document Delete document	Create new document Create partial document Get document Create document with custom ID or Update entire document Update partial document Delete document
/search	Data Plane	Retrieves documents based on parameters like schemas and indexed fields.	Search documents	Search documents
/scroll	Data Plane	Retrieves large amount of Documents.	Scroll documents	Scroll documents