Skip to main content

API Guide: Creating and updating files

how to create documents and upload files over the Lexful REST API

Written by Jeremiah Hendrickson

Overview

This guide is on how to create documents and upload files over the Lexful REST API (reference: https://developer.lexful.ai) and is useful for customers/integrations that are looking to load files from other products (e.g Sharepoint, Google Drive, Dropbox, etc) into Lexful.

How Files Work

Files are not standalone assets, they can only be uploaded and attached to an existing asset. While files are commonly uploaded as attachments to Documents (i.e. system.document), uploading to other asset types is also supported.

Uploading a File

To upload a file, we must:

  1. Identify the Document asset that we can attach the file to. If none exists, we will need to create the Document asset first (capture the id from the response as it'll be required for the next step):

bash

curl -X POST 'https://api.us.lexful.app/v1/assets/system.document' \  --header 'X-Account-Id: {ACCOUNT_ID}' \  --header 'Authorization: Bearer {JWT}' \  --header 'Content-Type: application/json' \  --data '{    "organization_id": "{ORGANIZATION_ID}",    "name": "Name of document or file",    "content": "Content of document or preamble of file"  // this is optional  }'  Response:{  "id": "019983a9-xxxx,  ...}

  1. Under the Document asset, create a file attachment and capture the file id and presignedUploadUrl from the response as it'll be needed for uploading the file (max 100MB):

bash

curl -X POST 'https://api.us.lexful.app/v1/assets/system.document/{ASSET_ID}/files' \  --header 'X-Account-Id: {ACCOUNT_ID}' \  --header 'Authorization: Bearer {JWT}' \  --header 'Content-Type: application/json' \  --data '{    "name": "Network Diagram",    "original_name": "network-diagram.pdf",    "file_extension": "pdf",    "mime_type": "application/pdf",    "size": 248413  // bytes  }'  Response:{  "file": {    "id": "0199a1c4-xxxx",    ...  },  "presignedUploadUrl": "https://s3.amazonaws.com/...&X-Amz-Signature=..."}

  1. Use the presignedUploadUrl to upload the file, note that the Content-Type must match the mime_type in the previous step:

bash

// NOTE: do not send Lexful API creds, PRESIGNED_UPLOAD_URL is already pre-authorized curl -X PUT '{PRESIGNED_UPLOAD_URL}' \  --header 'Content-Type: application/pdf' \  --data-binary '{file_content}'

  1. Update the file as upload completed using the file id from the previous step

bash

curl -X POST 'https://api.us.lexful.app/v1/assets/system.document/{ASSET_ID}/files/{FILE_ID}/complete' \  --header 'X-Account-Id: {ACCOUNT_ID}' \  --header 'Authorization: Bearer {JWT}'

Updating a File

There is no endpoint that swaps the bytes behind an existing file attachment. To replace it with a new version, follow steps above to create a new file attachment against the same asset, and delete the old file attachment (note that this step is unrecoverable):

bash

curl -X DELETE 'https://api.us.lexful.app/v1/assets/system.document/{ASSET_ID}/files/{OLD_FILE_ID}' \  --header 'X-Account-Id: {ACCOUNT_ID}' \  --header 'Authorization: Bearer {JWT}'

Best Practices

To do a clean integration, you will need the following as part of your solution:

  • Store and track the Document asset id, file id, and last upload date for each file uploaded to Lexful

  • Only upload files that have changed since last upload

  • Avoid repeatedly uploading files that have not changed

  • Do not upload files more than 100MB in size

Related Articles
Did this answer your question?