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

  • 7 February 2023
  • 3 replies

Userlevel 3
Badge +7

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. 


403 Forbidden

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

429 Too Many Requests

if the account makes more than 100 requests in 5 seconds


Badge +1

Hello, i try to use api https://api.lucid.co/documents/<id document>/contents but allways generate a 403 forbidden. I test the access by the url how to show in your post and i have access…. i have the permissions. What happened in this situatión?

Thank you

Userlevel 2
Badge +2

Hi @ljarami, thanks for posting in the community! Could you confirm that you have the correct access token type and access token scope for your OAuth token? For the Document contents endpoint, you’ll need to make sure the request is using the User access token type and these access scopes: lucidchart.document.content:readonlylucidchart.document.app.picker:readonlylucidchart.document.app.folder

You may also want to make sure that you are authorizing the Oauth token with the Lucid account that has access to the document. 

If this doesn’t help, would you mind sharing the temporary Support PIN for this document? This will allow me to take a closer look at the issue you’re experiencing.

For more information on generating a Support PIN, check out this Help Center article. This Support PIN doesn’t allow anyone but Lucid Support to take a look at your document, so you are safe to post it here.

Feel free to let us know if you have any additional questions!

Badge +1

thank you so much…