Skip to main content

Upload attachments

Attach reports, images, and raw exports to an existing JSON package. Files are uploaded separately, with a limit of 10 GB per file; do not embed them as base64 in a JSON package.

1. Ingest the parent package​

Send an ISO 19848 package or another registered JSON data type describing the data. Wait for 200 OK and record the packageId from the response.

Use the same ingest connection for the parent package and attachment. An external reference ID cannot replace the Gateway-assigned package ID, and an attachment cannot itself be the parent of another attachment.

2. Upload the file​

Send the file to POST /attachment/{packageId} as raw bytes, not multipart form data or JSON. Supply the file's content type and content length. Include X-Attachment-Filename with the filename and extension so recipients can identify the file.

With the environment and key configured as in the authentication guide, replace the placeholder with the returned parent ID and upload a local report.pdf:

export VISTA_PARENT_PACKAGE_ID='<packageId-from-the-ingest-response>'

curl --fail-with-body --silent --show-error \
  --request POST "${VISTA_GATEWAY_URL}/attachment/${VISTA_PARENT_PACKAGE_ID}" \
  --header "Authorization: ApiKey ${VISTA_GATEWAY_API_KEY}" \
  --header 'Content-Type: application/pdf' \
  --header 'User-Agent: ExampleIngest/1.0' \
  --header 'X-Attachment-Filename: report.pdf' \
  --header 'X-Package-External-Id: example-report-001' \
  --header 'X-Package-Correlation-Id: example-ingest-run-001' \
  --upload-file report.pdf

--request POST overrides curl's default upload method; --upload-file streams the file and sets its content length for a regular local file. When using another client, ensure it sends Content-Length; an unknown-length chunked upload is not accepted.

The Gateway validates the declared content type against the filename and, for supported formats, the file signature. Use a content type appropriate to the actual file.

3. Record the result​

A successful upload returns 201 Created with attachmentPackageId and parentPackageId. Store both IDs with your source-system reference. A successful parent ingest does not mean the attachment has also been uploaded; handle these as separate requests.

If the parent is not found, check that the ID came from a successful ingest response. If access is rejected, check that you are using the connection that sent the parent. See troubleshooting for size, rate-limit, validation, and service errors.

Attachments are made available to authorized DNV services. Download and consumption are outside the scope of the ingest API.