How to Implement URL Imports with Fastio API

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, Fastio Collaboration, and Fastio AI.

Get a Fastio account first. The Business Trial offers multiple GB storage and multiple monthly credits. Create it via the API with agent=true.

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.

Start Importing URLs Today

Business Trial includes 50GB storage and included credits. Built for how implement url imports with fast api workflows.

Start 14-Day Trial

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.

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

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

Completion Notification: Poll status or get webhook. File appears in storage tree with metadata.

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

Poll status:

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

For production apps, set up webhooks. POST to /current/webhooks/ with events=upload.complete and target_url=your_endpoint.

Webhook includes event_type, upload_id, node_id (new file), status.

Verify signature with shared secret. Use idempotent handling to avoid duplicates.

Example Node.js handler:

app.post('/webhook', (req, res) => {
  if (req.body.event_type === 'upload.complete') {
    // Process new file
  }
  res.status(200).send('OK');
});

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.

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 webhook delivery or network.

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