---
title: "Import file from public URL"
method: POST
path: "/files/remote-upload"
tags: ["Files"]
---

# Import file from public URL

`POST /files/remote-upload`

## Request

- Base URL: `https://api.beecargo.net`
- URL: `https://api.beecargo.net/files/remote-upload`
- Auth: none declared

Same publish fields as direct upload (including openShare / shareShortId). Send Idempotency-Key for safe retries.

## Headers

- `Idempotency-Key` string

## Request body

- RemoteUploadRequest
  - `url` string, uri, required
  - `folderId` string, uuid, nullable
  - `visibility` 'unlisted' | 'public'
  - `direct` boolean: Pro: start download when the /d share opens
  - `retention` 'ttl' | 'forever'
  - `expiresAt` string, date-time: Exact expiry when retention is ttl
  - `ttl` string: Keep-time preset from now, such as 1h, 24h, or 7d
  - `once` boolean: When true, the share can be downloaded only once
  - `maxDownloads` integer: Max downloads (ignored when once is true)
  - `protect` boolean: Create unlock code and private delivery link
  - `handoffMessage` string: Optional delivery-link note
  - `runId` string: Optional pipeline id; list later via GET /files/list?runId=
  - `openShare` boolean: Authenticated: open a growable multi-file Shipment; response shortId is the share link. Use shareShortId on later uploads.
  - `shareShortId` string: Authenticated: attach this upload to an existing growable Shipment from a prior openShare

## Response `200`

Import success

- FileUploadResponse
  - `success` boolean
  - `data` object
    - `id` string
    - `shortCode` string
    - `shareUrl` string, uri
    - `claimToken` string
    - `deletionToken` string

---

[API](https://skmtc.dev/beecargo/apis/beecargo-agent-api.md) · [All operations](https://skmtc.dev/beecargo/apis/beecargo-agent-api/llms.txt) · [OpenAPI document](https://skmtc.dev/beecargo/apis/beecargo-agent-api/revisions/1f3dfd396f6e?raw)