openapi: 3.0.0 info: title: VTex 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. | \r\n\r\n## Index\r\n\r\n### Documents\r\n\r\n- `POST` [Create new document](https://developers.vtex.com/docs/api-reference/master-data-api-v2#post-/api/dataentities/-dataEntityName-/documents)\r\n- `PATCH` [Create partial document](https://developers.vtex.com/docs/api-reference/master-data-api-v2#patch-/api/dataentities/-dataEntityName-/documents)\r\n- `GET` [Get document](https://developers.vtex.com/docs/api-reference/master-data-api-v2#get-/api/dataentities/-dataEntityName-/documents/-id-)\r\n- `PUT` [Create document with custom ID or Update entire document](https://developers.vtex.com/docs/api-reference/master-data-api-v2#put-/api/dataentities/-dataEntityName-/documents/-id-)\r\n- `PATCH` [Update partial document](https://developers.vtex.com/docs/api-reference/master-data-api-v2#patch-/api/dataentities/-dataEntityName-/documents/-id-)\r\n- `DELETE` [Delete document](https://developers.vtex.com/docs/api-reference/master-data-api-v2#delete-/api/dataentities/-dataEntityName-/documents/-id-)\r\n\r\n### Search\r\n\r\n- `GET` [Search documents](https://developers.vtex.com/docs/api-reference/master-data-api-v2#get-/api/dataentities/-dataEntityName-/search)\r\n\r\n### Scroll\r\n\r\n- `GET` [Scroll documents](https://developers.vtex.com/docs/api-reference/master-data-api-v2#get-/api/dataentities/-dataEntityName-/scroll)\r\n\r\n### Schemas\r\n\r\n- `GET` [Get schemas](https://developers.vtex.com/docs/api-reference/master-data-api-v2#get-/api/dataentities/-dataEntityName-/schemas)\r\n- `GET` [Get schema by name](https://developers.vtex.com/docs/api-reference/master-data-api-v2#get-/api/dataentities/-dataEntityName-/schemas/-schemaName-)\r\n- `PUT` [Save schema by name](https://developers.vtex.com/docs/api-reference/master-data-api-v2#put-/api/dataentities/-dataEntityName-/schemas/-schemaName-)\r\n- `DELETE` [Delete schema by name](https://developers.vtex.com/docs/api-reference/master-data-api-v2#delete-/api/dataentities/-dataEntityName-/schemas/-schemaName-)\r\n\r\n### Indices\r\n\r\n- `GET` [Get indices](https://developers.vtex.com/docs/api-reference/master-data-api-v2#get-/api/dataentities/-dataEntityName-/indices)\r\ \n- `PUT` [Put indices](https://developers.vtex.com/docs/api-reference/master-data-api-v2#put-/api/dataentities/-dataEntityName-/indices)\r\n- `GET` [Get index by name](https://developers.vtex.com/docs/api-reference/master-data-api-v2#get-/api/dataentities/-dataEntityName-/indices/-index_name-)\r\n- `DELETE` [Delete index by name](https://developers.vtex.com/docs/api-reference/master-data-api-v2#delete-/api/dataentities/-dataEntityName-/indices/-index_name-)\r\n\r\n### Clusters\r\n\r\n- `POST` [Validate document by clusters](https://developers.vtex.com/docs/api-reference/master-data-api-v2#post-/api/dataentities/-dataEntityName-/documents/-id-/clusters)\r\n\r\n### Versions\r\n\r\n- `GET` [List versions](https://developers.vtex.com/docs/api-reference/master-data-api-v2#get-/api/dataentities/-dataEntityName-/documents/-id-/versions)\r\n- `GET` [Get version](https://developers.vtex.com/docs/api-reference/master-data-api-v2#get-/api/dataentities/-dataEntityName-/documents/-id-/versions/-versionId-)\r\n- `PUT` [Put version](https://developers.vtex.com/docs/api-reference/master-data-api-v2#put-/api/dataentities/-dataEntityName-/documents/-id-/versions/-versionId-)" 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: VTex 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 [application key](https://developers.vtex.com/docs/guides/api-authentication-using-application-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>❗ To prevent integrations from having excessive permissions, consider the [best practices for managing app keys](https://help.vtex.com/en/tutorial/best-practices-application-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: '200': description: OK 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: VTex 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 [application key](https://developers.vtex.com/docs/guides/api-authentication-using-application-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>❗ To prevent integrations from having excessive permissions, consider the [best practices for managing app keys](https://help.vtex.com/en/tutorial/best-practices-application-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/documentResponse' example: Id: Newsletter-b818cbda-e489-11e6-94f4-0ac138d2d42e Href: http://api.vtex.com/apiexamples/dataentities/Newsletter/documents/b818cbda-e489-11e6-94f4-0ac138d2d42e deprecated: false /api/dataentities/{dataEntityName}/documents/{id}: get: tags: - Documents summary: VTex 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 [application key](https://developers.vtex.com/docs/guides/api-authentication-using-application-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>❗ To prevent integrations from having excessive permissions, consider the [best practices for managing app keys](https://help.vtex.com/en/tutorial/best-practices-application-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: VTex 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 [application key](https://developers.vtex.com/docs/guides/api-authentication-using-application-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>❗ To prevent integrations from having excessive permissions, consider the [best practices for managing app keys](https://help.vtex.com/en/tutorial/best-practices-application-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: '200': description: OK. Document changed successfully. 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 '201': description: Created. Document created successfully. '304': description: Not Modified. There were no changes to the document. '400': description: Bad Request. Invalid information in JSON. '403': description: Forbidden. Unauthorized access. deprecated: false patch: tags: - Documents summary: VTex 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 [application key](https://developers.vtex.com/docs/guides/api-authentication-using-application-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>❗ To prevent integrations from having excessive permissions, consider the [best practices for managing app keys](https://help.vtex.com/en/tutorial/best-practices-application-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: '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 deprecated: false delete: tags: - Documents summary: VTex Delete document description: "Deletes a document. \r\n\r\n## Permissions\r\n\r\nAny user or [application key](https://developers.vtex.com/docs/guides/api-authentication-using-application-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>❗ To prevent integrations from having excessive permissions, consider the [best practices for managing app keys](https://help.vtex.com/en/tutorial/best-practices-application-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: '200': description: OK headers: {} deprecated: false /api/dataentities/{dataEntityName}/search: get: tags: - Search summary: VTex Search documents description: "Retrieves 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 results from 0 to 100 of a total 136108.\r\n\r\nBelow you can see some query examples and learn more about each query parameter.\n\r\n\r> 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### Simple filter\r\n\r\n```\r\n/dataentities/Newsletter/search?email=my@email.com\r\n```\r\n\r\n### Complex filter\r\n\r\n```\r\n/dataentities/Newsletter/search?_where=(firstName=Jon OR lastName=Smith) OR (createdIn between 2001-01-01 AND 2016-01-01)\r\n```\r\n\r\n### Date Range\r\n\r\n```\r\n/dataentities/Newsletter/search?_where=createdIn between 2001-01-01 AND 2016-01-01\r\n```\r\n\r\n### Range numeric fields\r\n\r\n```\r\n/dataentities/Newsletter/search?_where=age between 18 AND 25\r\n```\r\n\r\n### Partial filter\r\n\r\n```\r\n/dataentities/Newsletter/search?firstName=*Maria*\r\n```\r\n\r\n### Filter for null values\r\n\r\n```\r\n/dataentities/Newsletter/search?_where=firstName is null\r\n```\r\n\r\n### Filter for non-null values\r\n\r\n```\r\n/dataentities/Newsletter/search?_where=firstName is not null\r\n```\r\n\r\n### Filter for difference\r\n```\r\n/dataentities/Newsletter/search?_where=firstName<>maria\r\n```\r\n\r\n### Filter greater than or less than\r\n```\r\n/dataentities/Newsletter/search?_where=number>5\r\n/dataentities/Newsletter/search?_where=date<2001-01-01\r\n``` \r\n\r\n## Permissions\r\n\r\nAny user or [application key](https://developers.vtex.com/docs/guides/api-authentication-using-application-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>❗ To prevent integrations from having excessive permissions, consider the [best practices for managing app keys](https://help.vtex.com/en/tutorial/best-practices-application-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 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. Wildcard queries temporarily blocked due to excessive usage. Consider adjusting your code to remove them or reduce the rate of search requests with wildcards (*). This temporary block may also be due to excessive use of requests with the parameter `keyword`. deprecated: false /api/dataentities/{dataEntityName}/scroll: get: tags: - Scroll summary: VTex Scroll documents description: "If you need to query the entire VTEX Master Data database, or your collection is over 10.000 documents, use this endpoint.\r\n\r\nIn the first request, the `X-VTEX-MD-TOKEN` token will be returned in the header. This token must be passed to the next request in the query string `_token` parameter. The token has a timeout of 10 minutes, which refreshes after each request.\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. \n\r\n\r>⚠️ 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## Request examples\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``` \r\n\r\n## Permissions\r\n\r\nAny user or [application key](https://developers.vtex.com/docs/guides/api-authentication-using-application-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>❗ To prevent integrations from having excessive permissions, consider the [best practices for managing app keys](https://help.vtex.com/en/tutorial/best-practices-application-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 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. Wildcard queries temporarily blocked due to excessive usage. Consider adjusting your code to remove them or reduce the rate of search requests with wildcards (*). This temporary block may also be due to excessive use of requests with the parameter `keyword`. deprecated: false /api/dataentities/{dataEntityName}/schemas: get: tags: - Schemas summary: VTex 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 [application key](https://developers.vtex.com/docs/guides/api-authentication-using-application-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>❗ To prevent integrations from having excessive permissions, consider the [best practices for managing app keys](https://help.vtex.com/en/tutorial/best-practices-application-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: VTex 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 [application key](https://developers.vtex.com/docs/guides/api-authentication-using-application-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>❗ To prevent integrations from having excessive permissions, consider the [best practices for managing app keys](https://help.vtex.com/en/tutorial/best-practices-application-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: VTex 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## Permissions\r\n\r\nAny user or [application key](https://developers.vtex.com/docs/guides/api-authentication-using-application-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>❗ To prevent integrations from having excessive permissions, consider the [best practices for managing app keys](https://help.vtex.com/en/tutorial/best-practices-application-keys--7b6nD1VMHa49aI5brlOvJm) when assigning License Manager roles to integrations." operationId: Saveschemabyname parameters: - $ref: '#/components/parameters/dataEntityName' - $ref: '#/components/parameters/schemaName' requestBody: description: Request body for saving schema content: application/json: schema: $ref: '#/components/schemas/SaveschemabynameRequest' example: properties: name: type: string 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. deprecated: false delete: tags: - Schemas summary: VTex 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 [application key](https://developers.vtex.com/docs/guides/api-authentication-using-application-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>❗ To prevent integrations from having excessive permissions, consider the [best practices for managing app keys](https://help.vtex.com/en/tutorial/best-practices-application-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: VTex 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 [application key](https://developers.vtex.com/docs/guides/api-authentication-using-application-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>❗ To prevent integrations from having excessive permissions, consider the [best practices for managing app keys](https://help.vtex.com/en/tutorial/best-practices-application-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: VTex 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 [application key](https://developers.vtex.com/docs/guides/api-authentication-using-application-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>❗ To prevent integrations from having excessive permissions, consider the [best practices for managing app keys](https://help.vtex.com/en/tutorial/best-practices-application-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: VTex 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 [application key](https://developers.vtex.com/docs/guides/api-authentication-using-application-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>❗ To prevent integrations from having excessive permissions, consider the [best practices for managing app keys](https://help.vtex.com/en/tutorial/best-practices-application-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: VTex 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 [application key](https://developers.vtex.com/docs/guides/api-authentication-using-application-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>❗ To prevent integrations from having excessive permissions, consider the [best practices for managing app keys](https://help.vtex.com/en/tutorial/best-practices-application-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: VTex 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 [application key](https://developers.vtex.com/docs/guides/api-authentication-using-application-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>❗ To prevent integrations from having excessive permissions, consider the [best practices for managing app keys](https://help.vtex.com/en/tutorial/best-practices-application-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: VTex 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 [application key](https://developers.vtex.com/docs/guides/api-authentication-using-application-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>❗ To prevent integrations from having excessive permissions, consider the [best practices for managing app keys](https://help.vtex.com/en/tutorial/best-practices-application-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: VTex 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 [application key](https://developers.vtex.com/docs/guides/api-authentication-using-application-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>❗ To prevent integrations from having excessive permissions, consider the [best practices for managing app keys](https://help.vtex.com/en/tutorial/best-practices-application-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: VTex 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 [application key](https://developers.vtex.com/docs/guides/api-authentication-using-application-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>❗ To prevent integrations from having excessive permissions, consider the [best practices for managing app keys](https://help.vtex.com/en/tutorial/best-practices-application-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 [application key](https://developers.vtex.com/docs/guides/api-authentication-using-application-keys). appToken: type: apiKey in: header name: X-VTEX-API-AppToken description: Secret token of the [application key](https://developers.vtex.com/docs/guides/api-authentication-using-application-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: Schema. properties: properties: $ref: '#/components/schemas/Properties' 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: $ref: '#/components/schemas/Properties' 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 example: 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`). example: 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. 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 clause the document must comply with. 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: Defines the collection of documents to be returned. A range within the collection limited by 100 documents per query. 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: Sets sorting mode in two parts. The first part is the name of the field you want to sort by. In the second part, use `ASC` for ascending or `DESC` for descending. required: false style: form schema: type: string example: firstName ASC _token: name: _token in: query description: Value of the header `X-VTEX-MD-TOKEN` returned in your first request. Send its value in this query string in the subsequent requests. The token has a timeout of 10 minutes, which refreshes after each new request. 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: Clusters - name: Documents - name: Indices - name: Schemas - name: Scroll - name: Search - name: Versions