Upload endpoints
You can upload files using either:- POST
/silo/v1/entries/{entry_id}/files
System generates the UUID. - PUT
/silo/v1/entries/{entry_id}/files/{id}
You specify the UUID.
POST and let the system generate UUIDs. However, PUT is useful when you need idempotent operations (safe retries with the same UUID), when integrating with external systems that have their own identifiers, or when you need to reference the file URL before the upload completes.
Upload options
Both endpoints support two upload methods:Inline upload (base64)
Upload the file data directly in the request body as base64-encoded content. This works well for smaller files.cURL
Placeholder with streaming upload
Create a placeholder file first, then upload the actual file contents to the URL provided in the response. This is useful for larger files or when you want to separate metadata creation from file upload.1
Create the placeholder
cURL
sha256 hash and size, use your programming language’s built-in crypto and file system libraries. In Node.js, use the crypto module with createHash('sha256') and fs.statSync(). In Python, use hashlib.sha256() and os.path.getsize(). In Go, use crypto/sha256 and os.Stat(). Most languages provide similar standard library functions for these operations.2
Upload the file to the URL from the response
Success
url field from the response to upload the file contents. Note stored is false until the file is uploaded.cURL
Request parameters
The file upload endpoints accept the following parameters:| Parameter | Required | Description |
|---|---|---|
name | Yes | Name of the file (e.g., invoice.pdf) |
category | No | Use format for alternative formats (PDF, XML), attachment for supporting documents. |
data | Conditional | Base64-encoded binary data. Required if sha256, size, and mime are not provided |
mime | Conditional | MIME type (e.g., application/pdf). Required when data is not provided |
sha256 | Conditional | SHA256 hex hash of the file. Required when data is not provided |
size | Conditional | Size of the file in bytes. Required when data is not provided |
key | No | Used to identify a file in a category. If two files are uploaded with the same key and category, one will replace the other. If no key is provided, the filename is used for uniqueness along with the category |
desc | No | Description of the file |
embeddable | No | When true, the file may be embedded inside other files like PDFs. Default is false |
private | No | When true, the file is private and can only be accessed by the owner. Default is false |
meta | No | Additional metadata about the file (key-value pairs) |
Examples
Upload a PDF invoice
Upload a PDF invoice
cURL
Upload an XML file
Upload an XML file
cURL
Create a placeholder for large file upload
Create a placeholder for large file upload
cURL
url field that can be used to upload the file contents.Response
This is an example response from the file upload endpoints:Fetching files
After uploading a file, you can retrieve it using the Fetch a File endpoint:cURL
Content-Type and Content-Disposition headers set according to the file’s source.
Best practices
- Use placeholders for large files — For files larger than a few megabytes, create a placeholder first and upload via the streaming URL to avoid timeouts.
-
Provide file metadata — Include
key,desc, andcategoryto make files easier to identify and organize. -
Verify uploads — Check the
storedfield in the response to confirm the file was uploaded successfully. -
Use appropriate categories — Use
formatfor alternative invoice formats (PDF, XML) andattachmentfor supporting documents. -
Set privacy flags — Use the
privateflag for sensitive files that shouldn’t be publicly accessible.