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/username/list

    Returns entries for the root folder of account username (Only works for current user, right now)

  • GET /api/v1/users/username/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/username/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/username/documents/doc.html

  • GET /api/v1/users/username/documents/doc.svg

  • GET /api/v1/users/username/documents/doc.png

  • POST /api/v1/users/username/documents/doc/token

  • GET /api/v1/users/username/documents/doc/token

Creating documents

Route

POST /api/v1/users/username/documents

Document actions

Route

POST /api/v1/users/username/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

Routes

  • PUT /api/v1/users/username/documents/doc

  • PATCH /api/v1/users/username/documents/doc

  • POST /api/v1/users/username/documents/doc/add-record

Deleting documents

Route

DELETE /api/v1/users/username/documents/doc

Returns

No content upon success.

Working with folders

Routes

  • GET /api/v1/users/username/folders

  • GET /api/v1/users/username/folders/*path

  • PUT /api/v1/users/username/folders/*path

  • DELETE /api/v1/users/username/folders/*path

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 username or organization slug.
  • 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

  • username: The username 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 username, nor email is given, a sharing link is generated and returned as part of the ACE.

Examples:

  1. POST /api/v1/share

    {
  "owner": "alice",
  "document": "T0g2oxgTQFaaONWDe4Spvw",
  "username": "bob"
}

    Will allow read access for Vizzlo user bob for alice's document T0g2oxgTQFaaONWDe4Spvw.

  2. DELETE /api/v1/share

    {
  "owner": "alice",
  "document": "T0g2oxgTQFaaONWDe4Spvw",
  "username": "bob"
}

    Will revoke the access from example 1 again.

  3. POST /api/v1/share

    {
  "owner": "alice",
  "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": "alice",
  "document": "T0g2oxgTQFaaONWDe4Spvw",
  "link": "https://vizzlo.com/share/qfWi7PKiTrChiSjwueFp3Q",
  "mode": "w"
}

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

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

  5. DELETE /api/v1/share

    {
  "owner": "alice",
  "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/username/foreign-folders

    Listing folders shared with specified user

  • DELETE /api/v1/users/username/foreign-folders/owner/*path

    Removing a foreign folder from my “Shared with me” view

  • GET /api/v1/users/username/foreign-documents

    Listing documents shared with current users

  • DELETE /api/v1/users/username/foreign-documents/owner/document

    Removes a foreign document from specified users’ “Shared with me” view

  • GET /api/v1/users/username/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"
      }
    }
  ]
}