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
Query parameters
NameTypeDescription
offset (optional)numberSkips this number of results
limit (optional)numberLimits number of results to this value (default: 10)
match (optional)stringMatches 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

Getting layouted, renderend, or rastered representations of a document

Routes

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
Returns

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

Examples

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

Optionally, a history_version (number) can be added to the payload to fork from a specific point in the document’s version history instead of its current state.

There is also a closely related duplicate action that behaves like fork but is tracked separately (it is the “Make a copy” action offered in the UI):

{
  "action": "duplicate"
}
Returns

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.

For backwards compatibility, this endpoint replaces the whole document: any field you omit is reset to its zero value (with the exception of custom_theme and style, which are only applied when present). To make sure you don’t lose data, always send the complete document representation.

Route

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

Payload
NameTypeDescription
plugin_idstringID of the plugin (Vizzard) the document uses. If given, the document is migrated to this plugin.
titlestringTitle of the document.
settingsobjectPlugin-specific settings object.
dataarrayPlugin-specific array of data records.
themestringIdentifier of the theme to use (see Managing organization themes).
custom_themeobjectOptional: An inline theme definition, used instead of a named theme.
styleobjectOptional: Document style and layout (see below). Only applied when present.
svgstringOptional: Pre-rendered SVG of the document. If omitted, the server re-renders on demand.
isPublicbooleanWhether the document is publicly accessible. May be forced to false by organization policy.
ownerstringOptional: Account ID to move the document to while updating.
versionnumberOptional: Document schema version. When > 0, only that version is written; when omitted the whole document is replaced.
final_savebooleanOptional: Signals the last save of an editing session (e.g. triggers thumbnail regeneration).

The optional style object may contain the following fields (all optional):

NameTypeDescription
no_titlebooleanHide the document title.
no_brandingbooleanHide the Vizzlo branding.
no_footnotebooleanHide the footer.
subtitlestringDocument subtitle (may contain simple HTML).
footerstringFooter content (may contain simple HTML).
descriptionstringMeta description of the document.
annotationsarrayArray of annotation objects.
custom_colorsarrayArray of custom color strings.
widthnumberDocument width in points.
heightnumberDocument height in points.
marginobjectDocument margins in points, an object with top, right, bottom, and left keys.
{
  "plugin_id": "1M2ko1y3Qee4ZiPA0zkzKQ",
  "title": "My Vizzlo document",
  "settings": {
    "showLegend": true
  },
  "data": [
    { "label": "Q1", "value": 12 },
    { "label": "Q2", "value": 34 }
  ],
  "theme": "business-blue",
  "isPublic": false,
  "style": {
    "no_title": false,
    "no_branding": false,
    "subtitle": "My document's <u>subtitle</u>",
    "footer": "Footer content <b>HTML</b>",
    "description": "This document's meta description.",
    "annotations": [],
    "width": 960,
    "height": 540,
    "margin": {
      "top": 40,
      "right": 40,
      "bottom": 40,
      "left": 40
    }
  }
}
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
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"
}
Moving only (without renaming)

There is also a dedicated endpoint that only moves a document (to another folder and/or account) but does not rename it:

Payload
{
  "folder": "/XXXXXXXX/XXXXXXXXXXXXXXXXXXX",
  "owner": "XXXXXXXXXXXXX"
}
Returns

A JSON object containing the document’s new path, owner, timestamp, urls, and acl.

Adding a new record to an existing document

Allows you to add a single new record to the data of an existing document without changing anything else. This is a convenient shortcut for appending to a document (for example, adding a task to a Gantt chart) without having to send the full document as you would with a PUT request.

You need write access to the document; the document must not be deleted.

Route
Payload

A single JSON object representing the new data record. Its shape is Vizzard-specific and matches one element of the document’s data array. It is appended to the end of data.

{
  "label": "Q3",
  "value": 56
}
Returns

No content (HTTP status code 204) upon success.

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

Duplicating folders

Route

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

Payload
{
  "action": "duplicate"
}
Returns

A JSON object is returned which contains the following fields:

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

A request object always contains these properties:

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

Sharing with external users (by email address)

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
Route

GET /api/v1/search

Query parameters valid for this action
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"
      }
    }
  ]
}