Skip to main content
Question

Are the curl examples wrong in the documented endpoints?

  • 27 June 2024
  • 5 replies
  • 90 views

 

I have been checking the documentation for embedding files and it appears that I am supposed to be generating a temporary token that is to be used when embedding files. This is the page I am looking at: https://lucid.readme.io/reference/documentembedstoken

The example curl is:

curl --request POST \
     --url https://api.lucid.co/embeds/token \
     --header 'accept: application/jwt' \
     --header 'authorization: Bearer oauth2-...' \
     --header 'content-type: application/json'

This curl seems to be incorrect/missing data, as when I use the example I get the error The requested resource requires a valid Lucid-Api-Version header. So, I pass this header: Lucid-Api-Version: 1 in the curl (which I am assuming is correct but there is no good way for me to be sure) and I get the error Missing or invalid access token despite me passing in a valid access token. In addition, the documentation says I need to pass a body, including `origin`, and `embedId` (as optional) which is not included in the example despite `origin` being a required field.

So I change the curl on my side to something like this, but I still get a “Missing or invalid access token” error, though I have confirmed this access token is correct via other endpoints.

curl --request POST \
     --url https://api.lucid.co/embeds/token \
     --header 'accept: application/jwt' \
     --header 'content-type: application/json' \
     --header 'Lucid-Api-Version: 1' \
     --header 'authorization: Bearer oauth2-...' \
     --data '{"embedId":"...","origin":"http://localhost"}'


This seems to be the case for most all documented endpoints, providing an incomplete curl which does not include (required) information included in the documentation. I don’t know if this just is something that isn’t working on LucidChart’s side or if my curl is incorrect, because the documentation seems inconsistent.

Comments

T
Userlevel 2
Badge +2

Hi Trevor,

I understand the confusion. We switched our documentation to this new site recently and are still working out some of the issues.

Yes, every endpoint needs a ‘Lucid-Api-Version’ header, and every endpoint only has one version at the moment, so ‘Lucid-Api-Version: 1’. We call it out in a few places (here for example), but I agree that it’s very hidden and should be in each curl example. We are aware that this is missing from nearly every endpoint and will work to fix that.

The ‘Body Params’ section of the page has input boxes that will update the example curl request as you fill them in, so until required fields are filled in, the curl example will be incomplete. We’ll look for ways to reduce friction here.

I was able to generate an Embed Session Token by copying your curl request, inserting my own OAuth2 token, and removing the optional `embedId` parameter. Given the `Missing or invalid access token` error, I would double check that your OAuth2 token has the correct scope (valid scopes are listed in the endpoint’s documentation). OAuth2 tokens also expire after one hour, so you may need to refresh your token or generate a new one.

Hope this helps! Let me know if this doesn’t solve the problem.

T
Badge +1

Hi @Trevor J thanks for the response -- what is the embedId supposed to be in this case? I have tried with the documentId but that seems to be incorrect.

After some trial and error I have landed on the following:
 


{"code":"notFound","message":"Resource not found","requestId":"d348b2fdd7458c6c","details":{"error":"Embed with given ID not found"}}%

 

T
Userlevel 2
Badge +2

Obtaining an embed session token through this endpoint without specifying an embedId and using that token to open an embed viewer will show a document picker that allows you to select which document to embed. This is what generates the embedId.  Specifying this embedId in a future embed session token request will allow you to skip the document picker step and embed the same document.

In other words, you have to have already embedded a document once to obtain an embedId for that document.

T
Badge +1

Thanks @Trevor J, I think that makes sense -- in that case, is there any way for me to embed a document onto a page without first popping the embed picker? I have obtained the documentIds for numerous documents, and would like to create functionality that allows users to preview their files within my application.

T
Userlevel 2
Badge +2

Oh, I think I might have overlooked something. We have a Create Document Embed that should be able to generate the embedId using the documentId. This endpoint also needs the ‘Lucid-Api-Version: 1’ header that isn’t documented.

Reply


Lucid Software Inc. Supplemental Community Terms