# List grouped documents

- Operation ID: `previewListOfDocumentsGroupedByGroup`
- HTTP method: `POST`
- Path: `/schema-service/v2/documents/preview/grouped-by/groups/list`
- [Human-readable API reference](https://hub.synerise.com/api-reference/asset-management#tag/Documents/operation/previewListOfDocumentsGroupedByGroup)

## Self-contained OpenAPI method

The fenced document below contains this method's documentation and all of its local references. It is self-contained; no category or master specification fetch is required.

```yaml
openapi: 3.0.0
info:
  title: Synerise Public API
  version: 1.9.5
paths:
  /schema-service/v2/documents/preview/grouped-by/groups/list:
    post:
      tags:
        - Documents
      summary: List grouped documents
      description: |
        Retrieve a group or groups of documents with information about the documents in those groups and relations between them. The response is an array of arrays (groups) of objects (documents).

        ---

        **API consumers:** <a href="/api-reference/authorization?tag=Authorization&amp;operationId=profileLogin" target="_blank" rel="noopener">Workspace (Business Profile)</a>, <a href="/api-reference/authorization?tag=Authorization&amp;operationId=userLogin" target="_blank" rel="noopener">Synerise User</a>

        **API key permission required:** `SCHEMA_SERVICE_SCHEMA_READ`

        **User role permission required:** `assets_docs: read`
      operationId: previewListOfDocumentsGroupedByGroup
      security:
        - JWT: []
        - BasicAuth: []
      requestBody:
        content:
          application/json:
            schema:
              type: array
              items:
                type: string
                format: uuid
                description: UUID of a document group
      responses:
        "200":
          description: List of document groups
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  required:
                    - id
                    - name
                    - children
                  properties:
                    id:
                      type: string
                      format: uuid
                      description: UUID of a document group
                    name:
                      type: string
                      description: Group name
                    children:
                      type: array
                      description: An array of documents in the group
                      items:
                        type: object
                        description: Details of a single document
                        required:
                          - id
                          - name
                          - status
                          - priority
                          - children
                        properties:
                          id:
                            type: string
                            format: uuid
                            description: UUID of the document
                          name:
                            type: string
                            description: Name of the document
                          status:
                            type: string
                            enum:
                              - DRAFT
                              - ACTIVE
                              - SCHEDULED
                              - PAUSED
                              - FINISHED
                            description: Filter by status
                          priority:
                            type: integer
                            format: int32
                            maximum: 100
                            description: Priority of the document
                          children:
                            type: array
                            description: Documents that are included in the body of this document
                            items:
                              type: object
                              description: Details of a single document
                              required:
                                - id
                                - name
                                - status
                                - priority
                                - children
                              properties:
                                id:
                                  type: string
                                  format: uuid
                                  description: UUID of the document
                                name:
                                  type: string
                                  description: Name of the document
                                status:
                                  type: string
                                  enum:
                                    - DRAFT
                                    - ACTIVE
                                    - SCHEDULED
                                    - PAUSED
                                    - FINISHED
                                  description: Filter by status
                                priority:
                                  type: integer
                                  format: int32
                                  maximum: 100
                                  description: Priority of the document
                                children:
                                  type: array
                                  description: Documents that are included in the body of this document. This is a recursive schema, `children` may have their own `children`.
                                  items:
                                    $ref: "#/components/schemas/schema-service-DocumentPreviewGroup"
        "400":
          description: See error message for details
          content:
            application/json:
              schema:
                type: object
                properties:
                  timestamp:
                    type: string
                    format: date-time
                    description: Time when the error occurred
                  errorCode:
                    type: string
                    description: |
                      Code of the error, needed for troubleshooting

                      See error reference: [https://developers.synerise.com/errors.html](https://developers.synerise.com/errors.html)
                  status:
                    type: integer
                    description: Error's HTTP status code
                  message:
                    type: string
                    description: Description of the problem
        "401":
          description: "Unauthorized: wrong consumer scope; token missing/expired/invalid; invalid API key; etc."
          content:
            application/json:
              schema:
                type: object
                properties:
                  timestamp:
                    type: string
                    description: Time when the error occurred
                  error:
                    type: string
                    description: Summary of the error
                  message:
                    type: string
                    description: Description of the problem
                  status:
                    type: integer
                    format: int32
                    description: HTTP status code
        "403":
          description: Forbidden; insufficient permissions
          content:
            application/json:
              schema:
                type: object
                properties:
                  timestamp:
                    type: string
                    description: Time when the error occurred
                  error:
                    type: string
                    description: Summary of the error
                  message:
                    type: string
                    description: Description of the problem
                  status:
                    type: integer
                    format: int32
                    description: HTTP status code
        "404":
          description: Resource not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  timestamp:
                    type: string
                    format: date-time
                    description: Time when the error occurred
                  errorCode:
                    type: string
                    description: |
                      Code of the error, needed for troubleshooting

                      See error reference: [https://developers.synerise.com/errors.html](https://developers.synerise.com/errors.html)
                  status:
                    type: integer
                    description: Error's HTTP status code
                  message:
                    type: string
                    description: Description of the problem
        "500":
          description: See error message for details
          content:
            application/json:
              schema:
                type: object
                properties:
                  timestamp:
                    type: string
                    format: date-time
                    description: Time when the error occurred
                  errorCode:
                    type: string
                    description: |
                      Code of the error, needed for troubleshooting

                      See error reference: [https://developers.synerise.com/errors.html](https://developers.synerise.com/errors.html)
                  status:
                    type: integer
                    description: Error's HTTP status code
                  message:
                    type: string
                    description: Description of the problem
      x-snr-doc-urls:
        - /api-reference/asset-management#tag/Documents/operation/previewListOfDocumentsGroupedByGroup
      x-codeSamples:
        - lang: cURL
          label: cURL
          source: |-
            curl --request POST \
              --url https://api.synerise.com/schema-service/v2/documents/preview/grouped-by/groups/list \
              --header 'Authorization: Basic REPLACE_BASIC_AUTH' \
              --header 'content-type: application/json' \
              --data '["497f6eca-6276-4993-bfeb-53cbbbba6f08"]'
        - lang: Python
          label: Python
          source: |-
            import http.client

            conn = http.client.HTTPSConnection("api.synerise.com")

            payload = "[\"497f6eca-6276-4993-bfeb-53cbbbba6f08\"]"

            headers = {
                'Authorization': "Basic REPLACE_BASIC_AUTH",
                'content-type': "application/json"
                }

            conn.request("POST", "/schema-service/v2/documents/preview/grouped-by/groups/list", payload, headers)

            res = conn.getresponse()
            data = res.read()

            print(data.decode("utf-8"))
        - lang: JavaScript
          label: JavaScript
          source: |-
            const data = JSON.stringify([
              "497f6eca-6276-4993-bfeb-53cbbbba6f08"
            ]);

            const xhr = new XMLHttpRequest();
            xhr.withCredentials = true;

            xhr.addEventListener("readystatechange", function () {
              if (this.readyState === this.DONE) {
                console.log(this.responseText);
              }
            });

            xhr.open("POST", "https://api.synerise.com/schema-service/v2/documents/preview/grouped-by/groups/list");
            xhr.setRequestHeader("Authorization", "Basic REPLACE_BASIC_AUTH");
            xhr.setRequestHeader("content-type", "application/json");

            xhr.send(data);
        - lang: Node.js
          label: Node.js
          source: |-
            const http = require("https");

            const options = {
              "method": "POST",
              "hostname": "api.synerise.com",
              "port": null,
              "path": "/schema-service/v2/documents/preview/grouped-by/groups/list",
              "headers": {
                "Authorization": "Basic REPLACE_BASIC_AUTH",
                "content-type": "application/json"
              }
            };

            const req = http.request(options, function (res) {
              const chunks = [];

              res.on("data", function (chunk) {
                chunks.push(chunk);
              });

              res.on("end", function () {
                const body = Buffer.concat(chunks);
                console.log(body.toString());
              });
            });

            req.write(JSON.stringify(['497f6eca-6276-4993-bfeb-53cbbbba6f08']));
            req.end();
        - lang: PHP
          label: PHP
          source: |-
            <?php

            $request = new HttpRequest();
            $request->setUrl('https://api.synerise.com/schema-service/v2/documents/preview/grouped-by/groups/list');
            $request->setMethod(HTTP_METH_POST);

            $request->setHeaders([
              'Authorization' => 'Basic REPLACE_BASIC_AUTH',
              'content-type' => 'application/json'
            ]);

            $request->setBody('["497f6eca-6276-4993-bfeb-53cbbbba6f08"]');

            try {
              $response = $request->send();

              echo $response->getBody();
            } catch (HttpException $ex) {
              echo $ex;
            }
        - lang: Java
          label: Java
          source: |-
            HttpResponse<String> response = Unirest.post("https://api.synerise.com/schema-service/v2/documents/preview/grouped-by/groups/list")
              .header("Authorization", "Basic REPLACE_BASIC_AUTH")
              .header("content-type", "application/json")
              .body("[\"497f6eca-6276-4993-bfeb-53cbbbba6f08\"]")
              .asString();
servers:
  - url: https://api.synerise.com
    description: Microsoft Azure EU
  - url: https://api.azu.synerise.com
    description: Microsoft Azure USA
  - url: https://api.geb.synerise.com
    description: Google Cloud Platform
tags:
  - name: Documents
components:
  schemas:
    schema-service-DocumentPreviewGroup:
      type: object
      description: Details of a single document
      required:
        - id
        - name
        - status
        - priority
        - children
      properties:
        id:
          type: string
          format: uuid
          description: UUID of the document
        name:
          type: string
          description: Name of the document
        status:
          type: string
          enum:
            - DRAFT
            - ACTIVE
            - SCHEDULED
            - PAUSED
            - FINISHED
          description: Filter by status
        priority:
          type: integer
          format: int32
          maximum: 100
          description: Priority of the document
        children:
          type: array
          description: Documents that are included in the body of this document
          items:
            type: object
            description: Details of a single document
            required:
              - id
              - name
              - status
              - priority
              - children
            properties:
              id:
                type: string
                format: uuid
                description: UUID of the document
              name:
                type: string
                description: Name of the document
              status:
                type: string
                enum:
                  - DRAFT
                  - ACTIVE
                  - SCHEDULED
                  - PAUSED
                  - FINISHED
                description: Filter by status
              priority:
                type: integer
                format: int32
                maximum: 100
                description: Priority of the document
              children:
                type: array
                description: Documents that are included in the body of this document. This is a recursive schema, `children` may have their own `children`.
                items:
                  $ref: "#/components/schemas/schema-service-DocumentPreviewGroup"
  securitySchemes:
    JWT:
      type: http
      scheme: bearer
      description: |
        Synerise uses [JSON Web Token (JWT)](https://jwt.io/) as the authorization method.

        The token is generated by the *auth/login* endpoints.

        You need to include it in the `Authorization` header of your requests, with a `Bearer` prefix.


        By default, the token is valid for **one week** (see [workspace settings](https://hub.synerise.com/docs/settings/tool/iam-for-apps/general/#jwt-lifetime)).  
        You can request a refreshed key for the session by using the *auth/refresh* endpoint **before** the current token expires.


        You can verify your JWT signature by using the [public key](https://api.synerise.com/v4/public.pem).


        See Developer Guides on JWT API authentication for:
        - [profiles](https://hub.synerise.com/developers/api/api-authorization/client-login/);
        - [workspaces](https://hub.synerise.com/developers/api/api-authorization/workspace-login/#api-authentication-with-jwt);
        - [users](https://hub.synerise.com/developers/api/api-authorization/user-login/).
    BasicAuth:
      type: http
      scheme: basic
      description: |
        Basic authentication with login (workspace GUID) and password (workspace API key) encoded with Base64 and sent in the `Authorization` header. **Must be enabled in the settings of the API key**.

        <span style="color:red">This is less secure than JWTs.</span> Limit the API key permissions to only those that you need. Consider API key rotation and other security measures.

        You can still use JWTs from the same API key when basic authentication is enabled.

        For details, see ["Workspace authentication"](https://hub.synerise.com/jwt-or-basic/#basic-api-authentication-with-api-keys).
```