Skip to main content
ION stores file attachments such as procedure images, run artifacts, and inspection photos. You don’t upload a file by posting it through the GraphQL endpoint. Instead, you use a three-step flow. Large files upload directly to storage rather than through ION.

How the flow works

  1. Send requestFileUploadUrl to ION. ION returns uploadUrl, s3Key, and contentType.
  2. Send a PUT request with the file body and Content-Type header to uploadUrl. Storage returns a 200 response with an ETag header.
  3. Send createFileAttachment to ION with s3Key, s3Etag, entityId, and filename. ION returns the fileAttachment.

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

Variables:
Response:
The 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:
The -i flag returns the response headers, including the ETag value:
That 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.
Capturing the ETag is the most common file-upload bug. Confirm your HTTP library exposes response headers and isn’t using a wrapper that discards them.

Step 3: Register the attachment

Variables:
Response:
After this returns successfully, the file is visible in the ION UI on the entity you attached it to.

Input fields

With validateUpload set to true, ION makes one extra HEAD request and gives you immediate feedback when the registration doesn’t match the uploaded bytes.

Content type rules

The signed upload URL is bound to one content type. Storage rejects the PUT request unless its Content-Type header matches exactly.
  • ION guesses the content type from the stored file name. Known extensions return their standard type, such as application/pdf or model/step.
  • When the extension isn’t recognized, ION signs the URL for application/octet-stream. Send application/octet-stream in 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 contentType from requestFileUploadUrl. In the create-first flow it is fileAttachment.contentType.
  • Sending any other Content-Type returns 403 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 skips s3Etag and validateUpload.
Variables:
Send a PUT request with the file body to 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. To attach a file that stays in another system, pass integrationId, integrationFetchUrl, and filename instead of uploading bytes:
ION stores only the link. No bytes are uploaded, 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

The entityId 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:
Use the returned 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. Set GQL_URL to your region’s API endpoint:
For the full Python integration template, see Build an API client.

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:
The downloadUrl is a fresh signed download URL, time-bound. Don’t cache it long-term.
Set a longer timeout for the upload PUT in step 2 than for your GraphQL requests. For large files, the upload is the slowest part of the flow.