Skip to main content

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’:

tzACa0QbPLPvFhFvLFzG7g.png

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

sW9hS1gxv5oftDDLTLKPPQ.png

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:

Yi9xYc7xDhQsL0r2sVbQsg.png

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:
      E5Tzu3GjSez7UdSCe08Zyw.png
    2. The owner of the document removed you as a collaborator:
      rXFkmJvAkdYkaSTrFboegA.png
    3. You do not have access to the document at all and the owner must share the document with you:
      140il3gD10FL3gIUbgmv0Q.png

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

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


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!


thank you so much… 


What about Lucidspark documents? Why is this export not supported for Lucidspark documents?

 

Response from Lucid Server after requesting a document:

{"code":"badRequest","message":"Bad or malformed request","requestId":"7a0eea68c00da769","details":{"error":"Only Lucidchart documents are supported."}}


Hello ralfpanse,

 

Lucidspark documents will be supported as well in a future update. I do not have a ETA at this time, but we will announce in the forums when its available.


Thanks for this explanation. I tried it on a document and it works perfect! Now I wonder if it is possible to extract to what link (URL) a shape points too? I mainly need this to know about how much links are used and which of them are outdated. Any chance to get this info?

In addition I have a doc where comments were used for annotations. here I need to run similar checks of how many annotations we have an check consistency. So how can I read comments via this (or other) API endpoint?

 

Thx!


Hi tobi,

You can get some limited information about URLs by converting shapes with links into embedded links. This will change the shape type to be `LinkUnfurlBlock`, but will still not give the address the link points to. There is currently no way to retrieve this information through Lucid’s APIs.

Similarly, Lucid’s APIs don’t offer any way to see comments on a document, but we will take your suggestion into consideration.


hey @Trevor J 

Thanks for your quick reply. That’s what I thought - bummer. Now I’m looking into if `customData` could be an option. In addition I figured the PDF export contains the links, but then I learned the API doesn’t support PDF export :(

So nevertheless, thanks for taking it into consideration, please let me know if one or the other new feature appears on the API.

 


Reply