Skip to main content

API guide: Upload and replace asset attachments

Upload supporting files to existing assets through the REST API, and replace attachments safely.

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

This guide covers file attachments uploaded to an existing asset through the API. Attachments can belong to Documents (system.document) or other supported asset types. The Files release also adds standalone file records (system.file), which use a separate file-property upload flow. You do not need to create a blank native document to upload a standalone file through the Documents screen. Availability depends on the Files rollout for your account.

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?