Upload a File with the API
Work with files through the public API.
The public API includes file records and file metadata endpoints. Use the generated OpenAPI reference for the exact upload flow available in your current deployment.
Use file API endpoints from trusted backend systems only. Do not expose API keys or upload control logic directly in browser code.
Use this workflow for migrations, external document intake, finance attachments, customer file handoff, or operational systems that need to keep file metadata in Agiled.
Common File Tasks
- List files.
- Get a file record.
- Create a file record after an upload flow.
- Update file metadata.
- Delete a file record.
Use the Files API when another system needs to attach supporting documents, export file metadata, or clean up file records after a migration.
Before Uploading
Confirm:
- The API key has file write ability.
- The target folder or parent id exists if you are organizing files.
- The file is attached to the correct workspace record after upload.
Also confirm the file name, MIME type, size, and source record. Store the Agiled file ID returned by the API so your integration can update, attach, or remove the same file later.
Metadata to Keep
Store the Agiled file ID, original external ID, original filename, content type, size, upload time, and any related record ID. This makes retries, cleanup, and support investigations much easier.
Upload Safely
For migrations, upload a small sample first and inspect the files in Agiled. Confirm previews, downloads, folder placement, and record attachments before running the full job.
If the upload flow returns a validation error, fix the metadata or target folder before retrying. If the file bytes were uploaded but the record was not created, avoid retrying blindly until you know whether a duplicate file exists.
Troubleshooting
If files upload but cannot be found in the UI, check folder placement, workspace scope, and whether the file record was attached to a visible record.
If previews fail, confirm MIME type, file extension, file size, and whether the source file is valid.
If migration uploads create duplicates, compare external IDs and stored Agiled file IDs before retrying failed rows.
Post-Upload Review
After the first successful upload, open the file in Agiled and verify preview, download, folder, uploader, attached record, and permissions. If the file is used with invoices, estimates, documents, projects, or tickets, open that record too and confirm the attachment appears where users expect it.
For migrations, keep a sample set that includes PDFs, images, office documents, large files, and unsupported file types. This gives you realistic evidence before moving the full file archive.