VTEX Scroll API

openapi: 3.2.0
info:
  title: VTex Master Data API - v2 Scroll API
  description: ">ℹ️ Master Data v2 is not compatible with data entities from previous versions, such as CL and AD.\n\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.\n\nSeveral internal VTEX modules use Master Data as a data repository, including Orders and Sales App. \n\nThere are two main ways to use Master Data:\n\n- [Directly from the storefront](#directly-from-the-storefront)\n- [With an external integration](#external-integrations)\n\n## Directly from the storefront\n\nWhen using Master Data within the storefront, consider the following:\n\n- Use the storefront host to query or store information to avoid issues related to Cross-origin resource sharing (CORS).\n- Use the relative path to avoid CORS issues.\n- Configure the JSON Schema of the Data Entity to specify which information should be public and which should not be.\n- Avoid creating query loops to prevent potential throttling issues or APIs being disabled due to security protection measures.\n- Never add authentication keys, such as `X-VTEX-API-AppKey` or `X-VTEX-API-AppToken`, via JavaScript as this could pose security risks.\n\n## External integrations\n\nWhen using Master Data to store data from an external integration, such as client data from another service, consider the following:\n\n- Use the host `{{accountName}}.vtexcommercestable.com.br`.\n- Use the authentication keys (`X-VTEX-API-AppKey` ou `X-VTEX-API-AppToken`).\n\n## Common parameters\n\n| Name | Description |\n| -------- | -------- |\n| `accountName` | Account name in VTEX License Manager. |\n| `name` | Data Entity name. |\n| `schema` | JSON Schema of a Data Entity. |\n| `id` | Identifier of a document. |\n| `X-VTEX-API-AppKey` | appKey. |\n| `X-VTEX-API-AppToken` | appToken. | \n\n## Index\n\n### Documents\n\n- `POST` [Create new document](https://developers.vtex.com/docs/api-reference/master-data-api-v2#post-/api/dataentities/-dataEntityName-/documents)\n- `PATCH` [Create partial document](https://developers.vtex.com/docs/api-reference/master-data-api-v2#patch-/api/dataentities/-dataEntityName-/documents)\n- `GET` [Get document](https://developers.vtex.com/docs/api-reference/master-data-api-v2#get-/api/dataentities/-dataEntityName-/documents/-id-)\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-)\n- `PATCH` [Update partial document](https://developers.vtex.com/docs/api-reference/master-data-api-v2#patch-/api/dataentities/-dataEntityName-/documents/-id-)\n- `DELETE` [Delete document](https://developers.vtex.com/docs/api-reference/master-data-api-v2#delete-/api/dataentities/-dataEntityName-/documents/-id-)\n\n### Search\n\n- `GET` [Search documents](https://developers.vtex.com/docs/api-reference/master-data-api-v2#get-/api/dataentities/-dataEntityName-/search)\n\n### Scroll\n\n- `GET` [Scroll documents](https://developers.vtex.com/docs/api-reference/master-data-api-v2#get-/api/dataentities/-dataEntityName-/scroll)\n\n### Schemas\n\n- `GET` [Get schemas](https://developers.vtex.com/docs/api-reference/master-data-api-v2#get-/api/dataentities/-dataEntityName-/schemas)\n- `GET` [Get schema by name](https://developers.vtex.com/docs/api-reference/master-data-api-v2#get-/api/dataentities/-dataEntityName-/schemas/-schemaName-)\n- `PUT` [Save schema by name](https://developers.vtex.com/docs/api-reference/master-data-api-v2#put-/api/dataentities/-dataEntityName-/schemas/-schemaName-)\n- `DELETE` [Delete schema by name](https://developers.vtex.com/docs/api-reference/master-data-api-v2#delete-/api/dataentities/-dataEntityName-/schemas/-schemaName-)\n\n### Indices\n\n- `GET` [Get indices](https://developers.vtex.com/docs/api-reference/master-data-api-v2#get-/api/dataentities/-dataEntityName-/indices)\n- `PUT` [Put indices](https://developers.vtex.com/docs/api-reference/master-data-api-v2#put-/api/dataentities/-dataEntityName-/indices)\n- `GET` [Get index by name](https://developers.vtex.com/docs/api-reference/master-data-api-v2#get-/api/dataentities/-dataEntityName-/indices/-index_name-)\n- `DELETE` [Delete index by name](https://developers.vtex.com/docs/api-reference/master-data-api-v2#delete-/api/dataentities/-dataEntityName-/indices/-index_name-)\n\n### Clusters\n\n- `POST` [Validate document by clusters](https://developers.vtex.com/docs/api-reference/master-data-api-v2#post-/api/dataentities/-dataEntityName-/documents/-id-/clusters)\n\n### Versions\n\n- `GET` [List versions](https://developers.vtex.com/docs/api-reference/master-data-api-v2#get-/api/dataentities/-dataEntityName-/documents/-id-/versions)\n- `GET` [Get version](https://developers.vtex.com/docs/api-reference/master-data-api-v2#get-/api/dataentities/-dataEntityName-/documents/-id-/versions/-versionId-)\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
security:
- appKey: []
  appToken: []
- VtexIdclientAutCookie: []
tags:
- name: Scroll
paths:
  /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.\n\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.\n\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\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`.\n\n## Request examples\n\nFirst request:\n```\n/dataentities/Newsletter/scroll?isCluster=true&_size=250&_fields=email,firstName\n```\n\nRetrieve the token in the header `X-VTEX-MD-TOKEN` from the first request's response and use it to make the following requests.\n\nSubsequent requests:\n```\n/dataentities/Newsletter/scroll?_token={tokenValue}\n``` \n\n## Permissions\n\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:\n\n| **Product** | **Category** | **Resource** |\n| --------------- | ----------------- | ----------------- |\n| Dynamic Storage | Dynamic storage generic resources | **Read only documents** |\n| Dynamic Storage | Dynamic storage generic resources | **Insert or update document (not remove)** |\n| Dynamic Storage | Dynamic storage generic resources | **Full access to all documents** |\n| Dynamic Storage | Dynamic storage generic resources | **Master Data administrator** |\n\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).\n\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
components:
  parameters:
    _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
    _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'
    _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
    dataEntityName:
      name: dataEntityName
      in: path
      required: true
      description: Name of the data entity.
      schema:
        type: string
        example: Newsletter
    _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
    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
    _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
    Content-Type:
      name: Content-Type
      in: header
      description: Type of the content being sent.
      required: true
      style: simple
      schema:
        type: string
        example: application/json
    _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
  schemas:
    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.
  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.'