> ## Documentation Index
> Fetch the complete documentation index at: https://docs.erdo.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Download files from a link

> Check public link access, then download files onto a Knowledge record.

Ask Erdo to download files from a link and it uses its `download_files` tool to
keep them on a Knowledge record: logos, fonts, brochures and other files from a
direct file URL or a public Dropbox, Google Drive, SharePoint or OneDrive link.
Anyone-with-the-link shares work without connecting an account. Files can be up
to 50 MiB each.

Create the destination record first, then name it as `record`. You need
edit access to that record in your selected organization. Downloaded attachments
stay private until you explicitly publish or share them.

## Check a link before importing

Use `POST /v1/shared-links/inspect`, the MCP tool `erdo_inspect_shared_link`, or
`erdo files inspect-link <url>` to check a public file or shared-folder link.
Inspection does not import files, create records, or store content. Keep all
sharing parameters in the URL. Only HTTPS URLs without credentials are accepted.

```bash theme={null}
erdo files inspect-link 'https://example.com/brochure.pdf'
```

The REST request is:

```json theme={null}
{ "url": "https://example.com/brochure.pdf" }
```

An accessible file returns:

```json theme={null}
{
  "provider": "web",
  "kind": "file",
  "opens": true,
  "reason": null,
  "file_count": 1,
  "total_bytes": 2048,
  "complete": true,
  "sample": [{ "name": "brochure.pdf", "bytes": 2048 }],
  "checked_at": "2026-11-18T12:00:00Z"
}
```

`provider` is `sharepoint`, `onedrive`, `dropbox`, `google_drive`, or `web`.
`kind` is `file`, `folder`, or `unknown`. `opens: true` means file content or a
structured folder listing was reached without signing in. It does not guarantee
that a later import succeeds, or that every file in a folder is downloadable.

When `opens` is false, `reason` explains the result:

* `sign_in_required`: an authentication endpoint, sign-in form, or HTTP 401/403
  was returned. Ask the owner for an anyone-with-the-link share.
* `not_found`: the server returned HTTP 404 or 410.
* `unsupported`: access could not be established from the response. This is
  inconclusive, including HTML previews that need a browser to inspect.
* `error`: the request failed, timed out, or was blocked by public-URL checks.

Inspection has a 20-second budget, reads only bounded content prefixes, and
returns at most 50 sample files. SharePoint folders use the same guest session
and REST listing as imports, with limits on response size, folder depth and
folder count. `file_count` is null when enumeration is incomplete; `total_bytes`
is null when enumeration or sizes are incomplete. Unknown sample sizes are null.
`complete` is false whenever enumeration is truncated or a size is unknown.

Inspection makes no hosted-browser calls and incurs no paid browser lookup.
Dropbox, Google Drive and personal OneDrive folder previews may therefore return
`unsupported`, even when their owner has shared them publicly. Inspection requires
an authenticated member of the selected organization and supports API keys.

## Run the download

The agent calls `download_files` with:

```json theme={null}
{
  "source_url": "https://www.dropbox.com/scl/fi/example/brochure.pdf?rlkey=example&dl=0",
  "record": "brand-style"
}
```

From the CLI or MCP, send the request to an agent (for example `erdo agent send`) and it calls `download_files` the same way.

Keep all sharing parameters in the original link. SharePoint and OneDrive for
Business links are read directly with the guest access the link grants. Google
Drive file links also use direct downloads. Dropbox, Google Drive and personal
OneDrive folders download inside a hosted browser session. The
download never signs in or changes sharing permissions. A link that requires a
login fails with `denied`; its owner must make it accessible, or replace it with
a public file link.

For a single file, [Knowledge attachment upload](https://docs.erdo.ai/knowledge-attachments.md) accepts
these public file share links through the CLI, REST and MCP as well. Folder URLs
sent to attachment upload return an explanation directing you to this importer.

## Select files and continue

Omit `paths` to download everything. To select specific material, supply exact
relative filenames or folder prefixes ending in `/`, such as
`["logos/", "brochures/facts.pdf"]`. Nested folders are included by default;
set `recursive` to `false` to select root files only.

One call processes up to ten files. If `listing_complete` is false and
`next_cursor` is present, pass it as `cursor` with the same link, record and
filters. If there is no cursor, check the reported failure and retry the
original request. Folder contents can change between calls; start a fresh import
to include files added before an earlier page's cursor.

`listing_complete` describes the folder listing, including files that failed to
download. Check `failures` even when it is true. Each failure has a filename,
source URL and reason: `denied`, `too_large`, `unsupported`, `timeout` or
`unreadable`. Retry failed paths separately after resolving the cause. Exact
replays of the same filename and bytes reuse the existing attachment.

## Read the result

Each imported file includes its filename, media type, byte size, original source
URL, `attachment_id` and `attachment_handle`. A PDF also has an
`extraction_status`:

* `extracted`: `text_handle` is a stored-content handle. An agent reads it with
  `read_document(dataset_slug=text_handle)` or searches it with
  `read_document` with a `query`.
* `unreadable`: the PDF is stored, but readable text was not obtained. This can
  happen with scanned, encrypted or malformed PDFs, or if text storage failed.
* `not_applicable`: the imported file is not a PDF.

The original PDF appears when you read the Knowledge record. Fonts remain
binary attachments; importing a font does not
make it available for use in a published page.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.