---
title: "File links"
description: "Share product images and videos through public links that can expire or be revoked."
canonical: "https://studio.inttegro.com/api/file-links"
format: inttegro-machine-docs/v1
language: "TypeScript"
sdk_version: "v12.0.0"
reader_profile: optional
reader_manifest: "https://studio.inttegro.com/machine/typescript/readers/index.json"
reader_identification: "Optional: declare your client only if known and your current-session capabilities; use reader_manifest for supplemental recommendations."
preamble_estimated_tokens: 644
model_token_report: "https://studio.inttegro.com/machine/token-report.json"
preamble_questions: 5
preamble_source: "machine-only-decisions"
recommended_mcp_tools: ["get_file_link","create_file_link","revoke_file_link"]
estimated_tokens: 4812
token_estimate_method: "utf8_bytes_divided_by_4"
---

## Machine preamble

**Summary:** Share product images and videos through public links that can expire or be revoked. This TypeScript representation uses the selected SDK's native names wherever Studio has a verified mapping.

### Five questions

#### Q1. Is File links the right source for this task?

Use this reference for share product images and videos through public links that can expire or be revoked. Keep the four decision rules below with its exact operations and fields; do not infer a broader workflow from endpoint order.

#### Q2. What is the first decision rule for treat a file link url as a revocable bearer capability?

Store the public URL at creation because lookup returns policy and lifecycle
metadata but not the URL again. Store the file-link ID separately for lookup
and revocation.

#### Q3. What is the second decision rule for treat a file link url as a revocable bearer capability?

Anyone who obtains the URL can exercise its remaining access. Keep it out of
logs, analytics, referrers, support transcripts, and unrelated model context;
use the narrowest useful expiry, origin, download, and access-count policy.

#### Q4. What is the third decision rule for treat a file link url as a revocable bearer capability?

Revoke the link to stop access without deleting the underlying file. Delete
or replace the file only when the asset lifecycle itself requires it.

#### Q5. What is the fourth decision rule for treat a file link url as a revocable bearer capability?

Open the complete returned URL unchanged. The public open operation is a wire
URL rather than an authenticated SDK resource method, and it works only while
lifecycle and access constraints still permit it.

### Recommended MCP assistance

Use these through an authenticated Inttegro MCP connection. This document remains the contract source.

- [`get_file_link`](https://studio.inttegro.com/machine/typescript/inttegro-mcp/tools.md#get_file_link) — read; no mutation confirmation. Gets lifecycle and access metadata for one file link while withholding its bearer-capability URL.
- [`create_file_link`](https://studio.inttegro.com/machine/typescript/inttegro-mcp/tools.md#create_file_link) — action; exact user confirmation required. Creates an expiring, revocable public bearer capability. Its secret URL is returned only by this creation response.
- [`revoke_file_link`](https://studio.inttegro.com/machine/typescript/inttegro-mcp/tools.md#revoke_file_link) — action; exact user confirmation required. Revokes one file-link capability without deleting the underlying file.

## Document content

# 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.

## Treat a file link URL as a revocable bearer capability

The four decision rules are in the machine preamble above.

## The file link object

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

- [`access`](https://typescript.inttegro.dev/v12.0.0)

  Access limits and usage details for the link.

  - [`access.accessCount`](https://typescript.inttegro.dev/v12.0.0) — `integer`

    Number of successful opens recorded for this link.

  - [`access.allowDownload`](https://typescript.inttegro.dev/v12.0.0) — `boolean`

    Whether attachment-style delivery is allowed.

  - [`access.allowedOrigins`](https://typescript.inttegro.dev/v12.0.0) — `array`

    Optional list of allowed origins.

  - [`access.lastAccessedAt`](https://typescript.inttegro.dev/v12.0.0) — `timestamp`

    When the link was last opened successfully.

  - [`access.maxAccesses`](https://typescript.inttegro.dev/v12.0.0) — `integer`

    Maximum number of successful opens allowed before the link stops working.

- [`active`](https://typescript.inttegro.dev/v12.0.0) — `boolean`

  Whether the link can still be opened.

- [`createdAt`](https://typescript.inttegro.dev/v12.0.0) — `timestamp`

  When the link was created.

- [`createdBy`](https://typescript.inttegro.dev/v12.0.0)

  Actor that created the link.

  - [`createdBy.email`](https://typescript.inttegro.dev/v12.0.0) — `string`

    Actor email when available.

  - [`createdBy.id`](https://typescript.inttegro.dev/v12.0.0) — `string`

    Actor ID when available.

  - [`createdBy.name`](https://typescript.inttegro.dev/v12.0.0) — `string`

    Actor display name when available.

  - [`createdBy.type`](https://typescript.inttegro.dev/v12.0.0) — `string`

    Actor type such as `"api_key"` or `"system"`.

- [`customData`](https://typescript.inttegro.dev/v12.0.0) — `object`

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

- [`delivery`](https://typescript.inttegro.dev/v12.0.0)

  How the file is presented when someone opens the link.

  - [`delivery.contentType`](https://typescript.inttegro.dev/v12.0.0) — `string`

    Optional content type override for the response.

  - [`delivery.disposition`](https://typescript.inttegro.dev/v12.0.0) — `string`

    Response disposition, such as [`Inttegro.FileDispositions.Attachment`](https://typescript.inttegro.dev/v12.0.0/variables/types_files.FileDispositions.html#attachment) or [`Inttegro.FileDispositions.Inline`](https://typescript.inttegro.dev/v12.0.0/variables/types_files.FileDispositions.html#inline).

  - [`delivery.filename`](https://typescript.inttegro.dev/v12.0.0) — `string`

    Filename to present to the downloader.

  - [`delivery.mode`](https://typescript.inttegro.dev/v12.0.0) — `string`

    Delivery mode: [`Inttegro.FileLinkDeliveryModes.Download`](https://typescript.inttegro.dev/v12.0.0/variables/types_files.FileLinkDeliveryModes.html#download), [`Inttegro.FileLinkDeliveryModes.Inline`](https://typescript.inttegro.dev/v12.0.0/variables/types_files.FileLinkDeliveryModes.html#inline), or [`Inttegro.FileLinkDeliveryModes.Redirect`](https://typescript.inttegro.dev/v12.0.0/variables/types_files.FileLinkDeliveryModes.html#redirect).

- [`expiresAt`](https://typescript.inttegro.dev/v12.0.0) — `timestamp`

  When the link stops granting access.

- [`fileId`](https://typescript.inttegro.dev/v12.0.0) — `string`

  File ID the link grants access to.

- [`id`](https://typescript.inttegro.dev/v12.0.0) — `string`

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

- [`kind`](https://typescript.inttegro.dev/v12.0.0) — `string`

  Link kind. Currently [`Inttegro.FileLinkKinds.Public`](https://typescript.inttegro.dev/v12.0.0/variables/types_files.FileLinkKinds.html#public).

- [`metadata`](https://typescript.inttegro.dev/v12.0.0) — `object`

  Read-only information added by Inttegro. Use [`fileLink.customData`](https://typescript.inttegro.dev/v12.0.0) for your own values.

- [`purpose`](https://typescript.inttegro.dev/v12.0.0) — `string`

  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.

- [`revokedAt`](https://typescript.inttegro.dev/v12.0.0) — `timestamp`

  When the link was revoked. Returned only after revocation.

- [`revokedBy`](https://typescript.inttegro.dev/v12.0.0)

  Actor that revoked the link. Present only after revocation.

  - [`revokedBy.email`](https://typescript.inttegro.dev/v12.0.0) — `string`

    Actor email when available.

  - [`revokedBy.id`](https://typescript.inttegro.dev/v12.0.0) — `string`

    Actor ID when available.

  - [`revokedBy.name`](https://typescript.inttegro.dev/v12.0.0) — `string`

    Actor display name when available.

  - [`revokedBy.type`](https://typescript.inttegro.dev/v12.0.0) — `string`

    Actor type such as `"api_key"` or `"system"`.

- [`status`](https://typescript.inttegro.dev/v12.0.0) — `string`

  Link lifecycle status: [`Inttegro.FileLinkStatuses.Active`](https://typescript.inttegro.dev/v12.0.0/variables/types_files.FileLinkStatuses.html#active), [`Inttegro.FileLinkStatuses.Revoked`](https://typescript.inttegro.dev/v12.0.0/variables/types_files.FileLinkStatuses.html#revoked), [`Inttegro.FileLinkStatuses.Expired`](https://typescript.inttegro.dev/v12.0.0/variables/types_files.FileLinkStatuses.html#expired), or [`Inttegro.FileLinkStatuses.Disabled`](https://typescript.inttegro.dev/v12.0.0/variables/types_files.FileLinkStatuses.html#disabled).

- [`updatedAt`](https://typescript.inttegro.dev/v12.0.0) — `timestamp`

  When the link was last updated.

## 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](https://studio.inttegro.com/machine/typescript/api/files.md#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

- `access` — `Access`

  Optional access policy for the link.

  - `access.allowDownload` — `boolean`

    Whether download-style delivery is allowed.

  - `access.allowed_ip_ranges` — `array` — wire-only

    Optional list of allowed CIDR ranges. Enforced when the link is opened but not returned in responses.

  - `access.allowedOrigins` — `string[]`

    Optional list of allowed origins.

  - `access.maxAccesses` — `number`

    Optional maximum successful open count.

- `createdBy` — `Actor`

  Optional actor creating the link. By default, created\_by.type is "api\_key".

  - `createdBy.email` — `string`

    Actor email when available.

  - `createdBy.id` — `string`

    Actor ID when available.

  - `createdBy.name` — `string`

    Actor display name when available.

  - `createdBy.type` — `string`

    Actor type.

- `customData` — `Data`

  Optional string key-value custom data for your own tracking. The encoded object can be at most 25 KiB, and each key can be at most 256 characters.

- `delivery` — `Delivery`

  Optional delivery settings for the link.

  - `delivery.contentType` — `string`

    Optional content type override.

  - `delivery.disposition` — `string`

    Optional disposition override. Use [`Inttegro.FileDispositions.Attachment`](https://typescript.inttegro.dev/v12.0.0/variables/types_files.FileDispositions.html#attachment) or [`Inttegro.FileDispositions.Inline`](https://typescript.inttegro.dev/v12.0.0/variables/types_files.FileDispositions.html#inline).

  - `delivery.filename` — `string`

    Optional filename override.

  - `delivery.mode` — `string`

    Delivery mode: [`Inttegro.FileLinkDeliveryModes.Download`](https://typescript.inttegro.dev/v12.0.0/variables/types_files.FileLinkDeliveryModes.html#download), [`Inttegro.FileLinkDeliveryModes.Inline`](https://typescript.inttegro.dev/v12.0.0/variables/types_files.FileLinkDeliveryModes.html#inline), or [`Inttegro.FileLinkDeliveryModes.Redirect`](https://typescript.inttegro.dev/v12.0.0/variables/types_files.FileLinkDeliveryModes.html#redirect).

- `expiresAt` — `Time`

  Optional RFC 3339 expiry. The default is 24 hours from creation.

- `fileId` — `string` — required

  Linkable file ID to expose.

### Defaults and limits

- Links expire after 24 hours unless you provide a future `expiresAt`.
- Delivery defaults to [`Inttegro.FileLinkDeliveryModes.Download`](https://typescript.inttegro.dev/v12.0.0/variables/types_files.FileLinkDeliveryModes.html#download). Use [`Inttegro.FileLinkDeliveryModes.Inline`](https://typescript.inttegro.dev/v12.0.0/variables/types_files.FileLinkDeliveryModes.html#inline) to display supported media in the browser or [`Inttegro.FileLinkDeliveryModes.Redirect`](https://typescript.inttegro.dev/v12.0.0/variables/types_files.FileLinkDeliveryModes.html#redirect) to send the browser to a short-lived delivery URL.
- `access.maxAccesses` sets the number of successful opens. Omit it or use `0` for no access-count limit.
- An attachment requires `access.allowDownload` set to `true`.
- Allowed origins must contain only a scheme and host. Allowed IP ranges use CIDR notation.

### Response

The response returns the new `FileLinkCreation` and its public [`url`](https://typescript.inttegro.dev/v12.0.0).

**Request — POST /file\_links/create**

```typescript
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"),
})
```

```json
{
  "file_link": {
    "id": "flink_8pQz3LkY6mN2vT9sB4cD1eF0",
    "kind": "public",
    "file_id": "file_4q6YcQk1RzPv2mDa8nFw0sHu",
    "purpose": "product_image",
    "status": "active",
    "active": true,
    "delivery": {
      "mode": "inline",
      "filename": "hero.png",
      "content_type": "image/png",
      "disposition": "inline"
    },
    "access": { "allow_download": true, "max_accesses": 100, "access_count": 0 },
    "created_by": { "type": "api_key" },
    "created_at": "2026-06-05T12:30:00Z",
    "updated_at": "2026-06-05T12:30:00Z",
    "expires_at": "2030-07-06T12:30:00Z"
  },
  "url": "<FILE_LINK_URL>"
}
```

## 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

- `id` — `string` — required

  File-link ID to retrieve.

### Response

The response returns the requested `FileLink`.

**Request — POST /file\_links/lookup**

```typescript
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",
})
```

## 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

- `fileId` — `string`

  Optional file ID filter.

- `pageNumber` — `number`

  Page number to retrieve. Defaults to `1`.

- `pageSize` — `number`

  Requested number of links per page. Defaults to `25` and is capped at `256`.

- `status` — `string`

  Optional status filter: [`Inttegro.FileLinkStatuses.Active`](https://typescript.inttegro.dev/v12.0.0/variables/types_files.FileLinkStatuses.html#active), [`Inttegro.FileLinkStatuses.Revoked`](https://typescript.inttegro.dev/v12.0.0/variables/types_files.FileLinkStatuses.html#revoked), [`Inttegro.FileLinkStatuses.Expired`](https://typescript.inttegro.dev/v12.0.0/variables/types_files.FileLinkStatuses.html#expired), or [`Inttegro.FileLinkStatuses.Disabled`](https://typescript.inttegro.dev/v12.0.0/variables/types_files.FileLinkStatuses.html#disabled).

### 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 [`page.fileLinks`](https://typescript.inttegro.dev/v12.0.0) array.

**Request — POST /file\_links/page**

```typescript
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,
})
```

## 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

- `id` — `string` — required

  File-link ID to revoke.

- `revokedBy` — `Actor`

  Optional actor revoking the link.

  - `revokedBy.email` — `string`

    Actor email when available.

  - `revokedBy.id` — `string`

    Actor ID when available.

  - `revokedBy.name` — `string`

    Actor display name when available.

  - `revokedBy.type` — `string`

    Actor type.

### Response

The response returns the updated `FileLink` with [`fileLink.status`](https://typescript.inttegro.dev/v12.0.0) set to [`Inttegro.FileLinkStatuses.Revoked`](https://typescript.inttegro.dev/v12.0.0/variables/types_files.FileLinkStatuses.html#revoked). The URL stops working immediately.

**Request — POST /file\_links/revoke**

```typescript
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",
})
```

## 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

- `id` — `string` — required

  File-link ID contained in the returned URL.

- `token` — `string` — required

  Access token contained in the returned URL.

### Response

Use the complete URL returned by [Create a file link](https://studio.inttegro.com/machine/typescript/api/file-links.md#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**

```typescript
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',
})
```