Document management

This section specifically only talks about documents that are stored in the Vizzlo Cloud. For other cloud storage providers, please see Cloud Storage.

Listing documents and folders

To list the contents of a users’ folders, the following two actions can be used.

Routes

GET /api/v1/users/id/list

Returns entries for the root folder of account id (Only works for current user, right now)
GET /api/v1/users/id/list/*path

Returns entries for the folder specified by path

Query parameters

Name	Type	Description
offset (optional)	number	Skips this number of results
limit (optional)	number	Limits number of results to this value (default: 10)
match (optional)	string	Matches against folder and document titles

Example

The result is a JSON object, looking roughly like this:

{
  "offset": 0,
  "limit": 10,
  "count": 123,
  "match": "blabalbal",
  "results": [
    {
      "type": "folder",
      "folder": {
        // …
      },
      "urls": {
        "view": "https://vizzlo.com/…",
        "endpoint": "https://vizzlo.com/api/v1/…"
      }
    },
    {
      "type": "document",
      "document": {
        // …
      },
      "urls": {
        "view": "https://vizzlo.com/…",
        "endpoint": "https://vizzlo.com/api/v1/…",
        "thumbnail": "https://vizzlo.com/…/.png"
      }
    }
  ]
}

Downloading documents

Getting the JSON representation of a document

Route

GET /api/v1/users/id/documents/doc

Optional query parameters valid for this action

include_download_url: Includes a tokenized download URL for the given type. Value can be png or svg.
transparent: If given, will include properties background_color and/or background_svg in the response. In this case, the client is reponsible for rendering the background based on these properties, if needed. When a download URL is requested (see above) and this property is given, too, the downloaded SVG or PNG image will have a transparent background.

Getting layouted, renderend, or rastered representations of a document

Routes

GET /api/v1/users/id/documents/doc.html
GET /api/v1/users/id/documents/doc.svg
GET /api/v1/users/id/documents/doc.png
POST /api/v1/users/id/documents/doc/token
GET /api/v1/users/id/documents/doc/token

Creating documents

Route

POST /api/v1/create-document

This endpoint is used to create a new document in the current user’s private space or any team folder they are a member of. The JSON payload needs to contains all necessary information to know where and what kind of document to create.

Payload

vizzard (string): Identifier of the vizzard to use for the newly created document. MUST be specified, if no template given.
template (string): ID of the document to use as template for the newly created document. MUST be specified, if no vizzard given.
owner (string): Account ID of organization or user account to create document in. Optional.
folder (string): Path of folder to create document in. Optional.
provider (string): Cloud storage provider to store document with. Optional, but must be used in conjuction with connection_id.
connection_id (string): Identifier of cloud storage connection to use for storing the document. Optional, but must be used in conjunction with provider.
folder_id (string): Optional, cloud storage-specific identifier of folder to store newly created document in.
layout (object): Optional, layout information for the newly created document. This object needs to contain the following fields: width (document width in points), height (document height in points), and margin (object containing top, right, bottom, and left fields, each specifying the respective document margin in points). If not given, the user’s default layout preset is used.

Returns

Upon success, a JSON object with two fields is returned:

endpoint (string): API endpoint URL of the newly created document.
document_view (string): Document URL of the newly created document. Useful to direct user’s browser directly to the document.

Examples

Creating a new Gantt chart in “My Documents”:
```
{
  "vizzard": "1M2ko1y3Qee4ZiPA0zkzKQ"
}
```

Creating a new Gantt in the “Marketing” teams folder:

{
  "vizzard": "1M2ko1y3Qee4ZiPA0zkzKQ",
  "owner": "abc0123456789",
  "folder": "marketing"
}

Creating new Gantt in a connected Google Drive:

{
  "vizzard": "1M2ko1y3Qee4ZiPA0zkzKQ",
  "provider": "googledrive",
  "connection_id": "7_EptI5mTNeTb2bWKsRYug"
}

Creating new document in Marketing team’s folder “XXX” from a template document:

{
  "template": "abcdefghijkl0123456789",
  "owner": "abc0123456789",
  "folder": "marketing/XXX"
}

Document actions

Route

POST /api/v1/users/id/documents/doc

This endpoint is used to trigger document-specific actions on the platform. The action is send as parameter action of the JSON payload of the request.

Closing a document

When a document is closed on the client side, a “close” action should be performed, to trigger generating an up-to-date thumbnail, etc. of the document.

Payload

{
  "action": "close"
}

Returns

No content upon success.

Forking an existing document

Also known as “Duplicate document” or “Make a copy” functionality, this action will create a fork of the document in the same folder (if the current user has write rights to that folder) or in the current user’s root directory.

Payload

{
  "action": "fork"
}

Returns

A JSON representation of the fork. Exactly the same output as if requesting that fork using link:#downloading-documents[a GET request].

Modifying documents

Updating an existing document

Allows you to update all content of an existing Vizzlo document. Most prominently, you might want to change the (Vizzard-specific) data and settings fields.

Route

PUT /api/v1/users/id/documents/doc

Payload

{
  "plugin_id": "XXXXXXXXXXXXXXXXXXXXXX",
  "settings": {
    "key1": "value1",
    "key2": "value2",
    "key3": "value3"
  },
  "data": [
    {
      "key1": "value1",
      "key2": "value2",
      "key3": "value3"
    },
    {
      "key1": "value1",
      "key2": "value2",
      "key3": "value3"
    }
  ],
  "title": "My Vizzlo document",
  "theme": "business-blue",
  "custom_theme": {
    "TBD": "TBD"
  },
  "style": {
    "no_title": false,
    "no_branding": false,
    "subtitle": "My document's <u>subtitle</u>",
    "footer": "Footer content <b>HTML</b>",
    "annotations": [
      {
        "": ""
      }
    ],
    "description": "This document's meta description.",
    "width": 960,
    "height": 540,
    "margin": [
      {
        "": ""
      }
    ]
  }
}

Returns

{
  "path": "/d/XXXXXXXXXXXXXXXXXXXXXX",
  "timestamp": "1234567890",
  "urls": {
    "endpoint": "/api/v1/users/XXXXXXXXXXXXX/documents/XXXXXXXXXXXXXXXXXXXXXX",
    "document_view": "https://vizzlo.com/d/XXXXXXXXXXXXXXXXXXXXXX",
    "parent_folder": "https://vizzlo.com/documents/XXXXXXXX/XXXXXXXXXXXXXXXXXXX",
    "parent_folder_title": "Bakery Project"
  }
}

Moving or renaming existing documents

Route

PATCH /api/v1/users/id/documents/doc

Payload

The JSON payload for this PATCH request allows moving a document to a different folder (optionally in a different account) and/or renaming it:

{
  "folder": "/XXXXXXXX/XXXXXXXXXXXXXXXXXXX",
  "owner": "XXXXXXXXXXXXX",
  "title": "XXX XXXXXXXXX XXXXXXXX"
}

Returns

{
  "path": "/d/XXXXXXXXXXXXXXXXXXXXXX",
  "timestamp": "1234567890"
}

Adding a new record to an existing document

Allows you to add a single new records to the data of an existng document without changing anything else.

Route

POST /api/v1/users/id/documents/doc/add-record

Payload

TBD

Returns

TBD

Deleting documents

Route

DELETE /api/v1/users/id/documents/doc

Returns

No content upon success.

Restoring documents from trash bin

Route

POST /api/v1/users/id/documents/doc

Payload

{
  "action": "restore"
}

Returns

No content upon success.

Expunging documents from trash bin

Route

DELETE /api/v1/users/id/documents/doc?expunge=1

Returns

No content upon success.

Working with folders

Routes

GET /api/v1/users/id/folders
GET /api/v1/users/id/folders/*path
PUT /api/v1/users/id/folders/*path
POST /api/v1/users/id/folders/*path
DELETE /api/v1/users/id/folders/*path

Duplicating folders

Route

POST /api/v1/users/id/folders/*path

Payload

{
  "action": "duplicate"
}

Returns

A JSON object is returned which contains the following fields:

name (string): Absolute path of the newly-created folder. This name might include a number if the requested name already existed. (Example: “Copy of Revenue Reporting 2”)
endpoint (string): API endpoint of the newly-created folder.
view (string): View URL of the newly created folder. Useful to direct user’s browser directly to the dashboard with the respective folder open.

Deleting folders

Route

DELETE /api/v1/users/id/folders/*path

Returns

No content upon success.

Restoring folders from trash bin

Route

POST /api/v1/users/id/folders/*path

Payload

{
  "action": "restore"
}

Returns

No content upon success.

Expunging folders from trash bin

The folder and all its contents will permanently be deleted from the system.

Route

DELETE /api/v1/users/id/folders/*path?expunge=1

Returns

No content upon success.

The access control list (ACL) of documents and folders (see acl property when GETting folder or documents) can be modified by POSTing or DELETEing single access control entries.

Routes

POST /api/v1/share
PATCH /api/v1/share
DELETE /api/v1/share

A request object always contains these properties:

owner: Owner of the document or folder to share. This is the user or organization identifier.
document or folder: The UUID of the document or the absolute path folder to share.
mode (optional): Access mode to enable. Might be r for read-only mode (the default) or w for read/write access.

When creating new (POST) or updating existing (PATCH) access control entries, the result of this request will always the full access control entry (ACE). In case of a successful DELETE request, HTTP 204 No Content will be returned.

Based on the additional properties, these are the different types of sharing requests you can make:

user_id: The ID of the Vizzlo user to share the document or folder with

email: Email address of the user to invite to Vizzlo.

A unique token will be generated that is sent by mail. Should the recipient already have a Vizzlo account, they will just be logged into their account by clicking the link and be added to the ACL as a Vizzlo user.

If neither user_id, nor email is given, a sharing link is generated and returned as part of the ACE.

Examples:

POST /api/v1/share
```
{
  "owner": "qdjn7notricsy",
  "document": "T0g2oxgTQFaaONWDe4Spvw",
  "user_id": "rxv242bf5t7c2"
}
```
Will allow read access for Vizzlo user rxv242bf5t7c2 to qdjn7notricsy’s document T0g2oxgTQFaaONWDe4Spvw.

DELETE /api/v1/share

{
  "owner": "qdjn7notricsy",
  "document": "T0g2oxgTQFaaONWDe4Spvw",
  "user_id": "rxv242bf5t7c2"
}

Will revoke the access from example 1 again.

POST /api/v1/share

{
  "owner": "qdjn7notricsy",
  "document": "T0g2oxgTQFaaONWDe4Spvw"
}

Will create a sharing link with read access and return:

{
  "mode": "r",
  "link": "https://vizzlo.com/share/qfWi7PKiTrChiSjwueFp3Q"
}

PATCH /api/v1/share

{
  "owner": "qdjn7notricsy",
  "document": "T0g2oxgTQFaaONWDe4Spvw",
  "link": "https://vizzlo.com/share/qfWi7PKiTrChiSjwueFp3Q",
  "mode": "w"
}

Will upgrade the existing permission to write access and return the ACE.

{
  "owner": "qdjn7notricsy",
  "document": "T0g2oxgTQFaaONWDe4Spvw",
  "link": "https://vizzlo.com/share/qfWi7PKiTrChiSjwueFp3Q",
  "mode": "w"
}

DELETE /api/v1/share

{
  "owner": "qdjn7notricsy",
  "document": "T0g2oxgTQFaaONWDe4Spvw",
  "link": "https://vizzlo.com/share/qfWi7PKiTrChiSjwueFp3Q"
}

Will revoke the access from example 3 again.

Listing things shared with me

Routes

GET /api/v1/users/id/foreign-folders

Listing folders shared with specified user
DELETE /api/v1/users/id/foreign-folders/owner/*path

Removing a foreign folder from my “Shared with me” view
GET /api/v1/users/id/foreign-documents

Listing documents shared with current users
DELETE /api/v1/users/id/foreign-documents/owner/document

Removes a foreign document from specified users’ “Shared with me” view
GET /api/v1/users/id/visible-folders

Lists folders visible to the specified user, needed to contruct a tree of possible targets for copying/moving things to

Search

Route

GET /api/v1/search

Query parameters valid for this action

query (mandatory): Matches against folder and document titles
offset: Skips this number of results
limit: Limits number of results to this value (default: 10)

The result is a JSON object, looking roughly like this

{
  "offset": 0,
  "limit": 10,
  "count": 123,
  "query": "blabalbal",
  "results": [
    {
      "type": "folder",
      "folder": {
        // …
      },
      "urls": {
        "view": "https://vizzlo.com/…",
        "endpoint": "https://vizzlo.com/api/v1/…"
      }
    },
    {
      "type": "document",
      "document": {
        // …
      },
      "urls": {
        "view": "https://vizzlo.com/…",
        "endpoint": "https://vizzlo.com/api/v1/…",
        "thumbnail": "https://vizzlo.com/…/.png"
      }
    }
  ]
}

Document management

Listing documents and folders

Routes

Query parameters

Example

Downloading documents

Getting the JSON representation of a document

Route

Optional query parameters valid for this action

Getting layouted, renderend, or rastered representations of a document

Routes

Creating documents

Route

Payload

Returns

Examples

Document actions

Route

Closing a document

Payload

Returns

Forking an existing document

Payload

Returns

Modifying documents

Updating an existing document

Route

Payload

Returns

Moving or renaming existing documents

Route

Payload

Returns

Adding a new record to an existing document

Route

Payload

Returns

Deleting documents

Route

Returns

Restoring documents from trash bin

Route

Payload

Returns

Expunging documents from trash bin

Route

Returns

Working with folders

Routes

Duplicating folders

Route

Payload

Returns

Deleting folders

Route

Returns

Restoring folders from trash bin

Route

Payload

Returns

Expunging folders from trash bin

Route

Returns

Sharing documents and folders

Routes

Sharing with Vizzlo users

Sharing with external users (by email address)

Generating a link for sharing

Examples:

Listing things shared with me

Routes

Search

Route

Query parameters valid for this action

The result is a JSON object, looking roughly like this