Skip to main content
View as Markdown

File links

Use File links to share product images and videos with customers or other recipients. You can set an expiry or access limit and revoke the link without deleting the underlying file.

Anyone with the URL can use the access it grants. Keep it out of logs and analytics, and share it only with its intended audience.

A file link records which file can be opened, how it should be delivered, and when access ends. The public URL is returned only when the link is created.

Properties​

TypeScript SDK responseFileLinkv12.0.0
  • accessFileLinkAccessAccess limits and usage details for the link.Click or tap to expand
    • Name
      accessCount
      Type
      number
      Description
      Number of successful opens recorded for this link.
    • Name
      allowDownload
      Type
      boolean
      Description
      Whether attachment-style delivery is allowed.
    • Name
      allowedOrigins
      Type
      string[]
      Description
      Optional list of allowed origins.
    • Name
      lastAccessedAt
      Type
      Date | null
      Description
      When the link was last opened successfully.
    • Name
      maxAccesses
      Type
      number
      Description
      Maximum number of successful opens allowed before the link stops working.
  • Name
    active
    Type
    boolean
    Description

    Whether the link can still be opened.

  • Name
    createdAt
    Type
    Date
    Description

    When the link was created.

  • createdByRecord<string, unknown>Actor that created the link.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" or "system".
  • customDataCustomDataClick or tap to expand

    Optional string key-value custom data attached to the link.

  • deliveryFileLinkDeliveryHow the file is presented when someone opens the link.Click or tap to expand
  • Name
    expiresAt
    Type
    Date | null
    Description

    When the link stops granting access.

  • Name
    fileId
    Type
    string
    Description

    File ID the link grants access to.

  • Name
    id
    Type
    string
    Description

    Unique file-link identifier. File link IDs begin with flink_.

  • Name
    kind
    Type
    string
    Description

    Link kind. Currently Inttegro.FileLinkKinds.Public.

  • metadataFileMetadataClick or tap to expand

    Read-only information added by Inttegro. Use customData for your own values.

  • Name
    purpose
    Type
    string
    Description

    Purpose of the linked file. Only product images and videos can be shared with file links:

    • "product_image" for product images.
    • "product_video" for product videos.
  • Name
    revokedAt
    Type
    Date | null
    Description

    When the link was revoked. Returned only after revocation.

  • revokedByRecord<string, unknown>Actor that revoked the link. Present only after revocation.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" or "system".
  • Name
    status
    Type
    FileLinkStatus
    Description

    Link lifecycle status: Inttegro.FileLinkStatuses.Active, Inttegro.FileLinkStatuses.Revoked, Inttegro.FileLinkStatuses.Expired, or Inttegro.FileLinkStatuses.Disabled.

  • Name
    updatedAt
    Type
    Date
    Description

    When the link was last updated.

POST/file_links/create

Create a file link

Create a public URL for a product image or video. For private files such as support documents and product downloads, use Download file contents from your backend instead.

The response includes the URL to share and a file-link ID for managing it later. Store both when you create the link because lookup responses do not return the URL again.

Request body​

TypeScript SDK requestFileLinkCreateRequestv12.0.0

Defaults and limits​

Response​

The response returns the new FileLinkCreation and its public url.

Request

POST/file_links/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.fileLinks.create({
  fileId: "file_4q6YcQk1RzPv2mDa8nFw0sHu",
  delivery: {
    mode: "inline",
  },
  access: {
    allowDownload: true,
    maxAccesses: 100,
  },
  expiresAt: new Date("2030-07-06T12:30:00Z"),
})

Response

SDK versionv12.0.0
Response {
  fileLink: { … },
  url: "<FILE_LINK_URL>",
}
POST/file_links/lookup

Lookup a file link

Retrieve a file link's status, delivery settings, access limits, and usage. The public URL is returned only when you create the link.

Request body​

TypeScript SDK responsev12.0.0
  • Name
    id
    Type
    string
    Required
    required
    Description

    File-link ID to retrieve.

Response​

The response returns the requested FileLink.

Request

POST/file_links/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.fileLinks.lookup({
  id: "flink_8pQz3LkY6mN2vT9sB4cD1eF0",
})
POST/file_links/page

Page file links

Browse the file links in your Inttegro account. Filter by file to see every link created for one asset, or by status to find links that are active, revoked, expired, or disabled.

Request body​

TypeScript SDK requestFileLinkPageRequestv12.0.0

Response​

Without a status filter, links are returned newest first. A status-filtered page is ordered by expiry. The response contains the current page number, the number of links returned, and a fileLinks array.

Request

POST/file_links/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.fileLinks.page({
  fileId: "file_4q6YcQk1RzPv2mDa8nFw0sHu",
  status: "active",
  pageNumber: 1,
  pageSize: 25,
})
POST/file_links/revoke

Revoke a file link

Stop a public URL from serving its file. Revoke a link when it was shared with the wrong audience, has outlived its purpose, or should be replaced with a different access policy.

Request body​

TypeScript SDK requestFileLinkRevokeRequestv12.0.0
  • Name
    id
    Type
    string
    Required
    required
    Description

    File-link ID to revoke.

  • revokedByFileActorOptional actor revoking the link.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.

Response​

The response returns the updated FileLink with status set to Inttegro.FileLinkStatuses.Revoked. The URL stops working immediately.

Request

POST/file_links/revoke
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.fileLinks.revoke({
  id: "flink_8pQz3LkY6mN2vT9sB4cD1eF0",
  revokedBy: {
    type: "user",
    id: "usr_support_123",
  },
}, {
  idempotencyKey: "revoke-file-link-001",
})
GET/file_links/open

Open a file link

This is the public endpoint behind the URL returned when you create a file link. It does not use your API key. Applications should use the complete returned URL rather than constructing it from the query parameters.

Query parameters​

TypeScript SDK responsev12.0.0
  • Name
    id
    Type
    string
    Required
    required
    Description

    File-link ID contained in the returned URL.

  • Name
    token
    Type
    string
    Required
    required
    Description

    Access token contained in the returned URL.

Response​

Use the complete URL returned by Create a file link unchanged. It works only while the link is active and within its expiry and access limits.

Download and inline links return the file. Redirect links send the browser to a short-lived delivery URL. A successful open counts toward access.max_accesses; an unsuccessful attempt does not. This public URL operation deliberately stays in wire form because it is not an SDK resource method.

Request

GET/file_links/open
SDK versionv12.0.0
import * as Inttegro from '@inttegro/inttegro-sdk'

const inttegro = new Inttegro.InttegroClient({
  apiKey: process.env.INTTEGRO_API_KEY!,
})
const download = await inttegro.fileLinks.open({
  url: '<FILE_LINK_URL>',
  saveTo: './hero.png',
})