Uploading documents using the Bluescape API

Hey folks,

May I know what the corresponding fields in the zygote body should be when uploading a pdf to a workspace using the Bluescape API? Currently following the “Upload content into a Canvas for v3” guide, but using “Document” in the “type” field does not work.

Sorry if this question has been asked before, I could not find it in the Developer docs.

Hi, @zackyew.
We are actively working to connect with the proper subject matter expert and gather up-to-date information for you. We will share our findings as soon as we are able. Thank you for being so patient. :smiley:

Hello @zackyew - welcome to the Bluescape Developer Community!

Sorry the “Upload Content into a Canvas for v3” guide didn’t help you with Document/pdf.

The short answer is REST body for pdf:

const zygote_body = {
    "type": "Document",
    "filename": "graphQL_intro.pdf",
    "documentFormat": "pdf",
    "transform": { "x": 300, "y": 100, "scale": 1 }

For a deeper explanation, if you are uploading a document from disk, it needs to be be done in 3 steps:

  1. call Bluescape createDocument mutation to get the s3 keys needed to upload the document to s3
  2. upload the document to s3 using response from step 1
  • (optional step to also upload a preview document preview)
  1. Complete the upload transfer by calling Bluescape processAsset mutation after receiving 204 response from step2.

You can find a sample a sample graphQL NodeJs application on our community github that demonstrates uploading files from disk and by URL:

you can navigate the graphQL documentation with our graphQL playground

  1. Step1: createDocument mutation
#create Document from disk
#formats: doc docx ppt pptx xls xlsx pdf docMime docxMime pptMime pptxMime xlsMime xlsxMime pdfMime
mutation createNewAssetFromLocal($workspaceId: String!, $input: CreateDocumentInput!){
    newAsset: createDocument(workspaceId: $workspaceId, input: $input) {
    content{ uploadId url fields}
    document {id width height ingestionState}

input variables:

"workspaceId": "{{workspaceID}}",
    "input": {
      "title": "./files/graphQL_intro.pdf",
      "filename": "./files/graphQL_intro.pdf",
      "transform": {"x":0, "y":0},
      "documentFormat": "pdf"
  1. Upload the Document to s3 with keys etc from step1:
curl --location 'https://s3.us-east-1.amazonaws.com/public-assets.bluescape.com' \
--form 'key="sessions/objects/workspaceId/uploadId.pdf"' \
--form 'bucket="public-assets.bluescape.com"' \
--form 'X-Amz-Algorithm="AWS4-HMAC-SHA256"' \
--form 'X-Amz-Credential="sampleCredential"' \
--form 'X-Amz-Date="20230523T200212Z"' \
--form 'Policy="samplePolicy"' \
--form 'X-Amz-Signature="sampleSignature"' \
--form 'file=@"/developerProgram/graphQL_intro.pdf"'
  1. after 204 response, or error inform Bluescape of s3 upload status:
#complete the asset upload using the uploadID obtained from 
#createImage, createVideo, createDocument
mutation myProcessAsset($workspaceId: String!, $uploadId: String!, $errorDataToReport:TransferCompleteInput! ) {
    processAsset( workspaceId:$workspaceId id:$uploadId input:$errorDataToReport)

input variables:

    "workspaceId": "{{workspaceID}}",
    "uploadId" : "{{Amz-uploadId}}",
            "errorCode": null,
            "errorMessage": null


  1. Step1 create element endpoint documentation: POST /v3/workspaces/{workspace}/elements
curl --location 'https://api.apps.us.bluescape.com/v3/workspaces/IPvtDuI2Eh7DAdsI6ciu/elements' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{yourToken}}' \
--data '{
    "type": "Document",
    "filename": "graphQL_intro.pdf",
    "documentFormat": "pdf",
    "transform": { "x": 300, "y": 100, "scale": 1 }
  1. Step2 upload to S3 (same as above)
  2. step3 process the result of s3 upload success/failure
curl --location --request PUT 'https://api.apps.us.bluescape.com/v3/workspaces/{{workspaceId}}/assets/uploads/{{s3UploadId}}' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{token}}' \
--data '{}'

I hope this helps you navigate our developer resources for both REST and graphQL and helps solve your issue with document upload!