BETA - Please note, that the Gliffy API is currently in BETA testing. There may be minor changes to the API that are likely to occur before the product leaves BETA.

Document

Currently, a document is a diagram, and diagrams are what Gliffy is all about. A Document can be created, viewed, or edited.

Method Summary

+List Documents in an Account

This is a basic document query service that lists all documents in the account.

Request URL

HTTP METHOD URL
GET or POST $API_ROOT/accounts/$YOUR_ACCOUNT_ID/documents.xml?action=get

Parameters

PARAMETER REQUIRED POSSIBLE VALUES DESCRIPTION
get Yes get
public no true | false If "true", only documents that are public are returned in the given account. If "false", only non-public documents in the account are returned. If omitted, all documents are returned

Example Response containing <documents>, and a single <document> 

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<response xmlns="http://www.gliffy.com" success="true"> 
    <documents> 
        <document num-versions="2" id="1000003"> 
            <name>Booze DB</name> 
            <mod-date>1215538283000</mod-date> 
            <create-date>1215538283000</create-date> 
            <published-date>1215538283000</published-date> 
            <owner id="208"> 
                <username>moe</username> 
                <email>moe@BurnsODyne.apiuser.gliffy.com</email> 
            </owner> 
        </document> 
        <document is-public="true" num-versions="4" id="1000000"> 
            <name>Hounds Room</name> 
            <mod-date>1215538283000</mod-date> 
            <create-date>1215538283000</create-date> 
            <published-date>1215538283000</published-date> 
            <owner id="202"> 
                <username>monty</username> 
                <email>monty@BurnsODyne.apiuser.gliffy.com</email> 
            </owner> 
        </document> 
    </documents> 
</response>

+Get meta-data for a single Document

You may wish to get meta-data about one document in particular and not have to sort through the entire list.

Request URL

HTTP METHOD URL
GET or POST $API_ROOT/accounts/$YOUR_ACCOUNT_ID/documents/$DOCUMENT_ID/meta-data.xml?action=get

Parameters

PARAMETER REQUIRED POSSIBLE VALUES DESCRIPTION
get Yes get
showRevisions no true | false If true, show a nested list of the document revisions or versions, with meta-data for each.

Example Response containing <documents> 

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<response xmlns="http://www.gliffy.com" success="true"> 
    <documents> 
        <document is-public="true" num-versions="2" id="1000003"> 
            <name>Booze DB</name> 
            <mod-date>1215538283000</mod-date> 
            <create-date>1215538283000</create-date> 
            <published-date>1215538283000</published-date> 
            <owner id="208"> 
                <username>moe</username> 
                <email>moe@BurnsODyne.apiuser.gliffy.com</email> 
            </owner> 
			<versions>
				<version id="1000002">
					<num>1</num>
					<create-date>1215538283000</create-date>
					<owner id="208">   
						<username>moe</username>   
						<email>moe@BurnsODyne.apiuser.gliffy.com</email>   
					</owner>
				</version>
				<version id="1000026">
					<num>2</num>
					<create-date>121559943322</create-date>
					<owner id="208">   
						<username>moe</username>   
						<email>moe@BurnsODyne.apiuser.gliffy.com</email>   
					</owner>
				</version>
			</versions>
        </document> 
    </documents> 
</response>

+Create a new Document

In Gliffy, you must explicitly create a document before editing it. See getting the Gliffy Editor Launch Link to enable your users to edit a document. Diagrams are private by default in Premium accounts, and public by default in Basic accounts. Before creating a diagram, it's a good idea to check the Account status so that you know if the Diagram will be public or private. Your users will want to know!

Request URL

HTTP METHOD URL
POST $API_ROOT/accounts/$YOUR_ACCOUNT_ID/documents.xml?action=create&documentName=$NEW_NAME&documentType=diagram

Parameters

PARAMETER REQUIRED POSSIBLE VALUES DESCRIPTION
action yes create
documentName yes Any string The name of the document
documentType yes diagram The type of the document
templateDiagramId no any diagram id If document is a diagram, the id of a diagram that should serve as the initial version of the new diagram (this is how you can achieve "copying" of diagrams).
folderPath no The path to a folder in your account that the logged-in user has access to initial folder the document will live in. The requesting user must have access to this folder (and it must exist, as well). If this is omitted, it will go in your account's default folder (which is ROOT)

Example Response containing <documents>, and a single <document> that was created 

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<response xmlns="http://www.gliffy.com" success="true"> 
    <documents> 
        <document num-versions="2" id="1000003"> 
            <name>Booze DB</name> 
            <mod-date>1215538283000</mod-date> 
            <create-date>1215538283000</create-date> 
            <published-date>1215538283000</published-date> 
            <owner id="208"> 
                <username>moe</username> 
                <email>moe@BurnsODyne.apiuser.gliffy.com</email> 
            </owner> 
        </document> 
    </documents> 
</response>

+Get a diagram Document as XML, SVG, or as an image

This can be used in several ways. The simplest is to put this inside an HTML <img> tag to render the diagram inline with some text. You can also use this to download the image bytes for client-side caching, or to get an SVG version of the diagram, for import into Visio. As such, this call supports conditional GET, meaning you can cache either the last modification time or the entity tag and use them in your request to save network bandwidth

Request URL

HTTP METHOD URL
GET or POST $API_ROOT/accounts/$YOUR_ACCOUNT_ID/documents/$DOCUMENT_ID.$EXTENSION?action=get

Parameters

PARAMETER REQUIRED POSSIBLE VALUES DESCRIPTION
action Yes get
size no
  • L - full size
  • M - medium size (relative to full size)
  • S - small size (relative to full size)
  • T - thumbnail (fixed small size)
 for rastered representation types (JPEG or PNG), this controls the size of the returned image. Ignored for SVG and XML.
version no a number if present, represents the version of the diagram to retrieve. The first version is version '1'. If omitted, the current version is retrieved.

Extension Types for File Formats

This table below shows the possible values for $EXTENSION

FORMAT MIME TYPE VALUE EXTENSION DESCRIPTION DEFAULT
JPEG image/jpeg .jpg Diagram as JPEG image no
PNG image/png .png Diagram as a PNG image no
SVG image/svg+xml .svg Vector format that is suitable for importing into Visio, or high-resolution printing no
GliffyXML text/xml .xml This is the Gliffy native XML format. This is the Gliffy native XML format but is subject to change and should not be relied upon. yes

+Update Document meta-data

You can rename a document at any time, and you can also make it public (or make it private to your account).

Request URL

HTTP METHOD URL
POST $API_ROOT/accounts/$YOUR_ACCOUNT_ID/documents/$DOCUMENT_ID/meta-data.xml?action=update

Parameters

PARAMETER REQUIRED POSSIBLE VALUES DESCRIPTION
action Yes update
documentName no any string the new name of the document. If omitted, the name will not be changed.
public no true | false If "true", this document will be made public; anyone on the internet can view it or use it as a template (you still retain rights to modify it, however). If "false", this document will be made "private" (it will still be accessible to anyone in your account with access to the folder in which the document resides). If omitted, the "publicness" of the document will not be changed

Example of successful <response> 

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<response xmlns="http://www.gliffy.com" success="true" />

+Update Document content

Update the content of a document. This will create a new revision of the document being updated. WARNING!
We do not recommend that you programatically modify the content of the document because validation of the content is not currently conducted AND we fully expect the current document format to change.

Request URL

HTTP METHOD URL
POST $API_ROOT/accounts/$YOUR_ACCOUNT_ID/documents/$DOCUMENT_ID.xml?action=update&content=$CONTENT_AS_XML

Parameters

PARAMETER REQUIRED POSSIBLE VALUES DESCRIPTION
action yes update
content yes XML of the new document content

Example of successful <response> 

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<response xmlns="http://www.gliffy.com" success="true"> 
    <documents> 
        <document num-versions="3" id="1000003"> 
            <name>Booze DB</name> 
            <mod-date>1215538283000</mod-date> 
            <create-date>1215538283000</create-date> 
            <published-date>1215538283000</published-date> 
            <owner id="208"> 
                <username>moe</username> 
                <email>moe@BurnsODyne.apiuser.gliffy.com</email> 
            </owner> 
        </document> 
    </documents> 
</response>

+Delete a Document

WARNING:This cannot be undone

Request URL

HTTP METHOD URL
DELETE or POST $API_ROOT/accounts/$YOUR_ACCOUNT_ID/documents/$DOCUMENT_ID.xml?action=delete

Parameters

PARAMETER REQUIRED POSSIBLE VALUES DESCRIPTION
action yes delete

Example of successful <response> after a deletion

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<response xmlns="http://www.gliffy.com" success="true" />

+Put a Document in a different Folder

A document can exist in one and only one folder

Request URL

HTTP METHOD URL
POST $API_ROOT/accounts/$YOUR_ACCOUNT_ID/folders/$FOLDER_PATH/documents/$DOCUMENT_ID.xml?action=move

Parameters

PARAMETER REQUIRED POSSIBLE VALUES DESCRIPTION
action yes move

Example of successful <response> after a moving diagram

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<response xmlns="http://www.gliffy.com" success="true" />
Gliffy Developer Program
REST API Documentation