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.

Operations

Create a file link
Lookup a file link
Page file links
Revoke a file link
Open a file link

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

accessobjectAccess limits and usage details for the link.Click or tap to expand
- Name
  access_count
  Type
  integer
  Description
  Number of successful opens recorded for this link.
- Name
  allow_download
  Type
  boolean
  Description
  Whether attachment-style delivery is allowed.
- Name
  allowed_origins
  Type
  array
  Description
  Optional list of allowed origins.
- Name
  last_accessed_at
  Type
  timestamp
  Description
  When the link was last opened successfully.
- Name
  max_accesses
  Type
  integer
  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
created_at
Type
timestamp
Description
When the link was created.
created_byobjectActor 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.
custom_dataobjectClick or tap to expand
Optional string key-value custom data attached to the link.
deliveryobjectHow the file is presented when someone opens the link.Click or tap to expand
- Name
  content_type
  Type
  string
  Description
  Optional content type override for the response.
- Name
  disposition
  Type
  string
  Description
  Response disposition, such as attachment or inline.
- Name
  filename
  Type
  string
  Description
  Filename to present to the downloader.
- Name
  mode
  Type
  string
  Description
  Delivery mode: download, inline, or redirect.
Name
expires_at
Type
timestamp
Description
When the link stops granting access.
Name
file_id
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 public.
metadataobjectClick or tap to expand
Read-only information added by Inttegro. Use custom_data 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
revoked_at
Type
timestamp
Description
When the link was revoked. Returned only after revocation.
revoked_byobjectActor 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
string
Description
Link lifecycle status: active, revoked, expired, or disabled.
Name
updated_at
Type
timestamp
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

accessobjectOptional access policy for the link.Click or tap to expand
- Name
  allow_download
  Type
  boolean
  Description
  Whether download-style delivery is allowed.
- Name
  allowed_ip_ranges
  Type
  array
  Description
  Optional list of allowed CIDR ranges. Enforced when the link is opened but not returned in responses.
- Name
  allowed_origins
  Type
  array
  Description
  Optional list of allowed origins.
- Name
  max_accesses
  Type
  integer
  Description
  Optional maximum successful open count.
created_byobjectOptional actor creating the link. Defaults to { "type": "api_key" }.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.
custom_dataobjectClick or tap to expand
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.
deliveryobjectOptional delivery settings for the link.Click or tap to expand
- Name
  content_type
  Type
  string
  Description
  Optional content type override.
- Name
  disposition
  Type
  string
  Description
  Optional disposition override. Use attachment or inline.
- Name
  filename
  Type
  string
  Description
  Optional filename override.
- Name
  mode
  Type
  string
  Description
  Delivery mode: download, inline, or redirect.
Name
expires_at
Type
timestamp
Description
Optional RFC 3339 expiry. The default is 24 hours from creation.
Name
file_id
Type
string
Required
required
Description
Linkable file ID to expose.

Defaults and limits

Links expire after 24 hours unless you provide a future expires_at.
Delivery defaults to download. Use inline to display supported media in the browser or redirect to send the browser to a short-lived delivery URL.
max_accesses sets the number of successful opens. Omit it or use 0 for no access-count limit.
An attachment requires access.allow_download: true.
Allowed origins must contain only a scheme and host. Allowed IP ranges use CIDR notation.

Response

The response returns the new file_link and the public url.

Request

POST/file_links/create

curl https://api.inttegro.com/file_links/create \
  -H "Authorization: Bearer $INTTEGRO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "file_id": "file_4q6YcQk1RzPv2mDa8nFw0sHu",
    "delivery": { "mode": "inline" },
    "access": { "allow_download": true, "max_accesses": 100 },
    "expires_at": "2030-07-06T12:30:00Z"
  }'

SDK versionv8.2.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: "2030-07-06T12:30:00Z",
})

SDK versionv4.4.0

package main

import (
  "context"
  "log"
  "os"

  inttegro "github.com/zebodotdev/inttegro-sdk-go/v4"
)

func main() {
  ctx := context.Background()
  client := inttegro.NewClient(os.Getenv("INTTEGRO_API_KEY"))

  params := inttegro.FileLinkCreateParams{
    FileID: "file_4q6YcQk1RzPv2mDa8nFw0sHu",
    Delivery: inttegro.FileLinkDelivery{
      Mode: "inline",
    },
    Access: inttegro.FileLinkAccess{
      AllowDownload: true,
      MaxAccesses: 100,
    },
    ExpiresAt: "2030-07-06T12:30:00Z",
  }
  fileLink, url, err := client.FileLinks.Create(ctx, params)
  if err != nil {
    log.Fatal(err)
  }
  _ = fileLink
  _ = url
}

SDK versionv6.2.0

import os
import inttegro

client = inttegro.InttegroClient(api_key=os.environ["INTTEGRO_API_KEY"])
result = client.file_links.create(inttegro.file_links.CreateRequest(
  file_id="file_4q6YcQk1RzPv2mDa8nFw0sHu",
  delivery=inttegro.file_links.Delivery(
    mode="inline",
  ),
  access=inttegro.file_links.Access(
    allow_download=True,
    max_accesses=100,
  ),
  expires_at="2030-07-06T12:30:00Z",
))

SDK versionv5.3.0

<?php

use Inttegro\Client;

$client = new Client($_ENV['INTTEGRO_API_KEY']);
$result = $client->fileLinks->create([
  'file_id' => 'file_4q6YcQk1RzPv2mDa8nFw0sHu',
  'delivery' => [
    'mode' => 'inline',
  ],
  'access' => [
    'allow_download' => true,
    'max_accesses' => 100,
  ],
  'expires_at' => '2030-07-06T12:30:00Z',
]);

SDK versionv4.3.0

require "inttegro"

client = Inttegro::Client.new(api_key: ENV.fetch("INTTEGRO_API_KEY"))
result = client.file_links.create(
  file_id: "file_4q6YcQk1RzPv2mDa8nFw0sHu",
  delivery: {
    mode: "inline",
  },
  access: {
    allow_download: true,
    max_accesses: 100,
  },
  expires_at: "2030-07-06T12:30:00Z"
)

SDK versionv5.2.0

import com.inttegro.Client;
import com.inttegro.files.FileLinkCreateParams;
import com.inttegro.files.FileLinkDelivery;
import com.inttegro.files.FileLinkDeliveryMode;
import com.inttegro.files.FileLinkAccess;

public class Example {
  public static void main(String[] args) throws Exception {
    var client = new Client(System.getenv("INTTEGRO_API_KEY"));
    var params = FileLinkCreateParams.builder()
      .fileId("file_4q6YcQk1RzPv2mDa8nFw0sHu")
      .delivery(FileLinkDelivery.builder()
          .mode(FileLinkDeliveryMode.INLINE)
          .build())
      .access(FileLinkAccess.builder()
          .allowDownload(true)
          .maxAccesses(100)
          .build())
      .expiresAt("2030-07-06T12:30:00Z")
      .build();
    var result = client.fileLinks().create(params, null);
  }
}

SDK versionv6.2.0

using Inttegro;

using var inttegro = new InttegroClient(
    Environment.GetEnvironmentVariable("INTTEGRO_API_KEY")!
);
var result = await inttegro.FileLinks.CreateAsync(new {
  file_id = "file_4q6YcQk1RzPv2mDa8nFw0sHu",
  delivery = new {
    mode = "inline",
  },
  access = new {
    allow_download = true,
    max_accesses = 100,
  },
  expires_at = "2030-07-06T12:30:00Z",
});

Response

Object
JSON

SDK versionv8.2.0

Response {
  fileLink: { … },
  url: "<FILE_LINK_URL>",
}

SDK versionv8.2.0

{
  "file_link": { … },
  "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

Name
id
Type
string
Required
required
Description
File-link ID to retrieve.

Response

The response returns the requested file_link.

Request

POST/file_links/lookup

curl https://api.inttegro.com/file_links/lookup \
  -H "Authorization: Bearer $INTTEGRO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"id":"flink_8pQz3LkY6mN2vT9sB4cD1eF0"}'

SDK versionv8.2.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",
})

SDK versionv4.4.0

package main

import (
  "context"
  "log"
  "os"

  inttegro "github.com/zebodotdev/inttegro-sdk-go/v4"
)

func main() {
  ctx := context.Background()
  client := inttegro.NewClient(os.Getenv("INTTEGRO_API_KEY"))

  result, err := client.FileLinks.Lookup(ctx, "flink_8pQz3LkY6mN2vT9sB4cD1eF0")
  if err != nil {
    log.Fatal(err)
  }
  _ = result
}

SDK versionv6.2.0

import os
import inttegro

client = inttegro.InttegroClient(api_key=os.environ["INTTEGRO_API_KEY"])
result = client.file_links.lookup("flink_8pQz3LkY6mN2vT9sB4cD1eF0")

SDK versionv5.3.0

<?php

use Inttegro\Client;

$client = new Client($_ENV['INTTEGRO_API_KEY']);
$result = $client->fileLinks->lookup("flink_8pQz3LkY6mN2vT9sB4cD1eF0");

SDK versionv4.3.0

require "inttegro"

client = Inttegro::Client.new(api_key: ENV.fetch("INTTEGRO_API_KEY"))
result = client.file_links.lookup(id: "flink_8pQz3LkY6mN2vT9sB4cD1eF0")

SDK versionv5.2.0

import com.inttegro.Client;

public class Example {
  public static void main(String[] args) throws Exception {
    var client = new Client(System.getenv("INTTEGRO_API_KEY"));
    var result = client.fileLinks().lookup("flink_8pQz3LkY6mN2vT9sB4cD1eF0");
  }
}

SDK versionv6.2.0

using Inttegro;

using var inttegro = new InttegroClient(
    Environment.GetEnvironmentVariable("INTTEGRO_API_KEY")!
);
var result = await inttegro.FileLinks.LookupAsync("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

Name
file_id
Type
string
Description
Optional file ID filter.
Name
page_number
Type
integer
Description
Page number to retrieve. Defaults to 1.
Name
page_size
Type
integer
Description
Requested number of links per page. Defaults to 25 and is capped at 256.
Name
status
Type
string
Description
Optional status filter: active, revoked, expired, or 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 file_links array.

Request

POST/file_links/page

curl https://api.inttegro.com/file_links/page \
  -H "Authorization: Bearer $INTTEGRO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"file_id":"file_4q6YcQk1RzPv2mDa8nFw0sHu","status":"active","page_number":1,"page_size":25}'

SDK versionv8.2.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,
})

SDK versionv4.4.0

package main

import (
  "context"
  "log"
  "os"

  inttegro "github.com/zebodotdev/inttegro-sdk-go/v4"
)

func main() {
  ctx := context.Background()
  client := inttegro.NewClient(os.Getenv("INTTEGRO_API_KEY"))

  params := inttegro.FileLinkPageParams{
    FileID: "file_4q6YcQk1RzPv2mDa8nFw0sHu",
    Status: "active",
    PageNumber: 1,
    PageSize: 25,
  }
  result, err := client.FileLinks.Page(ctx, params)
  if err != nil {
    log.Fatal(err)
  }
  _ = result
}

SDK versionv6.2.0

import os
import inttegro

client = inttegro.InttegroClient(api_key=os.environ["INTTEGRO_API_KEY"])
result = client.file_links.page(inttegro.file_links.PageRequest(
  file_id="file_4q6YcQk1RzPv2mDa8nFw0sHu",
  status="active",
  page_number=1,
  page_size=25,
))

SDK versionv5.3.0

<?php

use Inttegro\Client;

$client = new Client($_ENV['INTTEGRO_API_KEY']);
$result = $client->fileLinks->page([
  'file_id' => 'file_4q6YcQk1RzPv2mDa8nFw0sHu',
  'status' => 'active',
  'page_number' => 1,
  'page_size' => 25,
]);

SDK versionv4.3.0

require "inttegro"

client = Inttegro::Client.new(api_key: ENV.fetch("INTTEGRO_API_KEY"))
result = client.file_links.page(
  file_id: "file_4q6YcQk1RzPv2mDa8nFw0sHu",
  status: "active",
  page_number: 1,
  page_size: 25
)

SDK versionv5.2.0

import com.inttegro.Client;
import com.inttegro.files.FileLinkPageParams;
import com.inttegro.files.FileLinkStatus;

public class Example {
  public static void main(String[] args) throws Exception {
    var client = new Client(System.getenv("INTTEGRO_API_KEY"));
    var params = FileLinkPageParams.builder()
      .fileId("file_4q6YcQk1RzPv2mDa8nFw0sHu")
      .status(FileLinkStatus.ACTIVE)
      .pageNumber(1)
      .pageSize(25)
      .build();
    var result = client.fileLinks().page(params);
  }
}

SDK versionv6.2.0

using Inttegro;

using var inttegro = new InttegroClient(
    Environment.GetEnvironmentVariable("INTTEGRO_API_KEY")!
);
var result = await inttegro.FileLinks.PageAsync(new {
  file_id = "file_4q6YcQk1RzPv2mDa8nFw0sHu",
  status = "active",
  page_number = 1,
  page_size = 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

Name
id
Type
string
Required
required
Description
File-link ID to revoke.
revoked_byobjectOptional 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 file_link with status set to revoked. The URL stops working immediately.

Request

POST/file_links/revoke

curl https://api.inttegro.com/file_links/revoke \
  -H "Authorization: Bearer $INTTEGRO_API_KEY" \
  -H "Idempotency-Key: revoke-file-link-001" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "flink_8pQz3LkY6mN2vT9sB4cD1eF0",
    "revoked_by": { "type": "user", "id": "usr_support_123" }
  }'

SDK versionv8.2.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",
})

SDK versionv4.4.0

package main

import (
  "context"
  "log"
  "os"

  inttegro "github.com/zebodotdev/inttegro-sdk-go/v4"
)

func main() {
  ctx := context.Background()
  client := inttegro.NewClient(os.Getenv("INTTEGRO_API_KEY"))

  params := inttegro.FileLinkRevokeParams{
    ID: "flink_8pQz3LkY6mN2vT9sB4cD1eF0",
    RevokedBy: inttegro.FileActor{
      Type: "user",
      ID: "usr_support_123",
    },
  }
  result, err := client.FileLinks.Revoke(ctx, params, inttegro.WithIdempotencyKey("revoke-file-link-001"))
  if err != nil {
    log.Fatal(err)
  }
  _ = result
}

SDK versionv6.2.0

import os
import inttegro

client = inttegro.InttegroClient(api_key=os.environ["INTTEGRO_API_KEY"])
result = client.file_links.revoke(inttegro.file_links.RevokeRequest(
  id="flink_8pQz3LkY6mN2vT9sB4cD1eF0",
  revoked_by=inttegro.FileActorInput(
    type="user",
    id="usr_support_123",
  ),
),
    idempotency_key="revoke-file-link-001")

SDK versionv5.3.0

<?php

use Inttegro\Client;

$client = new Client($_ENV['INTTEGRO_API_KEY']);
$result = $client->fileLinks->revoke([
  'id' => 'flink_8pQz3LkY6mN2vT9sB4cD1eF0',
  'revoked_by' => [
    'type' => 'user',
    'id' => 'usr_support_123',
  ],
]);

SDK versionv4.3.0

require "inttegro"

client = Inttegro::Client.new(api_key: ENV.fetch("INTTEGRO_API_KEY"))
result = client.file_links.revoke(
  id: "flink_8pQz3LkY6mN2vT9sB4cD1eF0",
  revoked_by: {
    type: "user",
    id: "usr_support_123",
  },
  idempotency_key: "revoke-file-link-001"
)

SDK versionv5.2.0

import com.inttegro.Client;
import com.inttegro.files.FileLinkRevokeParams;
import com.inttegro.files.Actor;
import com.inttegro.RequestOptions;

public class Example {
  public static void main(String[] args) throws Exception {
    var client = new Client(System.getenv("INTTEGRO_API_KEY"));
    var params = FileLinkRevokeParams.builder()
      .id("flink_8pQz3LkY6mN2vT9sB4cD1eF0")
      .revokedBy(Actor.builder()
          .type("user")
          .id("usr_support_123")
          .build())
      .build();
    var result = client.fileLinks().revoke(params, RequestOptions.withIdempotencyKey("revoke-file-link-001"));
  }
}

SDK versionv6.2.0

using Inttegro;

using var inttegro = new InttegroClient(
    Environment.GetEnvironmentVariable("INTTEGRO_API_KEY")!
);
var result = await inttegro.FileLinks.RevokeAsync(new {
  id = "flink_8pQz3LkY6mN2vT9sB4cD1eF0",
  revoked_by = new {
    type = "user",
    id = "usr_support_123",
  },
}, "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

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.

Request

GET/file_links/open

curl "<FILE_LINK_URL>" \
  --output hero.png

SDK versionv8.2.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',
})

SDK versionv4.4.0

package main

import (
  "context"
  "log"
  "os"

  inttegro "github.com/zebodotdev/inttegro-sdk-go/v4"
)

func main() {
  ctx := context.Background()
  client := inttegro.NewClient(os.Getenv("INTTEGRO_API_KEY"))

  download, err := client.FileLinks.Open(ctx, "<FILE_LINK_URL>")
  if err != nil {
    log.Fatal(err)
  }
  defer download.Close()
}

SDK versionv6.2.0

import os
import inttegro

client = inttegro.InttegroClient(api_key=os.environ["INTTEGRO_API_KEY"])
download = client.file_links.open(
    "<FILE_LINK_URL>",
    save_to="./hero.png",
)

SDK versionv5.3.0

<?php

use Inttegro\Client;

$client = new Client($_ENV['INTTEGRO_API_KEY']);
$download = $client->fileLinks->open(
    '<FILE_LINK_URL>',
    './hero.png'
);

SDK versionv4.3.0

require "inttegro"

client = Inttegro::Client.new(api_key: ENV.fetch("INTTEGRO_API_KEY"))
download = client.file_links.open(
  "<FILE_LINK_URL>",
  save_to: "./hero.png"
)

SDK versionv5.2.0

import com.inttegro.Client;

public class Example {
  public static void main(String[] args) throws Exception {
    var client = new Client(System.getenv("INTTEGRO_API_KEY"));
    var download = client.fileLinks().open("<FILE_LINK_URL>");
    download.saveTo(java.nio.file.Path.of("./hero.png"));
  }
}

SDK versionv6.2.0

using Inttegro;

using var inttegro = new InttegroClient(
    Environment.GetEnvironmentVariable("INTTEGRO_API_KEY")!
);
var download = await inttegro.FileLinks.OpenAsync(
    "<FILE_LINK_URL>",
    "./hero.png"
);

The file link object

Properties​

Create a file link

Request body​

Defaults and limits​

Response​

Request

Response

Lookup a file link

Request body​

Response​

Request

Page file links

Request body​

Response​

Request

Revoke a file link

Request body​

Response​

Request

Open a file link

Query parameters​

Response​

Request

Properties

Request body

Defaults and limits

Response

Request body

Response

Request body

Response

Request body

Response

Query parameters

Response