Tutorial: How to retrieve a JSON of any Lucidchart document with the Document Contents request

Are you building an application with Lucid’s external APIs that uses our Document Contents endpoint? The Document Contents endpoint uses an OAuth token with User access scope to return a JSON that describes any document accessible by the User associated with the OAuth token. Read on for more information on what to expect in the response and what to do if you return an error.

Let’s take a look at a snippet from the JSON response for an example flowchart document to illustrate how the shapes on the canvas will be represented on the JSON. The magnifying glass in the screenshot below is covering a terminator shape labeled ‘Request complete’:

The document content within the magnifying glass will be represented in the JSON as shown in the screenshot below:

The object class (TerminatorBlock) is indicated as is the unique ItemId (q7NtnToLUGX9). Every individual shape line group and layer represented in the response will contain a unique value for ItemId to identify the object. For more details on document properties please review our Document Content resource and comment below if you have any questions or concerns.

You may notice that the shape’s location on the canvas is not included however its relative position in the flowchart can be seen if you look at the information returned for the line object:

We can see in endpoint2 that the terminator shape is referenced by its ItemID and that this line also connects to shape ID: q7NtHu9fbiOH at endpoint2.

The following information is not included in the response: 

• Who the document is shared with when it was last modified and other document metadata  (use our Get Document endpoint for when a document was last modified and our Collaborator endpoints for details on a document’s collaborators)
• Shape and text formatting (e.g. color font) size and absolute location on the canvas

If you don’t receive a 200 response consider the tips below:

403 Forbidden

This indicates that the app making the request does not have permission to the document or the document has been deleted or does not exist. 

If you’re not sure where the root cause lies 

1. Open your browser and sign into the Lucid user account that you used for the browser authorization step when you obtained the OAuth2 access token.
2. Grab the id parameter you included in the request and paste it into the following URL replacing <doc id>: https://lucid.app/lucidchart/<doc id>/edit?
3. If the user does not have permission to view the document there are three possible reasons:

1. Document was deleted:
   
2. The owner of the document removed you as a collaborator:
   
3. You do not have access to the document at all and the owner must share the document with you:
   

If you need help identifying the owner of a given Lucidchart document please contact your Lucid Administrator - Document Admins and your Account Owner may lookup documents by title with our Document Discovery feature.

429 Too Many Requests

This endpoint has a rate limit of 100 requests per 5 seconds per account.