Files

Use Files to add images, videos, downloads, catalog imports, and support attachments to your Inttegro account. Each upload receives a file ID that you can attach to another Inttegro resource, retrieve later, or remove when it is no longer needed.

The file object

A file represents an asset uploaded to Inttegro. Use its ID when attaching the asset to products and other resources.

Properties

TypeScript SDK responseFilev12.0.0

Name
availableAt
Type
Date
Description
When the file became available for use. Returned only after the file is available.
Name
checksumSha256
Type
string
Description
SHA-256 checksum of the original file bytes.
Name
contentType
Type
string
Description
MIME type of the uploaded file.
Name
createdAt
Type
Date
Description
When the file record was created.
createdByFileActorWho or what uploaded the file.Click or tap to expand
- Name
  email
  Type
  string
  Description
  Actor email when available.
- Name
  id
  Type
  string
  Description
  Actor ID when available.
- Name
  name
  Type
  string
  Description
  Actor display name when available.
- Name
  type
  Type
  string
  Description
  Actor type, such as "api_key", "system", or "upload_request".
customDataCustomDataClick or tap to expand
String key-value custom data supplied during upload. Omitted when no custom data was supplied.
deliveryRecord<string, unknown>Delivery details for files that can be displayed publicly. Omitted for other file purposes.Click or tap to expand
- Name
  cacheControl
  Type
  string
  Description
  Caching policy for the public URL.
- Name
  contentType
  Type
  string
  Description
  Content type served by the public URL.
- Name
  publicUrl
  Type
  string
  Description
  URL for displaying the asset. Use this value unchanged.
Name
expiresAt
Type
Date
Description
Expiry timestamp when the file has a policy-driven lifetime. Omitted when the file does not expire.
Name
filename
Type
string | null
Description
Filename supplied with the upload. Omitted when no filename is available.
Name
id
Type
string
Description
Unique file identifier. File IDs begin with file_.
latestErrorRecord<string, unknown>Most recent processing error when the file could not be made available. Present only when the file has failed.Click or tap to expand
- Name
  at
  Type
  Date
  Description
  When the error was recorded.
- Name
  code
  Type
  string
  Description
  Stable error code for the most recent failure.
- Name
  message
  Type
  string
  Description
  Human-readable failure message.
- Name
  retryable
  Type
  boolean
  Description
  Whether retrying the same operation can succeed.
mediaRecord<string, unknown>Extracted media details when Inttegro can derive them from the uploaded file.Click or tap to expand
- Name
  aspectRatio
  Type
  string
  Description
  Aspect ratio when available.
- Name
  codec
  Type
  string
  Description
  Detected codec when available.
- Name
  colorSpace
  Type
  string
  Description
  Detected color space when available.
- Name
  durationMs
  Type
  number
  Description
  Media duration in milliseconds when available.
- Name
  frameCount
  Type
  number
  Description
  Frame count when available.
- Name
  hasAlpha
  Type
  boolean
  Description
  Whether the media has an alpha channel when available.
- Name
  height
  Type
  number
  Description
  Media height in pixels when available.
- Name
  kind
  Type
  string
  Description
  Media category such as "image", "video", or "document".
- Name
  pageCount
  Type
  number
  Description
  Page count for document-like files when available.
- Name
  width
  Type
  number
  Description
  Media width in pixels when available.
metadataRecord<string, unknown>Click or tap to expand
Read-only information added by Inttegro. Use customData for your own values.
Name
name
Type
string | null
Description
Human-friendly title for the file. Omitted when no title was supplied.
Name
purpose
Type
string
Description
Purpose policy used to validate and store the file:
- "product_download" for downloadable product files and merchant-managed attachments. Accepts .pdf, .zip, .txt, and .csv files up to 100 MiB. Not linkable through file links.
- "product_image" for product images. Accepts JPEG, PNG, and GIF up to 10 MiB. Linkable through file links.
- "product_video" for product videos. Accepts MP4, WebM, and QuickTime up to 250 MiB. Linkable through file links.
- "products_import" for product-catalog imports. Accepts CSV files up to 32 MiB that follow the required import schema and contain no more than 10,000 data rows. Not linkable through file links.
- "support_document" for support evidence and attachments. Accepts PDF, JPEG, PNG, and plain text up to 25 MiB. Not linkable through file links.
Name
scanStatus
Type
string
Description
File safety check status: Inttegro.FileScanStatuses.Pending, Inttegro.FileScanStatuses.Passed, Inttegro.FileScanStatuses.Failed, or Inttegro.FileScanStatuses.Skipped.
Name
size
Type
number
Description
Original file size in bytes.
sourceFileSourceHow the file was uploaded.Click or tap to expand
- Name
  service
  Type
  string
  Description
  Service that supplied the file, when applicable.
- Name
  type
  Type
  string
  Description
  Source type such as Inttegro.FileSourceTypes.Direct or Inttegro.FileSourceTypes.UploadRequest.
- Name
  uploadRequestId
  Type
  string
  Description
  Upload-request ID when the file came from a delegated upload.
Name
status
Type
FileStatus
Description
File lifecycle status: Inttegro.FileStatuses.Uploading, Inttegro.FileStatuses.Processing, Inttegro.FileStatuses.Available, Inttegro.FileStatuses.Failed, or Inttegro.FileStatuses.Deleted.
storageRecord<string, unknown>Size and encoding of the stored file.Click or tap to expand
- Name
  encoding
  Type
  string
  Description
  Stored representation, such as Inttegro.FileStorageEncodings.Identity or Inttegro.FileStorageEncodings.Brotli.
- Name
  storedSize
  Type
  number
  Description
  Stored object size in bytes.
Name
updatedAt
Type
Date | null
Description
When the file record was last updated.

POST/files/create

Upload a file

Upload an asset from your backend. Choose a purpose that matches how you plan to use the file; it determines the accepted format and maximum size. To collect a file from a customer or another person, create an upload request instead.

Request body

TypeScript SDK requestFileCreateRequestv12.0.0

customDataCustomDataClick or tap to expand
Optional JSON object encoded as a form field. Keys and values must both be strings. The encoded object can be at most 25 KiB, and each key can be at most 256 characters.
Name
file
Type
string | Blob
Required
required
Description
Multipart file part containing the bytes to store.
Name
purpose
Type
string
Required
required
Description
How the file will be used: "product_download", "product_image", "product_video", "products_import", or "support_document". See the file object for the formats and size limit of each purpose.
Name
title
Type
string
Description
Optional display name for the file.

Response

The response returns the new File. Save id with the product or resource that uses the asset.

A products_import CSV must contain between 1 and 10,000 product rows. Each row uses these columns in order: name, type, price_currency, price_value, reference, description, about, category, tax_code, unit_dimension, price_label, publish, and attributes. The first row may contain those column names as a header.

Request

POST/files/create

SDK versionv12.0.0

import * as Inttegro from '@inttegro/inttegro-sdk'

const inttegro = new Inttegro.InttegroClient({
  apiKey: process.env.INTTEGRO_API_KEY!,
})
const result = await inttegro.files.create({
  file: "./hero.png",
  purpose: "product_image",
  title: "Hero image",
  customData: {
    product_ref: "SKU-12345",
  },
}, {
  idempotencyKey: "upload-hero-image-001",
})

Response

Object
JSON

SDK versionv12.0.0

FileResponse {
  file: { … },
}

SDK versionv12.0.0

{
  "file": {
    "id": "file_4q6YcQk1RzPv2mDa8nFw0sHu",
    "purpose": "product_image",
    "status": "available",
    "scan_status": "skipped",
    "name": "Hero image",
    "filename": "hero.png",
    "content_type": "image/png",
    "size": 248391,
    "checksum_sha256": "db6f2f1d7b4b4d9d9c30a3ddcc7f9d506e8c9d67c4a61e5b9fd2dd9b0f5d0000",
    "created_by": { "type": "api_key" },
    "source": { "type": "direct" },
    "storage": { "encoding": "identity", "stored_size": 248391 },
    "delivery": { … },
    "custom_data": { "product_ref": "SKU-12345" },
    "metadata": { "source_type": "direct" },
    "created_at": "2026-06-05T12:30:00Z",
    "updated_at": "2026-06-05T12:30:00Z",
    "available_at": "2026-06-05T12:30:00Z"
  }
}

POST/files/lookup

Lookup a file

Retrieve a file's name, type, size, status, and other details. To retrieve the file itself, use Download file contents.

Request body

TypeScript SDK requestFileLookupRequestv12.0.0

Name
fileId
Type
string
Required
required
Description
File ID to retrieve.

Response

The response returns the requested File.

Request

POST/files/lookup

SDK versionv12.0.0

import * as Inttegro from '@inttegro/inttegro-sdk'

const inttegro = new Inttegro.InttegroClient({
  apiKey: process.env.INTTEGRO_API_KEY!,
})
const result = await inttegro.files.lookup({
  fileId: "file_4q6YcQk1RzPv2mDa8nFw0sHu",
})

POST/files/page

Page files

Browse the files in your Inttegro account. Combine filters to find files by purpose, status, or upload date.

Request body

TypeScript SDK requestFilePageRequestv12.0.0

Name
createdAfter
Type
Date
Description
Return files created at or after this RFC 3339 timestamp.
Name
createdBefore
Type
Date
Description
Return files created at or before this RFC 3339 timestamp.
Name
pageNumber
Type
number
Description
Page number to retrieve. Defaults to 1.
Name
pageSize
Type
number
Description
Requested number of files per page. Defaults to 25 and is capped at 256.
Name
purpose
Type
string
Description
Filter by file purpose.
Name
status
Type
FileStatus
Description
Filter by lifecycle status: Inttegro.FileStatuses.Uploading, Inttegro.FileStatuses.Processing, Inttegro.FileStatuses.Available, Inttegro.FileStatuses.Failed, or Inttegro.FileStatuses.Deleted.

Response

Files are returned newest first. The response contains the current page number, the number of files returned, and a files array. When no more files remain, the array is empty.

Request

POST/files/page

SDK versionv12.0.0

import * as Inttegro from '@inttegro/inttegro-sdk'

const inttegro = new Inttegro.InttegroClient({
  apiKey: process.env.INTTEGRO_API_KEY!,
})
const result = await inttegro.files.page({
  purpose: "product_image",
  status: "available",
  pageNumber: 1,
  pageSize: 25,
})

Response (abbreviated file objects)

Object
JSON

SDK versionv12.0.0

PageResponse {
  page: { … },
}

SDK versionv12.0.0

{
  "page": {
    "number": 1,
    "size": 1,
    "files": [ … ]
  }
}

POST/file_references/reconcile

Reconcile file references

Tell Inttegro which files a resource currently uses. This prevents an attached file from being deleted while the resource still depends on it.

Send the complete set after you save the resource. Each call replaces the previous set: references you remove are released, references you add become protected, and an empty or omitted references array clears the set.

Request body

TypeScript SDK requestFileReferenceReconcileRequestv12.0.0

Name
references
Type
FileReferenceInput[]
Description
Complete desired set of live file references. Omit it or send an empty array to clear the set.
TypeScript SDK requestFileReferenceReconcileRequestv12.0.0
- Name
  field
  Type
  string
  Required
  required
  Description
  Stable path to the field containing the reference, such as "media.hero_image" or "media.gallery[0]".
- Name
  fileId
  Type
  string
  Required
  required
  Description
  Canonical file_... ID whose deletion should remain blocked while this reference is live.
- Name
  purpose
  Type
  string
  Description
  Optional purpose recorded with the reference, such as "product_image".
- Name
  reference
  Type
  string
  Description
  Optional exact value stored on the resource. This may be a file ID or file-link ID.
- Name
  referenceKind
  Type
  FileReferenceKind
  Description
  Optional kind describing references[].reference. Use "file" for a file ID or "file_link" for a file-link ID.
Name
resourceId
Type
string
Required
required
Description
ID of the resource whose live reference set is being replaced.
Name
resourceType
Type
string
Required
required
Description
Stable resource kind, such as "product".

Response

A successful response returns reconciled set to true, confirming that Inttegro now uses the submitted set to protect files from deletion.

Request

POST/file_references/reconcile

SDK versionv12.0.0

import * as Inttegro from '@inttegro/inttegro-sdk'

const inttegro = new Inttegro.InttegroClient({
  apiKey: process.env.INTTEGRO_API_KEY!,
})
const result = await inttegro.fileReferences.reconcile({
  resourceType: "product",
  resourceId: "prod_123",
  references: [
    {
      fileId: "file_4q6YcQk1RzPv2mDa8nFw0sHu",
      field: "media.hero_image",
      reference: "file_4q6YcQk1RzPv2mDa8nFw0sHu",
      referenceKind: "file",
      purpose: "product_image",
    },
  ],
})

Response

Object
JSON

SDK versionv12.0.0

ReconciledResponse {
  reconciled: true,
}

SDK versionv12.0.0

{
  "reconciled": true
}

POST/files/contents

Download file contents

Retrieve a file from your backend. Use this for private downloads and for file purposes that cannot be shared through file links.

Request body

TypeScript SDK requestFileContentsRequestv12.0.0

Name
disposition
Type
FileDisposition
Description
Optional response disposition: Inttegro.FileDispositions.Attachment or Inttegro.FileDispositions.Inline. Defaults to Inttegro.FileDispositions.Attachment.
Name
delivery
Type
string
Description
Delivery mode: Inttegro.FileDeliveries.Stream or Inttegro.FileDeliveries.Redirect. Defaults to Inttegro.FileDeliveries.Stream.
Name
fileId
Type
string
Required
required
Description
File ID whose bytes should be delivered.

Response

With delivery set to Inttegro.FileDeliveries.Stream, the response contains the file bytes and the headers needed to preserve its content type and filename.

With delivery set to Inttegro.FileDeliveries.Redirect, the response redirects to a short-lived download URL. The SDK helpers use stream delivery, which is the simplest choice when your backend needs to save or forward the file.

Stream request

POST/files/contents

SDK versionv12.0.0

import * as Inttegro from '@inttegro/inttegro-sdk'

const inttegro = new Inttegro.InttegroClient({
  apiKey: process.env.INTTEGRO_API_KEY!,
})
const result = await inttegro.files.contents({
  disposition: "attachment",
  fileId: "file_4q6YcQk1RzPv2mDa8nFw0sHu",
})

POST/files/delete

Delete a file

Delete a file that your business no longer needs. Its public links stop working, and Inttegro rejects the deletion while another resource still uses the file.

Request body

TypeScript SDK requestFileDeleteRequestv12.0.0

Name
fileId
Type
string
Required
required
Description
File ID to delete.

Response

The response returns the deleted File with status set to Inttegro.FileStatuses.Deleted.

Request

POST/files/delete

SDK versionv12.0.0

import * as Inttegro from '@inttegro/inttegro-sdk'

const inttegro = new Inttegro.InttegroClient({
  apiKey: process.env.INTTEGRO_API_KEY!,
})
const result = await inttegro.files.delete({
  fileId: "file_4q6YcQk1RzPv2mDa8nFw0sHu",
})

Response (abbreviated file object)

Object
JSON

SDK versionv12.0.0

FileResponse {
  file: { … },
}

SDK versionv12.0.0

{
  "file": {
    "id": "file_4q6YcQk1RzPv2mDa8nFw0sHu",
    "purpose": "product_image",
    "status": "deleted"
  }
}

The file object

Properties​

Upload a file

Request body​

Response​

Request

Response

Lookup a file

Request body​

Response​

Request

Page files

Request body​

Response​

Request

Response (abbreviated file objects)

Reconcile file references

Request body​

Response​

Request

Response

Download file contents

Request body​

Response​

Stream request

Delete a file

Request body​

Response​

Request

Response (abbreviated file object)

Properties

Request body

Response

Request body

Response

Request body

Response

Request body

Response

Request body

Response

Request body

Response