File Uploads

• Uploading Files
  • Step 1: Request Signed Upload URL
  • Step 2: Upload File to Signed URL
  • Step 3: Register the File
• File Size Limits

The Blond API uses a secure three-step file upload process for optimal performance and security.

The file upload process involves:

1. Request a signed upload URL - Get temporary upload credentials
2. Upload file directly - Upload file using the provided signed URL
3. Register the file - Use the UUID and key from the signed URL response to register the file in the system

This approach enables direct uploads with progress tracking while maintaining security.

Uploading Files

Step 1: Request Signed Upload URL

post

/vapor/signed-storage-url

Attribute (* required)	Type	Description
content_type *	String	MIME type of the file being uploaded

The file is always uploaded privately to Blond's storage bucket. The signed URL is valid for 5 minutes.

Example response

// HTTP 201 Created
{
    "uuid": "550e8400-e29b-41d4-a716-446655440000",
    "bucket": "blond-files",
    "key": "tmp/550e8400-e29b-41d4-a716-446655440000",
    "url": "https://blond-files.<storage-host>/tmp/550e8400-e29b-41d4-a716-446655440000?X-Amz-Algorithm=...",
    "headers": {
        "Content-Type": "image/jpeg",
        "x-amz-acl": "private"
    }
}

Step 2: Upload File to Signed URL

Use the signed URL to upload your file directly:

const response = await fetch(signedData.url, {
    method: 'PUT',
    headers: signedData.headers,
    body: file
});

Important Notes:

• Remove the Host header if present (it's automatically set by browsers)
• Use PUT method, not POST
• Include all headers from the signed URL response
• Upload progress can be tracked using XMLHttpRequest or axios

Step 3: Register the File

After uploading, use the response data from the signed URL request in subsequent API calls like the ones below. Uploads that are not registered within 24 hours are deleted.

• Expense Uploads
• Bank Transaction Imports

Pass uuid and key exactly as the signed URL response returned them. The request is rejected with 422 Unprocessable Entity when:

• key is not tmp/<uuid> for the submitted uuid
• the uuid has already been registered (each upload can be registered once)

// HTTP 422 Unprocessable Entity
{
    "message": "The upload is invalid. Please upload the file again.",
    "errors": {
        "key": ["The upload is invalid. Please upload the file again."]
    }
}

File Size Limits

File uploads are subject to size limits. Maximum file size varies by file type and endpoint, and available storage quotas may apply per organization. Refer to specific endpoint documentation for size limits.