This section specifically only talks about documents that are stored in the Vizzlo Cloud. For other cloud storage providers, please see Cloud Storage.
To list the contents of a users’ folders, the following two actions can be used.
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
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 |
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"
}
}
]
}
GET /api/v1/users/
id
/documents/doc
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.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
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.
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.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.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"
}
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.
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.
{
"action": "close"
}
No content upon success.
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.
{
"action": "fork"
}
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.
PUT /api/v1/users/
id
/documents/doc
{
"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": [
{
"": ""
}
]
}
}
{
"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"
}
}
PATCH /api/v1/users/
id
/documents/doc
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"
}
{
"path": "/d/XXXXXXXXXXXXXXXXXXXXXX",
"timestamp": "1234567890"
}
Allows you to add a single new records to the data
of an existng document without changing anything else.
POST /api/v1/users/
id
/documents/doc
/add-record
TBD
TBD
DELETE /api/v1/users/
id
/documents/doc
No content upon success.
POST /api/v1/users/
id
/documents/doc
{
"action": "restore"
}
No content upon success.
DELETE /api/v1/users/
id
/documents/doc
?expunge=1
No content upon success.
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
POST /api/v1/users/
id
/folders/*path
{
"action": "duplicate"
}
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.DELETE /api/v1/users/
id
/folders/*path
No content upon success.
POST /api/v1/users/
id
/folders/*path
{
"action": "restore"
}
No content upon success.
The folder and all its contents will permanently be deleted from the system.
DELETE /api/v1/users/
id
/folders/*path
?expunge=1
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.
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 withemail
: 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.
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.
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
GET /api/v1/search
query
(mandatory): Matches against folder and document titlesoffset
: Skips this number of resultslimit
: Limits number of results to this value (default: 10){
"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"
}
}
]
}