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/users/
id
/documents
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"
}
PUT /api/v1/users/
id
/documents/doc
PATCH /api/v1/users/
id
/documents/doc
POST /api/v1/users/
id
/documents/doc
/add-record
DELETE /api/v1/users/
id
/documents/doc
No content upon success.
GET /api/v1/users/
id
/folders
GET /api/v1/users/
id
/folders/*path
PUT /api/v1/users/
id
/folders/*path
DELETE /api/v1/users/
id
/folders/*path
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:
username
: The username 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 username
, nor email
is given, a sharing link is generated and
returned as part of the ACE.
POST /api/v1/share
{
"owner": "alice",
"document": "T0g2oxgTQFaaONWDe4Spvw",
"username": "bob"
}
Will allow read access for Vizzlo user bob
for alice
's document T0g2oxgTQFaaONWDe4Spvw
.
DELETE /api/v1/share
{
"owner": "alice",
"document": "T0g2oxgTQFaaONWDe4Spvw",
"username": "bob"
}
Will revoke the access from example 1 again.
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"
}
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"
}
DELETE /api/v1/share
{
"owner": "alice",
"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"
}
}
]
}