How the flow works
- Send
requestFileUploadUrlto ION. ION returnsuploadUrl,s3Key, andcontentType. - Send a PUT request with the file body and
Content-Typeheader touploadUrl. Storage returns a200response with anETagheader. - Send
createFileAttachmentto ION withs3Key,s3Etag,entityId, andfilename. ION returns thefileAttachment.
Prerequisites
- An authenticated GraphQL client. See Authentication.
- Permission to attach files to the entity you’re targeting.
- The entity ID of the object you’re attaching to. See Choose an entityId.
Step 1: Request a signed upload URL
uploadUrl is valid for one hour. If you wait longer, the PUT request in step 2 fails. If that happens, request a new URL.
The contentType in the response is the value you must send in the PUT request’s Content-Type header. ION derives it from the filename extension, for example application/pdf for .pdf and model/step for .step. When the extension isn’t recognized, contentType is application/octet-stream. See Content type rules.
Step 2: Upload the file
Upload the file directly using the signed URL:-i flag returns the response headers, including the ETag value:
ETag value, with the surrounding quotes stripped, is your s3Etag for step 3. ION uses it to verify that the file you uploaded matches the registration you’re about to create.
Step 3: Register the attachment
Input fields
Content type rules
The signed upload URL is bound to one content type. Storage rejects the PUT request unless itsContent-Type header matches exactly.
- ION guesses the content type from the stored file name. Known extensions return their standard type, such as
application/pdformodel/step. - When the extension isn’t recognized, ION signs the URL for
application/octet-stream. Sendapplication/octet-streamin that case. Renaming the file to get a different type isn’t required. - Use the value ION returns, not your own guess. In the flow above it is
contentTypefromrequestFileUploadUrl. In the create-first flow it isfileAttachment.contentType. - Sending any other
Content-Typereturns403 SignatureDoesNotMatch.
Alternative: create the attachment first
Instead of requesting a URL first, you can create the attachment record and upload the bytes afterward. This flow skipss3Etag and validateUpload.
uploadUrl. Set the Content-Type header to fileAttachment.contentType. The same one-hour expiry and exact content type rules apply.
ION creates the attachment record before the upload happens. If the upload never completes, the record exists without a file behind it. Use the three-step flow with validateUpload when you need ION to confirm the upload before it creates the record.
The createFileAttachment mutation always returns uploadUrl, including in the three-step flow, where you can ignore it.
Link an external file
To attach a file that stays in another system, passintegrationId, integrationFetchUrl, and filename instead of uploading bytes:
uploadUrl is an empty string, and downloadUrl is null. integrationId and integrationFetchUrl are the only fields that set up this mode, so don’t send s3Key with them.
File types, size limits, and previews
- ION doesn’t enforce a file type or file size limit on attachments. Files upload directly to storage, so limits set by your network or proxy can still apply.
- Each flow uploads the file in a single PUT request. Amazon S3 limits a single PUT request to 5 GB, so files larger than 5 GB can’t use these flows.
- Whether ION shows a preview depends on the file type. This guide doesn’t list the types that preview.
Choose an entityId
TheentityId is not the same as the parent object’s id. ION lets multiple object types share a relationship to file attachments, so you pass the parent’s entity ID rather than its own id. To attach a file to a run step, the most common case, first fetch the run step’s entity.id:
entity.id, not runStep.id, as the entityId in step 3.
The same pattern applies to other targets:
End-to-end example in Python
The example uses the US endpoint. SetGQL_URL to your region’s API endpoint:
Common errors
Verify the attachment
After step 3, you can confirm the attachment in two ways:- In the ION UI, open the parent entity and check the attachments panel.
- Via the API, query the attachment back by ID:
downloadUrl is a fresh signed download URL, time-bound. Don’t cache it long-term.