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.

Sharing documents and folders

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:

Sharing with Vizzlo users

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

Sharing with external users (by email address)

  • 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:

  1. POST /api/v1/share

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

    Will allow read access for Vizzlo user rxv242bf5t7c2 to qdjn7notricsy’s document T0g2oxgTQFaaONWDe4Spvw.

  2. DELETE /api/v1/share

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

    Will revoke the access from example 1 again.

  3. 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"
}

  4. 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"
}

  5. 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

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"
      }
    }
  ]
}