# How to Implement URL Imports with Fastio API

Guide to how implement url imports with fast api: With Fastio's API, URL imports pull files straight from external servers into your workspace. No downloading or re-uploading needed on your end. This saves bandwidth and speeds things up, especially for cloud-to-cloud moves. You'll see the complete process here, from API calls to status polling and activity feeds, with ready-to-use code examples.

Source: https://fast.io/resources/implement-url-imports-fastio-api/
Last reviewed: 2026-02-24

## What Are URL Imports?

URL imports let Fastio grab files from any HTTP or HTTPS link and drop them into your workspace or share. The platform takes care of downloading, virus checks, previews, and AI indexing if turned on.

It handles public URLs and ones protected by OAuth, like Google Drive, OneDrive, Box, or Dropbox. Agents get the most out of this since there's no local file handling. Files up to multiple GB work with the Business Trial.

Normally, you'd download to your server first, then upload it. This skips that step, making big transfers or regular pulls quicker and easier.

Helpful references: [Fastio Workspaces](/product/workspaces/), [Fastio Collaboration](/product/collaboration/), and [Fastio AI](/product/ai/).

## What to check before scaling How to implement URL imports with Fastio API

Get a Fastio account first. Fastio offers a 14-day Business Trial (card required; see /pricing/). Create it via the API.

Get your JWT token or API key next. Use the basic auth endpoint: GET /current/user/auth/ with your email and password.

Have your workspace ID ready (multiple-digit number or folder name) and parent node ID ('root' for top-level).

Imports use bandwidth credits at multiple per GB, so check rate limits.

## Initiating a URL Import

Send a POST request to the import endpoint with the source URL and target details.

Example curl:

```
curl -X POST https://api.fast.io/current/storage/workspace/{workspace_id}/import/url/ \
  -H "Authorization: Bearer {jwt_token}" \
  -d "url=https://example.com/file.pdf" \
  -d "parent_node_id=root"
```

The response includes an upload_id for tracking. For shares, replace workspace_id with share_id and add context_type=share.

OAuth sources require authorization first, via UI or token exchange.

## URL Import Lifecycle

1.

**Submit Request**: POST the URL and target. Get upload_id right away.

2.

**Processing Phase**: Server fetches the file, scans for viruses, generates previews, indexes if intelligence is enabled. Status: pending, in_progress.

3.

**Completion Notification**: Poll status or monitor the activity feed. File appears in storage tree with metadata.

Large files (>multiple) always async. Track with GET /current/upload/{upload_id}/details/.

## Async Processing and Event Polling

Poll status directly using the upload details endpoint:

```bash
curl -H "Authorization: Bearer {token}" \
  https://api.fast.io/current/upload/{upload_id}/details/
```

For production applications, monitor the realtime activity feed or connect to the WebSocket events feed to listen for upload completion events.

Status tracking includes upload status, node ID, and processing state.

## OAuth for Cloud Storage

For Drive or Dropbox: Start OAuth with GET /current/oauth/{provider}/authorize/, exchange code for token.

Pass oauth_token in the import request. Fastio handles refresh.

Read-only scopes work for file access.

## Best Practices and Troubleshooting

Batch small URLs, but limit concurrent large ones to stay under rate limits.

Retry 5xx errors with exponential backoff.

Common issues:
- multiple: File too large (>multiple agent limit).
- multiple: Invalid URL or auth.
- Pending forever: Check upload status or network connectivity.

Monitor credits via /org/{org_id}/billing/usage/.

## Frequently asked questions

### How do I upload a file via URL in Fastio?

POST to the URL import endpoint with the source URL and workspace or share ID. Fastio fetches and processes it automatically.

### Does Fastio support cloud-to-cloud file transfers?

Yes, URL imports with OAuth handle transfers from Google Drive, OneDrive, Dropbox, or Box. No local downloads.

### What is the maximum file size for URL imports?

multiple per file on the Business Trial. Paid plans support larger.

### How long do URL imports take?

Seconds for small files, minutes for large files or AI indexing. Poll upload details or monitor the activity feed.

### Can I import multiple URLs at once?

Send separate requests and track by upload_id. No batch endpoint.

## About Fast.io

Fast.io provides shared workspaces where people and AI agents work on the same files, with built-in semantic search and citation-backed chat over what they hold. Agents reach it through a remote MCP server at https://mcp.fast.io/mcp, a REST API at https://api.fast.io/current/, and a command line client published on npm as @vividengine/fastio-cli.