{ "openapi": "3.0.0", "info": { "title": "Master Data API - v2", "description": ">ℹ️ Master Data v2 is not compatible with data entities from previous versions, such as CL and AD.\r\n\r\n[Master Data](https://developers.vtex.com/docs/guides/master-data-introduction) is a secure, fast, scalable, and extensible solution that allows users to create their own entities, store data, and retrieve information directly from the storefront or external integrations.\r\n\r\nSeveral internal VTEX modules use Master Data as a data repository, including Orders and Sales App. \r\n\r\nThere are two main ways to use Master Data:\r\n\r\n- [Directly from the storefront](#directly-from-the-storefront)\r\n- [With an external integration](#external-integrations)\r\n\r\n## Directly from the storefront\r\n\r\nWhen using Master Data within the storefront, consider the following:\r\n\r\n- Use the storefront host to query or store information to avoid issues related to Cross-origin resource sharing (CORS).\r\n- Use the relative path to avoid CORS issues.\r\n- Configure the JSON Schema of the Data Entity to specify which information should be public and which should not be.\r\n- Avoid creating query loops to prevent potential throttling issues or APIs being disabled due to security protection measures.\r\n- Never add authentication keys, such as `X-VTEX-API-AppKey` or `X-VTEX-API-AppToken`, via JavaScript as this could pose security risks.\r\n\r\n## External integrations\r\n\r\nWhen using Master Data to store data from an external integration, such as client data from another service, consider the following:\r\n\r\n- Use the host `{{accountName}}.vtexcommercestable.com.br`.\r\n- Use the authentication keys (`X-VTEX-API-AppKey` ou `X-VTEX-API-AppToken`).\r\n\r\n## Common parameters\r\n\r\n| Name | Description |\r\n| -------- | -------- |\r\n| `accountName` | Account name in VTEX License Manager. |\r\n| `name` | Data Entity name. |\r\n| `schema` | JSON Schema of a Data Entity. |\r\n| `id` | Identifier of a document. |\r\n| `X-VTEX-API-AppKey` | appKey. |\r\n| `X-VTEX-API-AppToken` | appToken. | ", "contact": {}, "version": "1.0" }, "servers": [ { "url": "https://{accountName}.{environment}.com.br", "description": "VTEX server URL.", "variables": { "accountName": { "description": "Name of the VTEX account. Used as part of the URL", "default": "apiexamples" }, "environment": { "description": "Environment to use. Used as part of the URL.", "enum": [ "vtexcommercestable" ], "default": "vtexcommercestable" } } } ], "paths": { "/api/dataentities/{dataEntityName}/documents": { "post": { "tags": [ "Documents" ], "summary": "Create new document", "description": "Creates a new document with an ID automatically generated by VTEX, corresponding to a new or existing data entity. If an unexisting `dataEntityName` is informed in the path, this endpoint will create the data entity as well as the new document. For example, you can create a new customer profile or address.\r\n\r\n>ℹ️ You can use this request to create documents for any data entity. Because of this, you are not restricted to using the fields exemplified below in your requests. However you should be aware of the fields allowed or required for each document you wish to create.\r\n\r\n> To create a document with a custom ID, refer to the [Create document with custom ID](https://developers.vtex.com/docs/api-reference/master-data-api-v2#put-/api/dataentities/-dataEntityName-/documents/-id-) endpoint.\r\n\r\n## Permissions\r\n\r\nAny user or [API key](https://developers.vtex.com/docs/guides/api-authentication-using-api-keys) must have at least one of the appropriate [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3) to be able to successfully run this request. Otherwise they will receive a status code `403` error. These are the applicable resources for this endpoint:\r\n\r\n| **Product** | **Category** | **Resource** |\r\n| --------------- | ----------------- | ----------------- |\r\n| Dynamic Storage | Dynamic storage generic resources | **Insert or update document (not remove)** |\r\n| Dynamic Storage | Dynamic storage generic resources | **Full access to all documents** |\r\n| Dynamic Storage | Dynamic storage generic resources | **Master Data administrator** |\r\n\r\nThere are no applicable [predefined roles](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy) for this resource list. You must [create a custom role](https://help.vtex.com/en/tutorial/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) and add at least one of the resources above in order to use this endpoint.To learn more about machine authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication).\r\n\r\n>\u2757 To prevent integrations from having excessive permissions, consider the [best practices for managing API keys](https://help.vtex.com/en/tutorial/best-practices-api-keys--7b6nD1VMHa49aI5brlOvJm) when assigning License Manager roles to integrations.", "operationId": "Createnewdocument", "parameters": [ { "$ref": "#/components/parameters/Content-Type" }, { "$ref": "#/components/parameters/Accept" }, { "$ref": "#/components/parameters/dataEntityName" }, { "$ref": "#/components/parameters/_schema" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentRequest" }, "example": { "email": "clark.kent@examplemail.com", "firstName": "Clark", "lastName": "Kent", "phone": "+12025550195", "documentType": "CPF", "document": "12345678900", "isCorporate": false, "isNewsletterOptIn": false, "localeDefault": "en-US" } } }, "required": true }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateDocumentResponse" }, "example": { "Id": "Newsletter-cbfc4f67-6ea3-11ee-83ab-0a8d18f9f827", "Href": "http://cosmetics2.vtexcommercestable.com.br/api/dataentities/Newsletter/documents/cbfc4f67-6ea3-11ee-83ab-0a8d18f9f827", "DocumentId": "cbfc4f67-6ea3-11ee-83ab-0a8d18f9f827" } } } }, "202": { "description": "Accepted\n\nThe document creation has been accepted and will be processed asynchronously due to background operations.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateDocumentResponse" }, "example": { "Id": "Newsletter-cbfc4f67-6ea3-11ee-83ab-0a8d18f9f827", "Href": "http://cosmetics2.vtexcommercestable.com.br/api/dataentities/Newsletter/documents/cbfc4f67-6ea3-11ee-83ab-0a8d18f9f827", "DocumentId": "cbfc4f67-6ea3-11ee-83ab-0a8d18f9f827" } } } } }, "deprecated": false }, "patch": { "tags": [ "Documents" ], "summary": "Create partial document", "description": "This request allows you to partially update a document corresponding to a given data entity.\r\n\r\n>ℹ️ You can use this request to create documents for any given data entity. Because of this, you are not restricted to using the fields exemplified below in your requests. But you should be aware of the fields allowed or required for each document you wish to update.\r\n\r\n## Permissions\r\n\r\nAny user or [API key](https://developers.vtex.com/docs/guides/api-authentication-using-api-keys) must have at least one of the appropriate [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3) to be able to successfully run this request. Otherwise they will receive a status code `403` error. These are the applicable resources for this endpoint:\r\n\r\n| **Product** | **Category** | **Resource** |\r\n| --------------- | ----------------- | ----------------- |\r\n| Dynamic Storage | Dynamic storage generic resources | **Insert or update document (not remove)** |\r\n| Dynamic Storage | Dynamic storage generic resources | **Full access to all documents** |\r\n| Dynamic Storage | Dynamic storage generic resources | **Master Data administrator** |\r\n\r\nThere are no applicable [predefined roles](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy) for this resource list. You must [create a custom role](https://help.vtex.com/en/tutorial/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) and add at least one of the resources above in order to use this endpoint.To learn more about machine authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication).\r\n\r\n>\u2757 To prevent integrations from having excessive permissions, consider the [best practices for managing API keys](https://help.vtex.com/en/tutorial/best-practices-api-keys--7b6nD1VMHa49aI5brlOvJm) when assigning License Manager roles to integrations.", "operationId": "Createorupdatepartialdocument", "parameters": [ { "$ref": "#/components/parameters/dataEntityName" }, { "$ref": "#/components/parameters/_schema" }, { "$ref": "#/components/parameters/Content-Type" }, { "$ref": "#/components/parameters/Accept" } ], "requestBody": { "description": "JSON with the fields to be updated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentRequest" }, "example": { "phone": "+12025550195", "isNewsletterOptIn": false } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateDocumentResponse" }, "example": { "Id": "Newsletter-b818cbda-e489-11e6-94f4-0ac138d2d42e", "Href": "http://api.vtex.com/apiexamples/dataentities/Newsletter/documents/b818cbda-e489-11e6-94f4-0ac138d2d42e", "DocumentId": "b818cbda-e489-11e6-94f4-0ac138d2d42e" } } } } }, "deprecated": false } }, "/api/dataentities/{dataEntityName}/documents/{id}": { "get": { "tags": [ "Documents" ], "summary": "Get document", "description": "Retrieves a document by ID.\n\r\n\r>ℹ️ Assign the `_fields` parameter in the query string to retrieve the desired fields. If you want to return all the fields use `_fields=_all`.\r\n\r\n## Permissions\r\n\r\nAny user or [API key](https://developers.vtex.com/docs/guides/api-authentication-using-api-keys) must have at least one of the appropriate [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3) to be able to successfully run this request. Otherwise they will receive a status code `403` error. These are the applicable resources for this endpoint:\r\n\r\n| **Product** | **Category** | **Resource** |\r\n| --------------- | ----------------- | ----------------- |\r\n| Dynamic Storage | Dynamic storage generic resources | **Read only documents** |\r\n| Dynamic Storage | Dynamic storage generic resources | **Insert or update document (not remove)** |\r\n| Dynamic Storage | Dynamic storage generic resources | **Full access to all documents** |\r\n| Dynamic Storage | Dynamic storage generic resources | **Master Data administrator** |\r\n\r\nThere are no applicable [predefined roles](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy) for this resource list. You must [create a custom role](https://help.vtex.com/en/tutorial/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) and add at least one of the resources above in order to use this endpoint.To learn more about machine authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication).\r\n\r\n>\u2757 To prevent integrations from having excessive permissions, consider the [best practices for managing API keys](https://help.vtex.com/en/tutorial/best-practices-api-keys--7b6nD1VMHa49aI5brlOvJm) when assigning License Manager roles to integrations.", "operationId": "Getdocument", "parameters": [ { "$ref": "#/components/parameters/dataEntityName" }, { "$ref": "#/components/parameters/Content-Type" }, { "$ref": "#/components/parameters/Accept" }, { "$ref": "#/components/parameters/id" }, { "$ref": "#/components/parameters/_fields" }, { "$ref": "#/components/parameters/_schema" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Using_fields_all" }, "example": { "id": "b818cbda-e489-11e6-94f4-0ac138d2d42e", "accountId": "14af940d-9300-4279-9355-61d44c2ff879", "accountName": "apiexamples", "dataEntityId": "Newsletter" } } } } }, "deprecated": false }, "put": { "tags": [ "Documents" ], "summary": "Create document with custom ID or update entire document", "description": "Creates a new document with a custom ID, or updates an entire document if there is already a document with the informed ID. For example, you can update a customer profile or address.\r\n\r\n>ℹ️ You can use this request to create or update documents in any given data entity. Because of this, you are not restricted to using the fields exemplified below in your requests. But you should be aware of the fields allowed or required for each document you wish to update.\r\n\r\nA## Permissions\r\n\r\nAny user or [API key](https://developers.vtex.com/docs/guides/api-authentication-using-api-keys) must have at least one of the appropriate [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3) to be able to successfully run this request. Otherwise they will receive a status code `403` error. These are the applicable resources for this endpoint:\r\n\r\n| **Product** | **Category** | **Resource** |\r\n| --------------- | ----------------- | ----------------- |\r\n| Dynamic Storage | Dynamic storage generic resources | **Insert or update document (not remove)** |\r\n| Dynamic Storage | Dynamic storage generic resources | **Full access to all documents** |\r\n| Dynamic Storage | Dynamic storage generic resources | **Master Data administrator** |\r\n\r\nThere are no applicable [predefined roles](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy) for this resource list. You must [create a custom role](https://help.vtex.com/en/tutorial/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) and add at least one of the resources above in order to use this endpoint.To learn more about machine authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication).\r\n\r\n>\u2757 To prevent integrations from having excessive permissions, consider the [best practices for managing API keys](https://help.vtex.com/en/tutorial/best-practices-api-keys--7b6nD1VMHa49aI5brlOvJm) when assigning License Manager roles to integrations.", "operationId": "Updateentiredocument", "parameters": [ { "$ref": "#/components/parameters/dataEntityName" }, { "$ref": "#/components/parameters/_where" }, { "$ref": "#/components/parameters/_schema" }, { "$ref": "#/components/parameters/Accept" }, { "name": "id", "in": "path", "description": "ID of the document. If you inform an **unused ID**, this endpoint will create a new document with the informed custom ID, differently from the [Create new document](https://developers.vtex.com/docs/api-reference/master-data-api-v2#post-/api/dataentities/-dataEntityName-/documents) endpoint, which automatically generates the ID. If you inform an **existing ID**, this endpoint will update the entire document associated with the informed ID.", "required": true, "style": "simple", "schema": { "type": "string", "example": "Newsletter-b818cbda-e489-11e6-94f4-0ac138d2d42e" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentRequest" }, "example": { "email": "clark.kent@examplemail.com", "firstName": "Clark", "lastName": "Kent", "phone": "+12025550195", "documentType": "CPF", "document": "12345678900", "isCorporate": false, "isNewsletterOptIn": false, "localeDefault": "en-US" } } }, "required": true }, "responses": { "204": { "description": "No Content" }, "400": { "description": "Bad Request\n\nInvalid information in JSON." }, "403": { "description": "Forbidden\n\nUnauthorized access." } }, "deprecated": false }, "patch": { "tags": [ "Documents" ], "summary": "Update partial document", "description": "This request allows you to partially update a document corresponding to a given data entity. For example, you can update some fields of a customer profile or address.\r\n\r\n>ℹ️ You can use this request to update documents for any given data entity. Because of this, you are not restricted to using the fields exemplified below in your requests. But you should be aware of the fields allowed or required for each document you wish to update.\r\n\r\n## Permissions\r\n\r\nAny user or [API key](https://developers.vtex.com/docs/guides/api-authentication-using-api-keys) must have at least one of the appropriate [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3) to be able to successfully run this request. Otherwise they will receive a status code `403` error. These are the applicable resources for this endpoint:\r\n\r\n| **Product** | **Category** | **Resource** |\r\n| --------------- | ----------------- | ----------------- |\r\n| Dynamic Storage | Dynamic storage generic resources | **Insert or update document (not remove)** |\r\n| Dynamic Storage | Dynamic storage generic resources | **Full access to all documents** |\r\n| Dynamic Storage | Dynamic storage generic resources | **Master Data administrator** |\r\n\r\nThere are no applicable [predefined roles](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy) for this resource list. You must [create a custom role](https://help.vtex.com/en/tutorial/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) and add at least one of the resources above in order to use this endpoint.To learn more about machine authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication).\r\n\r\n>\u2757 To prevent integrations from having excessive permissions, consider the [best practices for managing API keys](https://help.vtex.com/en/tutorial/best-practices-api-keys--7b6nD1VMHa49aI5brlOvJm) when assigning License Manager roles to integrations.", "operationId": "Updatepartialdocument", "parameters": [ { "$ref": "#/components/parameters/dataEntityName" }, { "$ref": "#/components/parameters/_where" }, { "$ref": "#/components/parameters/_schema" }, { "$ref": "#/components/parameters/Accept" }, { "$ref": "#/components/parameters/id" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentRequest" }, "example": { "phone": "+12025550195", "isNewsletterOptIn": false } } }, "required": true }, "responses": { "204": { "description": "No Content" } }, "deprecated": false }, "delete": { "tags": [ "Documents" ], "summary": "Delete document", "description": "Deletes a document. \r\n\r\n## Permissions\r\n\r\nAny user or [API key](https://developers.vtex.com/docs/guides/api-authentication-using-api-keys) must have at least one of the appropriate [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3) to be able to successfully run this request. Otherwise they will receive a status code `403` error. These are the applicable resources for this endpoint:\r\n\r\n| **Product** | **Category** | **Resource** |\r\n| --------------- | ----------------- | ----------------- |\r\n| Dynamic Storage | Dynamic storage generic resources | **Full access to all documents** |\r\n| Dynamic Storage | Dynamic storage generic resources | **Master Data administrator** |\r\n\r\nThere are no applicable [predefined roles](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy) for this resource list. You must [create a custom role](https://help.vtex.com/en/tutorial/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) and add at least one of the resources above in order to use this endpoint.To learn more about machine authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication).\r\n\r\n>\u2757 To prevent integrations from having excessive permissions, consider the [best practices for managing API keys](https://help.vtex.com/en/tutorial/best-practices-api-keys--7b6nD1VMHa49aI5brlOvJm) when assigning License Manager roles to integrations.", "operationId": "Deletedocument", "parameters": [ { "$ref": "#/components/parameters/dataEntityName" }, { "$ref": "#/components/parameters/Content-Type" }, { "$ref": "#/components/parameters/Accept" }, { "$ref": "#/components/parameters/id" } ], "responses": { "204": { "description": "No Content" } }, "deprecated": false } }, "/api/dataentities/{dataEntityName}/delete": { "post": { "tags": [ "Bulk deletion" ], "summary": "Create bulk document deletion job", "description": "Creates an asynchronous job that deletes all documents in a data entity that match a given filter.\r\n\r\n> ⚠️ This feature is in closed beta, meaning only specific customers can access it now. If you want to implement it in the future, please contact [our Support](https://support.vtex.com/hc/en-us/).\r\n\r\nThis request does not delete any documents by itself. It creates a job and returns a `JobId`, which you must use to track the job with the [Get bulk document deletion job status](https://developers.vtex.com/docs/api-reference/master-data-api-v2#get-/api/dataentities/-dataEntityName-/delete/jobs/-jobId-) endpoint.\r\n\r\n>❗ This action cannot be undone. Deleted documents will be permanently lost.\r\n\r\n## Filter rules\r\n\r\n- The `filter` field is required.\r\n- Wildcards are not allowed. For example, `email = *@gmail.com` is rejected.\r\n- Every field used in the filter must be indexed. Internal fields, such as `createdIn`, are already indexed.\r\n- Filtering on a custom field also requires sending the `schema` that declares it as indexed in the request body. A custom field is declared as indexed for filtering in the `v-indexed` array of its [schema](https://developers.vtex.com/docs/api-reference/master-data-api-v2#put-/api/dataentities/-dataEntityName-/schemas/-schemaName-).\r\n- Only one active job per account and data entity is allowed at a time.\r\n\r\n>ℹ️ Confirm how many documents match your filter before deleting them, so you can compare that number with the `DocumentsDeleted` value returned by the job status endpoint.\r\n\r\n## Errors\r\n\r\n`{field}`, `{schema}`, and `{entity}` are placeholders for values from your request, and any quotation marks around them are part of the message returned by the API. Messages marked as truncated continue beyond the text shown.\r\n\r\n| Status code | Message or cause | What to do |\r\n| - | - | - |\r\n| `400` | `The 'filter' field is required.` | Send the `filter` field in the body. |\r\n| `400` | `Wildcard filters are not allowed for bulk delete.` | Rewrite the filter using exact or range conditions over indexed fields. |\r\n| `400` | `The field '{field}' is not an internal indexed field, so the 'schema' that declares it as indexed must be provided.` | Send the `schema` field in the body. |\r\n| `400` | `The field '{field}' is not indexed in the schema '{schema}'...` (truncated) | Mark the field as indexed in the schema and wait for reindexing, or filter on an already indexed field. |\r\n| `400` | `Invalid data entity name.` | Correct the data entity name in the URL. Invalid characters are rejected. |\r\n| `400` | The request body is empty or is not valid JSON. This response uses the standard validation error format and does not include the `Message` field. | Send a valid JSON body. |\r\n| `409` | `Bulk deletion job creation failed for entity {entity}`, returned when a job is already `InProgress` for this account and data entity. | Track the existing job and resend once its status is `Success` or `Failed`. If a job appears stuck, the data entity automatically accepts new jobs after 12 hours. |\r\n| `415` | The `Content-Type: application/json` header is missing or the media type is not supported. | Send the `Content-Type: application/json` header. |\r\n| `5xx` | Transient infrastructure failure during job creation. | No residual state is left behind, so you can resend the request. |\r\n\r\n## Permissions\r\n\r\nThis request requires a valid [user token](https://developers.vtex.com/docs/guides/api-authentication-using-user-tokens), sent in the `VtexIdclientAutCookie` header.", "parameters": [ { "$ref": "#/components/parameters/Content-Type" }, { "$ref": "#/components/parameters/dataEntityName" }, { "name": "an", "in": "query", "description": "Name of the VTEX account that owns the data entity (for example, `apiexamples`).", "required": true, "style": "form", "schema": { "type": "string", "example": "apiexamples" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkDeletionRequest" }, "examples": { "internalField": { "summary": "Filter on an internal field", "value": { "filter": "createdIn > 2026-08-16" } }, "customField": { "summary": "Filter on a custom indexed field, which requires the schema name", "value": { "filter": "number = 1337", "schema": "indexed-fields" } } } } }, "required": true }, "responses": { "202": { "description": "Accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkDeletionJobResponse" }, "example": { "JobId": "01M08C83Z5D91S3CA0A15SRNV8" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkDeletionErrorResponse" }, "examples": { "missingFilter": { "summary": "The filter field was not sent", "value": { "Message": "The 'filter' field is required." } }, "wildcardFilter": { "summary": "The filter uses a wildcard", "value": { "Message": "Wildcard filters are not allowed for bulk delete." } }, "schemaRequired": { "summary": "The filter uses a custom field and no schema was sent", "value": { "Message": "The field 'number' is not an internal indexed field, so the 'schema' that declares it as indexed must be provided." } }, "invalidDataEntityName": { "summary": "The data entity name in the URL is invalid", "value": { "Message": "Invalid data entity name." } } } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkDeletionErrorResponse" }, "example": { "Message": "Bulk deletion job creation failed for entity Newsletter" } } } }, "415": { "description": "Unsupported Media Type\n\nReturned when the JSON content type header is missing or the media type is not supported." }, "500": { "description": "Internal Server Error" } } } }, "/api/dataentities/{dataEntityName}/delete/jobs/{jobId}": { "get": { "tags": [ "Bulk deletion" ], "summary": "Get bulk document deletion job status", "description": "Retrieves the current status of a bulk document deletion job created with the [Create bulk document deletion job](https://developers.vtex.com/docs/api-reference/master-data-api-v2#post-/api/dataentities/-dataEntityName-/delete) endpoint.\r\n\r\n> ⚠️ This feature is in closed beta, meaning only specific customers can access it now. If you want to implement it in the future, please contact [our Support](https://support.vtex.com/hc/en-us/).\r\n\r\nPoll this endpoint until the job leaves the `InProgress` status.\r\n\r\nPossible `Status` values:\r\n\r\n- `InProgress`: The job is running and documents are being deleted in batches. Keep polling and do not create another job for this data entity.\r\n- `Success`: All matching documents were deleted. Compare `DocumentsDeleted` with the number of documents you expected to delete.\r\n- `Failed`: Processing stopped after exhausting internal retries. The deletion is partial, which means that documents from completed batches were already deleted. Fix the underlying cause and create a new job with the same filter to finish the deletion.\r\n\r\n## Errors\r\n\r\n| Status code | Cause | What to do |\r\n| - | - | - |\r\n| `404` | The `jobId` does not exist for this account and data entity, or the job was created more than 60 days ago. Job records are kept for 60 days after creation. | Check the `jobId`, the `an` query parameter, and the data entity in the URL. If all three are correct, the job is older than 60 days and its record is no longer available. |\r\n\r\n## Permissions\r\n\r\nThis request requires a valid [user token](https://developers.vtex.com/docs/guides/api-authentication-using-user-tokens), sent in the `VtexIdclientAutCookie` header.", "parameters": [ { "$ref": "#/components/parameters/dataEntityName" }, { "name": "jobId", "in": "path", "description": "Unique identifier of the bulk deletion job, returned by the [Create bulk document deletion job](https://developers.vtex.com/docs/api-reference/master-data-api-v2#post-/api/dataentities/-dataEntityName-/delete) endpoint (for example, `01M08C83Z5D91S3CA0A15SRNV8`).", "required": true, "style": "simple", "schema": { "type": "string", "example": "01M08C83Z5D91S3CA0A15SRNV8" } }, { "name": "an", "in": "query", "description": "Name of the VTEX account that owns the data entity (for example, `apiexamples`).", "required": true, "style": "form", "schema": { "type": "string", "example": "apiexamples" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkDeleteJobStatusResponseVO" }, "example": { "JobId": "01M08C83Z5D91S3CA0A15SRNV8", "Entity": "Newsletter", "Status": "Success", "Filter": "number < 100", "DocumentsDeleted": 19, "CreatedAt": "2026-08-07T15:48:15.4804028Z", "UpdatedAt": "2026-08-07T19:31:10.654298Z" } } } }, "404": { "description": "Not Found" } } } }, "/api/dataentities/{dataEntityName}/search": { "get": { "tags": [ "Search" ], "summary": "Search documents", "description": "Retrieves Master Data v2 documents' information, while choosing which fields will be returned and filtering documents by specific fields.\r\n\r\n> The response header `REST-Content-Range` indicates the total amount of results for that specific search. For example, it may return `resources 0-100/136108`, which indicates it has returned the first 100 results out of a total of 136108.\r\n\r\nBelow you can see some query examples and learn more about each query parameter.\n\r\n\rLearn more about [Pagination in the Master Data API](https://developers.vtex.com/docs/guides/pagination-in-the-master-data-api).\r\n\r\n>⚠️ Avoid sending too many requests with wildcards (`*`) in the search parameters or that use the `keyword` parameter. This may lead to this endpoint being temporarily blocked for your account. If this happens you will receive an error with status code `503`.\r\n\r\n## Query examples\r\n\r\n| **Query Type** | **Example** |\r\n|-|-|\r\n| **Simple filter** | `\/dataentities\/Newsletter\/search?email=my@email.com` |\r\n| **Complex filter** | `\/dataentities\/Newsletter\/search?_where=(firstName=Jon OR lastName=Smith) OR (createdIn between 2001-01-01 AND 2016-01-01)` |\r\n| **Date range** | `\/dataentities\/Newsletter\/search?_where=createdIn between 2001-01-01 AND 2016-01-01` |\r\n| **Range numeric fields** | `\/dataentities\/Newsletter\/search?_where=age between 18 AND 25` |\r\n| **Partial filter** | `\/dataentities\/Newsletter\/search?firstName=*Maria*` |\r\n| **Filter for null values** | `\/dataentities\/Newsletter\/search?_where=firstName is null` |\r\n| **Filter for non-null values** | `\/dataentities\/Newsletter\/search?_where=firstName is not null` |\r\n| **Filter for difference** | `\/dataentities\/Newsletter\/search?_where=firstName<>maria` |\r\n| **Filter greater than** | `\/dataentities\/Newsletter\/search?_where=number>5` |\r\n| **Filter less than** | `\/dataentities\/Newsletter\/search?_where=date<2001-01-01` |\r\n\r\n## Permissions\r\n\r\nAny user or [API key](https://developers.vtex.com/docs/guides/api-authentication-using-api-keys) must have at least one of the appropriate [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3) to be able to successfully run this request. Otherwise they will receive a status code `403` error. These are the applicable resources for this endpoint:\r\n\r\n| **Product** | **Category** | **Resource** |\r\n| --------------- | ----------------- | ----------------- |\r\n| Dynamic Storage | Dynamic storage generic resources | **Read only documents** |\r\n| Dynamic Storage | Dynamic storage generic resources | **Insert or update document (not remove)** |\r\n| Dynamic Storage | Dynamic storage generic resources | **Full access to all documents** |\r\n| Dynamic Storage | Dynamic storage generic resources | **Master Data administrator** |\r\n\r\nThere are no applicable [predefined roles](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy) for this resource list. You must [create a custom role](https://help.vtex.com/en/tutorial/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) and add at least one of the resources above in order to use this endpoint. To learn more about machine authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication).\r\n\r\n>\u2757 To prevent integrations from having excessive permissions, consider the [best practices for managing API keys](https://help.vtex.com/en/tutorial/best-practices-api-keys--7b6nD1VMHa49aI5brlOvJm) when assigning License Manager roles to integrations.", "operationId": "Searchdocuments", "parameters": [ { "$ref": "#/components/parameters/dataEntityName" }, { "$ref": "#/components/parameters/Content-Type" }, { "$ref": "#/components/parameters/Accept" }, { "$ref": "#/components/parameters/REST-Range" }, { "$ref": "#/components/parameters/_fields" }, { "$ref": "#/components/parameters/_where" }, { "$ref": "#/components/parameters/_schema" }, { "$ref": "#/components/parameters/_sort" } ], "responses": { "200": { "description": "OK", "headers": { "REST-Content-Range": { "schema": { "type": "string", "description": "Indicates the range of documents returned in the current response, as well as the total number of documents available in the dataset. The value follows the format `resources={x}-{y}/{total}`, where:\n* `x`: Index of the first document in the returned array.\n* `y`: Index of the last document in the returned array + 1.\n* `total`: Total number of documents that match the query.\nFor example, `resources=0-10/98` indicates that documents from 0 to 9 are returned out of a total of 98 matching documents." } } }, "content": { "application/json": { "schema": { "type": "array", "description": "List of documents that correspond to the result of the search.", "items": { "$ref": "#/components/schemas/Using_fields_all" } }, "example": [ { "id": "b818cbda-e489-11e6-94f4-0ac138d2d42e", "accountId": "14af940d-9300-4279-9355-61d44c2ff879", "accountName": "apiexamples", "dataEntityId": "Newsletter" } ] } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "type": "object", "description": "Response body object.", "properties": { "Message": { "type": "string", "description": "Error message." } } }, "example": { "Message": "Field 'X' not found in schema" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "type": "object", "description": "Response body object.", "properties": { "Message": { "type": "string", "description": "Error message." } } }, "example": { "Message": "Cannot filter by private fields" } } } }, "503": { "description": "Service Unavailable\n\nWildcard queries are temporarily blocked due to excessive wildcard or keyword usage so reduce those requests and try again later." } }, "deprecated": false } }, "/api/dataentities/{dataEntityName}/scroll": { "get": { "tags": [ "Scroll" ], "summary": "Scroll documents", "description": "Returns a list of documents according to query parameter filters. If you need to query the entire database, or your collection is over 10000 documents, use this endpoint.\r\n\r\nIn the first request, the `X-VTEX-MD-TOKEN` token will be obtained in the response header. This token must be passed to the next request in the `_token` query string parameter. The token expires after 20 minutes of inactivity, and each request made with the token during this time resets the expiration timer.\r\n\r\nAfter the token is obtained, it is no longer necessary to send the filter or document size per page parameters. You only need to resend the token until the document collection is empty.\r\n\r\nFirst request:\r\n```\r\n/dataentities/Newsletter/scroll?isCluster=true&_size=250&_fields=email,firstName\r\n```\r\n\r\nRetrieve the token in the header `X-VTEX-MD-TOKEN` from the first request's response and use it to make the following requests.\r\n\r\nSubsequent requests:\r\n```\r\n/dataentities/Newsletter/scroll?_token={tokenValue}\r\n```\n\r\n\rLearn more about [Pagination in the Master Data API](https://developers.vtex.com/docs/guides/pagination-in-the-master-data-api).\r\n\r\n>⚠️ Avoid sending too many requests with wildcards (`*`) in the search parameters or using the `keyword` parameter. This may lead to this endpoint being temporarily blocked for your account. If this happens you will receive an error with status code `429`.\r\n\r\n## Query examples\r\n\r\n| **Query Type** | **Example** |\r\n|-|-|\r\n| **Simple filter** | `\/dataentities\/Newsletter\/scroll?email=my@email.com` |\r\n| **Complex filter** | `\/dataentities\/Newsletter\/scroll?_where=(firstName=Jon OR lastName=Smith) OR (createdIn between 2001-01-01 AND 2016-01-01)` |\r\n| **Date range** | `\/dataentities\/Newsletter\/scroll?_where=createdIn between 2001-01-01 AND 2016-01-01` |\r\n| **Range numeric fields** | `\/dataentities\/Newsletter\/scroll?_where=age between 18 AND 25` |\r\n| **Partial filter** | `\/dataentities\/Newsletter\/scroll?firstName=*Maria*` |\r\n| **Filter for null values** | `\/dataentities\/Newsletter\/scroll?_where=firstName is null` |\r\n| **Filter for non-null values** | `\/dataentities\/Newsletter\/scroll?_where=firstName is not null` |\r\n| **Filter for difference** | `\/dataentities\/Newsletter\/scroll?_where=firstName<>maria` |\r\n| **Filter greater than** | `\/dataentities\/Newsletter\/scroll?_where=number>5` |\r\n| **Filter less than** | `\/dataentities\/Newsletter\/scroll?_where=date<2001-01-01` |\r\n\r\n## Permissions\r\n\r\nAny user or [API key](https://developers.vtex.com/docs/guides/api-authentication-using-api-keys) must have at least one of the appropriate [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3) to be able to successfully run this request. Otherwise they will receive a status code `403` error. These are the applicable resources for this endpoint:\r\n\r\n| **Product** | **Category** | **Resource** |\r\n| --------------- | ----------------- | ----------------- |\r\n| Dynamic Storage | Dynamic storage generic resources | **Read only documents** |\r\n| Dynamic Storage | Dynamic storage generic resources | **Insert or update document (not remove)** |\r\n| Dynamic Storage | Dynamic storage generic resources | **Full access to all documents** |\r\n| Dynamic Storage | Dynamic storage generic resources | **Master Data administrator** |\r\n\r\nThere are no applicable [predefined roles](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy) for this resource list. You must [create a custom role](https://help.vtex.com/en/tutorial/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) and add at least one of the resources above in order to use this endpoint.To learn more about machine authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication).\r\n\r\n>\u2757 To prevent integrations from having excessive permissions, consider the [best practices for managing API keys](https://help.vtex.com/en/tutorial/best-practices-api-keys--7b6nD1VMHa49aI5brlOvJm) when assigning License Manager roles to integrations.", "operationId": "Scrolldocuments", "parameters": [ { "$ref": "#/components/parameters/dataEntityName" }, { "$ref": "#/components/parameters/Content-Type" }, { "$ref": "#/components/parameters/Accept" }, { "$ref": "#/components/parameters/_token" }, { "$ref": "#/components/parameters/_size" }, { "$ref": "#/components/parameters/_fields" }, { "$ref": "#/components/parameters/_where" }, { "$ref": "#/components/parameters/_schema" }, { "$ref": "#/components/parameters/_sort" } ], "responses": { "200": { "description": "OK", "headers": { "X-VTEX-MD-TOKEN": { "schema": { "type": "string", "description": "Scroll token, which must be informed in the `_token` query parameter in the subsequent requests. The token expires after 20 minutes of inactivity, and each request made with the token during this time resets the expiration timer." } }, "REST-Content-Total": { "schema": { "type": "string", "description": "Total amount of documents corresponding to the query." } } }, "content": { "application/json": { "schema": { "type": "array", "description": "List of documents that correspond to the result of the scroll.", "items": { "$ref": "#/components/schemas/Using_fields_all" } }, "example": [ { "id": "b818cbda-e489-11e6-94f4-0ac138d2d42e", "accountId": "14af940d-9300-4279-9355-61d44c2ff879", "accountName": "apiexamples", "dataEntityId": "Newsletter" } ] } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "type": "object", "description": "Response body object.", "properties": { "Message": { "type": "string", "description": "Error message." } } }, "example": { "Message": "Operation not found for this token: 'X'" } } } }, "429": { "description": "Too Many Requests\n\nWildcard queries are temporarily blocked due to excessive wildcard or keyword usage so reduce those requests and try again later." } }, "deprecated": false } }, "/api/dataentities/{dataEntityName}/schemas": { "get": { "tags": [ "Schemas" ], "summary": "Get schemas", "description": "Retrieves all existing [schemas](https://developers.vtex.com/docs/guides/master-data-schema-lifecycle) for a given data entity. \r\n\r\n## Permissions\r\n\r\nAny user or [API key](https://developers.vtex.com/docs/guides/api-authentication-using-api-keys) must have at least one of the appropriate [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3) to be able to successfully run this request. Otherwise they will receive a status code `403` error. These are the applicable resources for this endpoint:\r\n\r\n| **Product** | **Category** | **Resource** |\r\n| --------------- | ----------------- | ----------------- |\r\n| Dynamic Storage | Dynamic storage generic resources | **Read only documents** |\r\n| Dynamic Storage | Dynamic storage generic resources | **Insert or update document (not remove)** |\r\n| Dynamic Storage | Dynamic storage generic resources | **Full access to all documents** |\r\n| Dynamic Storage | Dynamic storage generic resources | **Master Data administrator** |\r\n\r\nThere are no applicable [predefined roles](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy) for this resource list. You must [create a custom role](https://help.vtex.com/en/tutorial/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) and add at least one of the resources above in order to use this endpoint.To learn more about machine authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication).\r\n\r\n>\u2757 To prevent integrations from having excessive permissions, consider the [best practices for managing API keys](https://help.vtex.com/en/tutorial/best-practices-api-keys--7b6nD1VMHa49aI5brlOvJm) when assigning License Manager roles to integrations.", "operationId": "Getschemas", "parameters": [ { "$ref": "#/components/parameters/dataEntityName" }, { "$ref": "#/components/parameters/Content-Type" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "description": "Array with existing schemas. In case there is only one existing schema, it will be an object instead, without the `name` property and the named `schema` object, following the same structure as the [Get schema by name](https://developers.vtex.com/docs/api-reference/master-data-api-v2#get-/api/dataentities/-dataEntityName-/schemas/-schemaName-?endpoint=get-/api/dataentities/-dataEntityName-/schemas/-schemaName-) endpoint response.", "items": { "$ref": "#/components/schemas/GetSchemasResponse" } }, "example": [ { "name": "testschema", "schema": { "properties": { "name": { "type": "string" } } } } ] } } } }, "deprecated": false } }, "/api/dataentities/{dataEntityName}/schemas/{schemaName}": { "get": { "tags": [ "Schemas" ], "summary": "Get schema by name", "description": "Returns an existing [schema](https://developers.vtex.com/docs/guides/master-data-schema-lifecycle) for a given data entity. \r\n\r\n## Permissions\r\n\r\nAny user or [API key](https://developers.vtex.com/docs/guides/api-authentication-using-api-keys) must have at least one of the appropriate [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3) to be able to successfully run this request. Otherwise they will receive a status code `403` error. These are the applicable resources for this endpoint:\r\n\r\n| **Product** | **Category** | **Resource** |\r\n| --------------- | ----------------- | ----------------- |\r\n| Dynamic Storage | Dynamic storage generic resources | **Read only documents** |\r\n| Dynamic Storage | Dynamic storage generic resources | **Insert or update document (not remove)** |\r\n| Dynamic Storage | Dynamic storage generic resources | **Full access to all documents** |\r\n| Dynamic Storage | Dynamic storage generic resources | **Master Data administrator** |\r\n\r\nThere are no applicable [predefined roles](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy) for this resource list. You must [create a custom role](https://help.vtex.com/en/tutorial/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) and add at least one of the resources above in order to use this endpoint.To learn more about machine authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication).\r\n\r\n>\u2757 To prevent integrations from having excessive permissions, consider the [best practices for managing API keys](https://help.vtex.com/en/tutorial/best-practices-api-keys--7b6nD1VMHa49aI5brlOvJm) when assigning License Manager roles to integrations.", "operationId": "Getschemabyname", "parameters": [ { "$ref": "#/components/parameters/dataEntityName" }, { "$ref": "#/components/parameters/Content-Type" }, { "$ref": "#/components/parameters/schemaName" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SaveschemabynameRequest" }, "example": { "properties": { "name": { "type": "string" } } } } } } }, "deprecated": false }, "put": { "tags": [ "Schemas" ], "summary": "Save schema by name", "description": "Creates or edits a data entity schema. Learn more about [Master Data schemas](https://developers.vtex.com/vtex-rest-api/docs/master-data-schema-lifecycle).\r\n\r\n> Note that if you send a `schemaName` that does not exist for that data entity, this request will create it.\r\n\r\nThis request can also be used to [create or edit Master Data v2 triggers](https://developers.vtex.com/vtex-rest-api/docs/setting-up-triggers-in-master-data-v2).\r\n\r\n> Each Master Data v2 data entity can have up to 60 schemas.\r\n\r\n## Indexing fields for search, scroll and sort\r\n\r\nTo filter or sort by a field in [Search documents](https://developers.vtex.com/docs/api-reference/master-data-api-v2#get-/api/dataentities/-dataEntityName-/search) or [Scroll documents](https://developers.vtex.com/docs/api-reference/master-data-api-v2#get-/api/dataentities/-dataEntityName-/scroll), add that field to the `v-indexed` array in the schema. This is the schema-level index (separate from the [indices](https://developers.vtex.com/docs/api-reference/master-data-api-v2#get-/api/dataentities/-dataEntityName-/indices) endpoint).\r\n\r\n- `v-indexed`: Array of property names that Master Data v2 must index for `/search`, `/scroll`, and `_sort`. Use it whenever you want to use `_where`, `_sort`, or range filters (e.g. `_where=postalCode between 10000 AND 20000`) on that field. Indexing runs asynchronously after the schema is saved.\r\n- `filterable` and `searchable`: Apply to the UI (e.g. Master Data v1/CRM-style behavior). They do **not** create the index used by `/search`; only `v-indexed` does.\r\n\r\n**Example request body with `v-indexed`:**\r\n\r\n```json\r\n{\r\n \"properties\": {\r\n \"skuId\": { \"type\": \"string\" },\r\n \"postalCode\": { \"type\": \"string\" }\r\n },\r\n \"v-indexed\": [\"postalCode\"]\r\n}\r\n```\r\n\r\n> ℹ️ Use `v-indexed` when you need fields to be filterable/sortable in `/search`. Use the [/indices](https://developers.vtex.com/docs/api-reference/master-data-api-v2#put-/api/dataentities/-dataEntityName-/indices) endpoint when you need entity-level uniqueness, composite keys, or relationships between entities.\r\n\r\n## Reindex lock\r\n\r\nSaving a schema can trigger a full reindex of the data entity. The reindex lock works in two stages:\r\n\r\n1. **Locking the data entity:** The lock starts only when a schema save triggers a reindex. Schema saves that don't trigger a reindex never lock the data entity.\r\n2. **While the lock is active:** Every later schema save for that same data entity is rejected with `423 Locked`, including saves that would not trigger a reindex on their own. The response states that the reindex is still in progress.\r\n\r\nA schema save can trigger a new reindex of the same data entity only after an interval of 12 hours. Don't calculate a retry time from this interval. To know when the data entity accepts schema saves again, read the `Message` field of the `423 Locked` response, which states the time after which you can retry. When that time is not available, the message asks you to try again later.\r\n\r\n## Permissions\r\n\r\nAny user or [API key](https://developers.vtex.com/docs/guides/api-authentication-using-api-keys) must have at least one of the appropriate [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3) to be able to successfully run this request. Otherwise they will receive a status code `403` error. These are the applicable resources for this endpoint:\r\n\r\n| **Product** | **Category** | **Resource** |\r\n| --------------- | ----------------- | ----------------- |\r\n| Dynamic Storage | Dynamic storage generic resources | **Master Data administrator** |\r\n\r\nThere are no applicable [predefined roles](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy) for this resource list. You must [create a custom role](https://help.vtex.com/en/tutorial/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) and add at least one of the resources above in order to use this endpoint.To learn more about machine authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication).\r\n\r\n>\u2757 To prevent integrations from having excessive permissions, consider the [best practices for managing API keys](https://help.vtex.com/en/tutorial/best-practices-api-keys--7b6nD1VMHa49aI5brlOvJm) when assigning License Manager roles to integrations.", "operationId": "Saveschemabyname", "parameters": [ { "$ref": "#/components/parameters/dataEntityName" }, { "$ref": "#/components/parameters/schemaName" } ], "requestBody": { "description": "JSON Schema of the data entity. Include `v-indexed` with an array of property names when you will filter or sort by those fields in /search or /scroll.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SaveschemabynameRequest" }, "examples": { "minimal": { "summary": "Minimal schema", "value": { "properties": { "name": { "type": "string", "description": "Customer name." } } } }, "withVIndexed": { "summary": "Schema with v-indexed for filter and sort", "value": { "properties": { "skuId": { "type": "string", "description": "SKU identifier." }, "postalCode": { "type": "string", "description": "Postal code." } }, "v-indexed": [ "postalCode" ] } } } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "description": "Response body object.", "properties": { "Message": { "type": "string", "description": "Success message." } } }, "example": { "Message": "JSON Schema persisted successfully. Revalidation and indexing process running in background." } } } }, "423": { "description": "Locked", "content": { "application/json": { "schema": { "type": "object", "description": "Response body object.", "properties": { "Message": { "type": "string", "description": "Message stating that a full reindex of the data entity is in progress. When a retry time is available, the message also states the time after which you can retry the schema save. Otherwise, it falls back to asking you to try again later." } } }, "examples": { "reindexInProgress": { "summary": "Lock with retry time", "value": { "Message": "A recent schema change triggered a full reindex of this data entity that is still in progress. Please try again after 01/02/2024 00:00:00 +00:00." } }, "reindexInProgressNoDate": { "summary": "Lock without retry time", "value": { "Message": "A recent schema change triggered a full reindex of this data entity that is still in progress. Please try again later." } } } } } } }, "deprecated": false }, "delete": { "tags": [ "Schemas" ], "summary": "Delete schema by name", "description": "Deletes an existing [schema](https://developers.vtex.com/docs/guides/master-data-schema-lifecycle) for a given data entity. \r\n\r\n## Permissions\r\n\r\nAny user or [API key](https://developers.vtex.com/docs/guides/api-authentication-using-api-keys) must have at least one of the appropriate [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3) to be able to successfully run this request. Otherwise they will receive a status code `403` error. These are the applicable resources for this endpoint:\r\n\r\n| **Product** | **Category** | **Resource** |\r\n| --------------- | ----------------- | ----------------- |\r\n| Dynamic Storage | Dynamic storage generic resources | **Master Data administrator** |\r\n\r\nThere are no applicable [predefined roles](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy) for this resource list. You must [create a custom role](https://help.vtex.com/en/tutorial/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) and add at least one of the resources above in order to use this endpoint.To learn more about machine authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication).\r\n\r\n>\u2757 To prevent integrations from having excessive permissions, consider the [best practices for managing API keys](https://help.vtex.com/en/tutorial/best-practices-api-keys--7b6nD1VMHa49aI5brlOvJm) when assigning License Manager roles to integrations.", "operationId": "Deleteschemabyname", "parameters": [ { "$ref": "#/components/parameters/Content-Type" }, { "$ref": "#/components/parameters/dataEntityName" }, { "$ref": "#/components/parameters/schemaName" } ], "responses": { "204": { "description": "No Content" } }, "deprecated": false } }, "/api/dataentities/{dataEntityName}/indices": { "get": { "tags": [ "Indices" ], "summary": "Get indices", "description": "Returns the list of [indices](https://developers.vtex.com/docs/guides/master-data-components#index) by data entity. \r\n\r\n## Permissions\r\n\r\nAny user or [API key](https://developers.vtex.com/docs/guides/api-authentication-using-api-keys) must have at least one of the appropriate [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3) to be able to successfully run this request. Otherwise they will receive a status code `403` error. These are the applicable resources for this endpoint:\r\n\r\n| **Product** | **Category** | **Resource** |\r\n| --------------- | ----------------- | ----------------- |\r\n| Dynamic Storage | Index | **View index details** |\r\n| Dynamic Storage | Index | **List index** |\r\n| Dynamic Storage | Dynamic storage generic resources | **Master Data administrator** |\r\n\r\nThere are no applicable [predefined roles](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy) for this resource list. You must [create a custom role](https://help.vtex.com/en/tutorial/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) and add at least one of the resources above in order to use this endpoint.To learn more about machine authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication).\r\n\r\n>\u2757 To prevent integrations from having excessive permissions, consider the [best practices for managing API keys](https://help.vtex.com/en/tutorial/best-practices-api-keys--7b6nD1VMHa49aI5brlOvJm) when assigning License Manager roles to integrations.", "operationId": "Getindices", "parameters": [ { "$ref": "#/components/parameters/dataEntityName" }, { "$ref": "#/components/parameters/Content-Type" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "description": "Array with information about indices.", "items": { "$ref": "#/components/schemas/Index" } }, "example": [ { "name": "fullName", "acronym": "Newsletter", "isGlobal": false, "multiple": false, "fields": "firstName,lastName" } ] } } } }, "deprecated": false }, "put": { "tags": [ "Indices" ], "summary": "Create index", "description": "Creates an [index](https://developers.vtex.com/docs/guides/master-data-components#index). \r\n\r\n## Permissions\r\n\r\nAny user or [API key](https://developers.vtex.com/docs/guides/api-authentication-using-api-keys) must have at least one of the appropriate [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3) to be able to successfully run this request. Otherwise they will receive a status code `403` error. These are the applicable resources for this endpoint:\r\n\r\n| **Product** | **Category** | **Resource** |\r\n| --------------- | ----------------- | ----------------- |\r\n| Dynamic Storage | Index | **Edit index** |\r\n| Dynamic Storage | Index | **Create index** |\r\n| Dynamic Storage | Dynamic storage generic resources | **Master Data administrator** |\r\n\r\nThere are no applicable [predefined roles](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy) for this resource list. You must [create a custom role](https://help.vtex.com/en/tutorial/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) and add at least one of the resources above in order to use this endpoint.To learn more about machine authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication).\r\n\r\n>\u2757 To prevent integrations from having excessive permissions, consider the [best practices for managing API keys](https://help.vtex.com/en/tutorial/best-practices-api-keys--7b6nD1VMHa49aI5brlOvJm) when assigning License Manager roles to integrations.", "operationId": "Putindices", "parameters": [ { "$ref": "#/components/parameters/dataEntityName" } ], "requestBody": { "description": "Request body for creating an index", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PutindicesRequest" }, "example": { "name": "indexName", "multiple": false, "fields": "fieldName" } } }, "required": true }, "responses": { "200": { "description": "OK" } }, "deprecated": false } }, "/api/dataentities/{dataEntityName}/indices/{index_name}": { "get": { "tags": [ "Indices" ], "summary": "Get index by name", "description": "Retrieves an [index](https://developers.vtex.com/docs/guides/master-data-components#index). \r\n\r\n## Permissions\r\n\r\nAny user or [API key](https://developers.vtex.com/docs/guides/api-authentication-using-api-keys) must have at least one of the appropriate [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3) to be able to successfully run this request. Otherwise they will receive a status code `403` error. These are the applicable resources for this endpoint:\r\n\r\n| **Product** | **Category** | **Resource** |\r\n| --------------- | ----------------- | ----------------- |\r\n| Dynamic Storage | Index | **View index details** |\r\n| Dynamic Storage | Dynamic storage generic resources | **Master Data administrator** |\r\n\r\nThere are no applicable [predefined roles](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy) for this resource list. You must [create a custom role](https://help.vtex.com/en/tutorial/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) and add at least one of the resources above in order to use this endpoint.To learn more about machine authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication).\r\n\r\n>\u2757 To prevent integrations from having excessive permissions, consider the [best practices for managing API keys](https://help.vtex.com/en/tutorial/best-practices-api-keys--7b6nD1VMHa49aI5brlOvJm) when assigning License Manager roles to integrations.", "operationId": "Getindexbyname", "parameters": [ { "$ref": "#/components/parameters/dataEntityName" }, { "$ref": "#/components/parameters/Content-Type" }, { "$ref": "#/components/parameters/index_name" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Index" }, "example": { "name": "fullName", "acronym": "Newsletter", "isGlobal": false, "multiple": false, "fields": "firstName,lastName" } } } } }, "deprecated": false }, "delete": { "tags": [ "Indices" ], "summary": "Delete index by name", "description": "Deletes an [index](https://developers.vtex.com/docs/guides/master-data-components#index). \r\n\r\n## Permissions\r\n\r\nAny user or [API key](https://developers.vtex.com/docs/guides/api-authentication-using-api-keys) must have at least one of the appropriate [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3) to be able to successfully run this request. Otherwise they will receive a status code `403` error. These are the applicable resources for this endpoint:\r\n\r\n| **Product** | **Category** | **Resource** |\r\n| --------------- | ----------------- | ----------------- |\r\n| Dynamic Storage | Index | **Remove index** |\r\n| Dynamic Storage | Dynamic storage generic resources | **Master Data administrator** |\r\n\r\nThere are no applicable [predefined roles](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy) for this resource list. You must [create a custom role](https://help.vtex.com/en/tutorial/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) and add at least one of the resources above in order to use this endpoint.To learn more about machine authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication).\r\n\r\n>\u2757 To prevent integrations from having excessive permissions, consider the [best practices for managing API keys](https://help.vtex.com/en/tutorial/best-practices-api-keys--7b6nD1VMHa49aI5brlOvJm) when assigning License Manager roles to integrations.", "operationId": "Deleteindexbyname", "parameters": [ { "$ref": "#/components/parameters/dataEntityName" }, { "$ref": "#/components/parameters/Content-Type" }, { "$ref": "#/components/parameters/index_name" } ], "responses": { "204": { "description": "No Content" } }, "deprecated": false } }, "/api/dataentities/{dataEntityName}/documents/{id}/clusters": { "post": { "tags": [ "Clusters" ], "summary": "Validate document by clusters", "description": "Checks if a document is present in one or more clusters (specific set of field values).\r\n\r\n>ℹ️ There is a limit of five rules per request. \r\n\r\n## Permissions\r\n\r\nAny user or [API key](https://developers.vtex.com/docs/guides/api-authentication-using-api-keys) must have at least one of the appropriate [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3) to be able to successfully run this request. Otherwise they will receive a status code `403` error. These are the applicable resources for this endpoint:\r\n\r\n| **Product** | **Category** | **Resource** |\r\n| --------------- | ----------------- | ----------------- |\r\n| Dynamic Storage | Dynamic storage generic resources | **Insert or update document (not remove)** |\r\n| Dynamic Storage | Dynamic storage generic resources | **Full access to all documents** |\r\n| Dynamic Storage | Dynamic storage generic resources | **Master Data administrator** |\r\n\r\nThere are no applicable [predefined roles](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy) for this resource list. You must [create a custom role](https://help.vtex.com/en/tutorial/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) and add at least one of the resources above in order to use this endpoint.To learn more about machine authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication).\r\n\r\n>\u2757 To prevent integrations from having excessive permissions, consider the [best practices for managing API keys](https://help.vtex.com/en/tutorial/best-practices-api-keys--7b6nD1VMHa49aI5brlOvJm) when assigning License Manager roles to integrations.", "operationId": "Validatedocumentbyclusters", "parameters": [ { "$ref": "#/components/parameters/dataEntityName" }, { "$ref": "#/components/parameters/Accept" }, { "$ref": "#/components/parameters/id" } ], "requestBody": { "description": "Request body for validating a document by clusters", "content": { "application/json": { "schema": { "type": "array", "description": "List of cluster validation rule information.", "items": { "type": "object", "description": "Cluster validation rule information.", "properties": { "name": { "type": "string", "description": "Cluster name.", "example": "male" }, "rule": { "type": "string", "description": "Cluster validation rule.", "example": "gender=male" } } } }, "example": [ { "name": "male", "rule": "gender=male" }, { "name": "complex", "rule": "((gender=male AND percent=0.35) AND any is null) AND (name=*go*)" }, { "name": "complex2", "rule": "((gender=male AND percent=0.35) AND any is not null) OR (name=*go*)" }, { "name": "createdIn", "rule": "createdIn between 2015-10-28 AND 2015-10-30" } ] } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "description": "Array with objects validating each cluster rule.", "items": { "type": "object", "description": "Cluster rule validation object.", "properties": { "name": { "type": "string", "description": "Cluster name." }, "isValid": { "type": "boolean", "description": "Informs if the document is valid according to the cluster rule (`true`) or not (`false`)." } } } }, "example": [ { "name": "male", "isValid": false }, { "name": "complex", "isValid": false }, { "name": "complex2", "isValid": false }, { "name": "createdIn", "isValid": false } ] } } } }, "deprecated": false } }, "/api/dataentities/{dataEntityName}/documents/{id}/versions": { "get": { "tags": [ "Versions" ], "summary": "List versions", "description": "Lists the versions of a document. \r\n\r\n>ℹ Master Data documents are versioned. This means that, for each change, a new version is generated. \r\n\r\n## Permissions\r\n\r\nAny user or [API key](https://developers.vtex.com/docs/guides/api-authentication-using-api-keys) must have at least one of the appropriate [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3) to be able to successfully run this request. Otherwise they will receive a status code `403` error. These are the applicable resources for this endpoint:\r\n\r\n| **Product** | **Category** | **Resource** |\r\n| --------------- | ----------------- | ----------------- |\r\n| Dynamic Storage | Dynamic storage generic resources | **Read only documents** |\r\n| Dynamic Storage | Dynamic storage generic resources | **Insert or update document (not remove)** |\r\n| Dynamic Storage | Dynamic storage generic resources | **Full access to all documents** |\r\n| Dynamic Storage | Dynamic storage generic resources | **Master Data administrator** |\r\n\r\nThere are no applicable [predefined roles](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy) for this resource list. You must [create a custom role](https://help.vtex.com/en/tutorial/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) and add at least one of the resources above in order to use this endpoint.To learn more about machine authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication).\r\n\r\n>\u2757 To prevent integrations from having excessive permissions, consider the [best practices for managing API keys](https://help.vtex.com/en/tutorial/best-practices-api-keys--7b6nD1VMHa49aI5brlOvJm) when assigning License Manager roles to integrations.", "operationId": "Listversions", "parameters": [ { "$ref": "#/components/parameters/dataEntityName" }, { "$ref": "#/components/parameters/Content-Type" }, { "$ref": "#/components/parameters/Accept" }, { "$ref": "#/components/parameters/id" }, { "name": "load", "in": "query", "description": "If true, return all the fields in each version of the document.", "required": false, "schema": { "type": "boolean", "default": true } }, { "name": "fields", "in": "query", "description": "If `load` is true, the response will return only these specific fields.", "required": false, "schema": { "type": "string", "default": "id,dataEntityId,isNewsletterOptIn,createdBy" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Listversion" } }, "example": [ { "id": "_EAR0cJ7XB5k5grnmm0zeKGlVvVM9WCPy_", "date": "2016-10-18T16:53:32+00:00", "document": { "id": "72e7f8dd-1168-23ec-82ac-0e2b61663eb4", "dataEntityId": "Newsletter", "isNewsletterOptIn": true, "createdBy": "81fc8b10-25b7-48de-b425-7b93554002cc" } }, { "id": "_E5SH9WXVvhPBNnbQtYAAGqrIysIeNYhV_", "date": "2016-09-08T20:11:42+00:00", "document": { "id": "72e7f8dd-1168-23ec-82ac-0e2b61663eb4", "dataEntityId": "Newsletter", "isNewsletterOptIn": true, "createdBy": "81fc8b10-25b7-48de-b425-7b93554002cc" } } ] } } } }, "deprecated": false } }, "/api/dataentities/{dataEntityName}/documents/{id}/versions/{versionId}": { "get": { "tags": [ "Versions" ], "summary": "Get version", "description": "Returns the version of a document. \r\n\r\n>ℹ Master Data documents are versioned. This means that, for each change, a new version is generated. \r\n\r\n## Permissions\r\n\r\nAny user or [API key](https://developers.vtex.com/docs/guides/api-authentication-using-api-keys) must have at least one of the appropriate [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3) to be able to successfully run this request. Otherwise they will receive a status code `403` error. These are the applicable resources for this endpoint:\r\n\r\n| **Product** | **Category** | **Resource** |\r\n| --------------- | ----------------- | ----------------- |\r\n| Dynamic Storage | Dynamic storage generic resources | **Read only documents** |\r\n| Dynamic Storage | Dynamic storage generic resources | **Insert or update document (not remove)** |\r\n| Dynamic Storage | Dynamic storage generic resources | **Full access to all documents** |\r\n| Dynamic Storage | Dynamic storage generic resources | **Master Data administrator** |\r\n\r\nThere are no applicable [predefined roles](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy) for this resource list. You must [create a custom role](https://help.vtex.com/en/tutorial/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) and add at least one of the resources above in order to use this endpoint.To learn more about machine authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication).\r\n\r\n>\u2757 To prevent integrations from having excessive permissions, consider the [best practices for managing API keys](https://help.vtex.com/en/tutorial/best-practices-api-keys--7b6nD1VMHa49aI5brlOvJm) when assigning License Manager roles to integrations.", "operationId": "Getversion", "parameters": [ { "$ref": "#/components/parameters/dataEntityName" }, { "$ref": "#/components/parameters/Content-Type" }, { "$ref": "#/components/parameters/Accept" }, { "$ref": "#/components/parameters/id" }, { "$ref": "#/components/parameters/versionId" } ], "responses": { "200": { "description": "OK", "headers": {}, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Getversion" }, "example": { "id": "cSIAceEelBEmSOqRkzJYLRQuGgi6.CqF", "author": "1f936e42-79b3-4e5b-91d2-da9a8af0b215", "document": { "id": "cbfc4f67-6ea3-11ee-83ab-0a8d18f9f827", "dataEntityId": "Newsletter", "accountId": "a8b27fb4-6516-4cc0-82b6-a5f2b011e6e2", "accountName": "apiexamples", "followers": [], "schemas": [ "testprofile", "testprofile2" ], "email": "clark.kent@examplemail.com" } } } } } }, "deprecated": false }, "put": { "tags": [ "Versions" ], "summary": "Update version", "description": "Updates the document's version value.\r\n\r\n>ℹ Master Data documents are versioned. This means that, for each change, a new version is generated. \r\n\r\n## Permissions\r\n\r\nAny user or [API key](https://developers.vtex.com/docs/guides/api-authentication-using-api-keys) must have at least one of the appropriate [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3) to be able to successfully run this request. Otherwise they will receive a status code `403` error. These are the applicable resources for this endpoint:\r\n\r\n| **Product** | **Category** | **Resource** |\r\n| --------------- | ----------------- | ----------------- |\r\n| Dynamic Storage | Dynamic storage generic resources | **Insert or update document (not remove)** |\r\n| Dynamic Storage | Dynamic storage generic resources | **Full access to all documents** |\r\n| Dynamic Storage | Dynamic storage generic resources | **Master Data administrator** |\r\n\r\nThere are no applicable [predefined roles](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy) for this resource list. You must [create a custom role](https://help.vtex.com/en/tutorial/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) and add at least one of the resources above in order to use this endpoint.To learn more about machine authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication).\r\n\r\n>\u2757 To prevent integrations from having excessive permissions, consider the [best practices for managing API keys](https://help.vtex.com/en/tutorial/best-practices-api-keys--7b6nD1VMHa49aI5brlOvJm) when assigning License Manager roles to integrations.", "operationId": "Putversion", "parameters": [ { "$ref": "#/components/parameters/dataEntityName" }, { "$ref": "#/components/parameters/Content-Type" }, { "$ref": "#/components/parameters/Accept" }, { "$ref": "#/components/parameters/id" }, { "name": "versionId", "in": "path", "description": "ID of the version to update", "required": true, "style": "simple", "schema": { "type": "string", "example": "_8sZcvyj4nng7FgA2RgtVVZmkIxb4Pbfe_" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/documentResponse" }, "example": { "Id": "Newsletter-b818cbda-e489-11e6-94f4-0ac138d2d42e", "Href": "http://api.vtex.com/apiexamples/dataentities/Newsletter/documents/b818cbda-e489-11e6-94f4-0ac138d2d42e" } } } }, "304": { "description": "Not Modified" } }, "deprecated": false } } }, "security": [ { "appKey": [], "appToken": [] }, { "VtexIdclientAutCookie": [] } ], "components": { "securitySchemes": { "appKey": { "type": "apiKey", "in": "header", "name": "X-VTEX-API-AppKey", "description": "Unique identifier of the [API key](https://developers.vtex.com/docs/guides/api-authentication-using-api-keys)." }, "appToken": { "type": "apiKey", "in": "header", "name": "X-VTEX-API-AppToken", "description": "Secret token of the [API key](https://developers.vtex.com/docs/guides/api-authentication-using-api-keys)." }, "VtexIdclientAutCookie": { "type": "apiKey", "in": "header", "name": "VtexIdclientAutCookie", "description": "[User token](https://developers.vtex.com/docs/guides/api-authentication-using-user-tokens), valid for 24 hours." } }, "schemas": { "DocumentRequest": { "title": "DocumentRequest", "type": "object", "description": "This can be any pure JSON document. Add new _Key-Value_ pairs to test.", "additionalProperties": true }, "Using_fields_all": { "title": "Using_fields=_all", "required": [ "id", "accountId", "accountName", "dataEntityId" ], "type": "object", "description": "Document information.", "properties": { "id": { "type": "string", "description": "ID of the document." }, "accountId": { "type": "string", "description": "ID of the VTEX account." }, "accountName": { "type": "string", "description": "Name of the VTEX account." }, "dataEntityId": { "type": "string", "description": "Data entity name." } } }, "SaveschemabynameRequest": { "title": "SaveschemabynameRequest", "required": [ "properties" ], "type": "object", "description": "JSON Schema of the data entity. Add `v-indexed` with an array of property names to make those fields filterable and sortable in /search and /scroll.", "properties": { "properties": { "type": "object", "description": "Object containing schema properties.", "properties": { "name": { "type": "object", "description": "Property name.", "required": [ "type" ], "properties": { "type": { "type": "string", "description": "Type of property.", "enum": [ "array", "boolean", "integer", "number", "object", "string" ] } } } } }, "v-indexed": { "type": "array", "items": { "type": "string", "description": "Name of a property to index." }, "description": "Names of properties to index for /search, /scroll, and _sort. Required for reliable filtering (e.g. _where=field=value) and sorting (_sort=field ASC). Indexing is asynchronous after schema save." } } }, "GetSchemasResponse": { "title": "GetSchemasResponse", "required": [ "name", "schema" ], "type": "object", "description": "Schema.", "properties": { "name": { "type": "string", "description": "Schema name." }, "schema": { "type": "object", "description": "Object with schema properties.", "properties": { "properties": { "type": "object", "description": "Object containing schema properties.", "properties": { "name": { "type": "object", "description": "Property name.", "required": [ "type" ], "properties": { "type": { "type": "string", "description": "Type of property.", "enum": [ "array", "boolean", "integer", "number", "object", "string" ] } } } } } } } } }, "Properties": { "title": "Properties", "required": [ "name" ], "type": "object", "description": "Object containing schema properties.", "properties": { "name": { "$ref": "#/components/schemas/Name" } } }, "Name": { "title": "Name", "required": [ "type" ], "type": "object", "description": "Property name.", "properties": { "type": { "type": "string", "description": "Type of property.", "enum": [ "array", "boolean", "integer", "number", "object", "string" ] } } }, "PutindicesRequest": { "title": "PutindicesRequest", "required": [ "name", "multiple", "fields" ], "type": "object", "description": "Request body object.", "properties": { "name": { "description": "Name to identify the index.", "type": "string", "example": "indexName" }, "multiple": { "description": "Determines whether the values need to be unique. If false, values must be unique.", "type": "boolean", "example": false }, "fields": { "description": "Comma-separated fields of the index.", "type": "string", "example": "fieldName" } } }, "Index": { "type": "object", "description": "Index information.", "properties": { "name": { "type": "string", "description": "Index name." }, "acronym": { "type": "string", "description": "Data entity name." }, "isGlobal": { "type": "boolean", "description": "Defines whether the index is global (`true`) or not (`false`).", "deprecated": true }, "multiple": { "type": "boolean", "description": "Determines whether the values need to be unique. If `false`, values must be unique." }, "fields": { "type": "string", "description": "Comma-separated fields of the index." } } }, "Listversion": { "title": "Listversion", "required": [ "id", "date" ], "type": "object", "description": "Version information.", "properties": { "id": { "type": "string", "description": "Version ID." }, "date": { "type": "string", "description": "Date when the version was created in ISO 8601 format." }, "document": { "type": "object", "description": "Information about the document.", "properties": { "id": { "type": "string", "description": "Document ID." }, "dataEntityId": { "type": "string", "description": "Data entity name." }, "isNewsletterOptIn": { "type": "boolean", "description": "Indicates whether client otped to receive the store newsletter (`true`) or not (`false`).", "nullable": true }, "createdBy": { "type": "string", "description": "ID of the user who created the document." } } } } }, "Getversion": { "title": "Getversion", "required": [ "id", "author", "document" ], "type": "object", "description": "Request body object.", "properties": { "id": { "type": "string", "description": "Version ID." }, "author": { "type": "string", "description": "ID of the user who created the version." }, "document": { "$ref": "#/components/schemas/Document" } } }, "Document": { "title": "Document", "required": [ "id", "dataEntityId", "accountId", "accountName", "followers" ], "type": "object", "description": "Document information.", "properties": { "id": { "type": "string", "description": "ID of the document." }, "dataEntityId": { "type": "string", "description": "Data entity name." }, "accountId": { "type": "string", "description": "ID of the VTEX account." }, "accountName": { "type": "string", "description": "Name of the VTEX account." }, "followers": { "type": "array", "description": "Followers.", "deprecated": true, "items": { "type": "string", "description": "Follower." } }, "schemas": { "type": "array", "description": "Schemas which the document is compliant with.", "items": { "type": "string", "description": "Schema name." } }, "email": { "type": "string", "description": "User email." } } }, "CreateDocumentResponse": { "required": [ "Id", "Href", "DocumentId" ], "type": "object", "description": "Response body object.", "properties": { "Id": { "type": "string", "description": "ID of the document that was created, with data entity prefix." }, "Href": { "type": "string", "description": "Document reference URL." }, "DocumentId": { "type": "string", "description": "ID of the document that was created." } } }, "documentResponse": { "required": [ "Id", "Href" ], "type": "object", "description": "Response body object.", "properties": { "Id": { "type": "string", "description": "ID of the document that was created or updated." }, "Href": { "type": "string", "description": "Document reference URL." } } }, "BulkDeletionRequest": { "type": "object", "description": "Request body object.", "required": [ "filter" ], "properties": { "filter": { "type": "string", "description": "Deletion criteria, using the same syntax as the filter in the [Search documents](https://developers.vtex.com/docs/api-reference/master-data-api-v2#get-/api/dataentities/-dataEntityName-/search) request. Wildcards are not allowed and every field must be indexed." }, "schema": { "type": "string", "description": "Name of the [schema](https://developers.vtex.com/docs/guides/master-data-schema-lifecycle) that declares the filtered field as indexed. Required only when the filter uses custom fields." } } }, "BulkDeletionJobResponse": { "type": "object", "description": "Response body object.", "properties": { "JobId": { "type": "string", "description": "Unique identifier of the bulk deletion job. Use this value to track the job with the [Get bulk document deletion job status](https://developers.vtex.com/docs/api-reference/master-data-api-v2#get-/api/dataentities/-dataEntityName-/delete/jobs/-jobId-) endpoint." } } }, "BulkDeleteJobStatusResponseVO": { "type": "object", "description": "Response body object.", "properties": { "JobId": { "type": "string", "description": "Unique identifier of the bulk deletion job." }, "Entity": { "type": "string", "description": "Name of the data entity whose documents the job deletes." }, "Status": { "type": "string", "description": "Current status of the bulk deletion job. Possible values: `InProgress`, `Success`, or `Failed`.", "enum": [ "InProgress", "Success", "Failed" ] }, "Filter": { "type": "string", "description": "Deletion criteria sent when the job was created." }, "DocumentsDeleted": { "type": "integer", "description": "Number of documents that the job has deleted." }, "CreatedAt": { "type": "string", "format": "date-time", "description": "Date and time when the job was created, in the ISO 8601 format." }, "UpdatedAt": { "type": "string", "format": "date-time", "description": "Date and time when the job was last updated, in the ISO 8601 format." } } }, "BulkDeletionErrorResponse": { "type": "object", "description": "Response body object.", "properties": { "Message": { "type": "string", "description": "Error message." } } } }, "parameters": { "Content-Type": { "name": "Content-Type", "in": "header", "description": "Type of the content being sent.", "required": true, "style": "simple", "schema": { "type": "string", "example": "application/json" } }, "Accept": { "name": "Accept", "in": "header", "description": "HTTP Client Negotiation _Accept_ Header. Indicates the types of responses the client can understand.", "required": true, "style": "simple", "schema": { "type": "string", "example": "application/json" } }, "dataEntityName": { "name": "dataEntityName", "in": "path", "required": true, "description": "Name of the data entity.", "schema": { "type": "string", "example": "Newsletter" } }, "_schema": { "name": "_schema", "in": "query", "description": "Name of the [schema](https://developers.vtex.com/docs/guides/master-data-schema-lifecycle) that the document complies with. This field is required when using `_where` or `_fields` query parameters.", "required": false, "style": "form", "schema": { "type": "string", "example": "schema" } }, "id": { "name": "id", "in": "path", "description": "ID of the Document.", "required": true, "style": "simple", "schema": { "type": "string", "example": "b818cbda-e489-11e6-94f4-0ac138d2d42e" } }, "versionId": { "name": "versionId", "in": "path", "description": "ID of the version to update.", "required": true, "style": "simple", "schema": { "type": "string", "example": "_8sZcvyj4nng7FgA2RgtVVZmkIxb4Pbfe_" } }, "_where": { "name": "_where", "in": "query", "description": "Defines a condition the document must comply with. When referring to fields, you can use a nested field up to the first level (e.g. `wishlistProduct.productName`).", "required": false, "style": "form", "schema": { "type": "string", "example": "firstName is not null" } }, "index_name": { "name": "index_name", "in": "path", "description": "Name of the index.", "required": true, "style": "simple", "schema": { "type": "string", "example": "{{index_name}}" } }, "schemaName": { "name": "schemaName", "in": "path", "description": "Name of the schema.", "required": true, "style": "simple", "schema": { "type": "string", "example": "{{schema}}" } }, "REST-Range": { "name": "REST-Range", "in": "header", "description": "Specifies the range of documents to be returned in the response. The value should follow the format `resources={x}-{y}`, where:\n* `x`: Index of the first document in the returned array.\n* `y`: Index of the last document in the returned array + 1.\n\nThis field controls pagination by defining the subset of documents to be retrieved. The maximum number of documents returned per query is limited to 100.\nFor example, `resources=0-10` returns the first 10 documents.", "required": true, "style": "simple", "schema": { "type": "string", "example": "resources=0-10" } }, "_fields": { "name": "_fields", "in": "query", "description": "Fields that should be returned by document. Separate fields' names with commas. For example `_fields=email,firstName,document`. You can also use `_fields=_all` to fetch all fields.", "required": false, "style": "form", "schema": { "type": "string", "example": "email,firstName,document" } }, "_sort": { "name": "_sort", "in": "query", "description": "Defines sorting mode in two parts. The first part is the name of the field you want to sort by. It can be a nested field up to the first level (e.g. `wishlistProduct.productName`). In the second part, use `ASC` for ascending order or `DESC` for descending order.", "required": false, "style": "form", "schema": { "type": "string", "example": "firstName ASC" } }, "_token": { "name": "_token", "in": "query", "description": "Value of the `X-VTEX-MD-TOKEN` token obtained in the response header of the first request, necessary on subsequent requests to continue scrolling through documents. The token expires after 20 minutes of inactivity, and each request made with the token during this time resets the expiration timer.", "required": false, "style": "form", "schema": { "type": "string", "example": "123456" } }, "_size": { "name": "_size", "in": "query", "description": "Inform the number of documents per request. Maximum value of `1000`.", "required": false, "style": "form", "schema": { "type": "integer", "default": 100 } } } }, "tags": [ { "name": "Documents" }, { "name": "Search" }, { "name": "Scroll" }, { "name": "Schemas" }, { "name": "Indices" }, { "name": "Clusters" }, { "name": "Versions" }, { "name": "Bulk deletion", "description": "Bulk deletion removes all documents in a data entity that match a filter, through an asynchronous job. This action cannot be undone." } ] }