Bulk Import & Export via CSV & JSON

Migrate from Bitly, Rebrandly, or any in-house URL database in minutes. Shaf's bulk import pipeline validates, deduplicates, and inserts thousands of links across Cloudflare D1 and KV with real-time conflict detection.

Bulk Importing Links via CSV

Navigate to the Import Panel

In the Shaf Dashboard, go to Links → click the Import button in the top-right header.

Prepare Your CSV File

Download the template or structure your spreadsheet with the following columns:

1234url,slug,description,tags
https://example.com/product,summer-deal,Summer Promotion,"sale,email"
https://example.com/pricing,pricing-2026,2026 Pricing Plans,"pricing"
https://example.com/blog,blog-main,Main Blog,"content,seo"

Column reference:

url (required) — The full destination URL including protocol.
slug (optional) — Leave blank to auto-generate a random slug.
description (optional) — Internal label visible only in your dashboard.
tags (optional) — Comma-separated list, wrap in quotes if using multiple.

Upload & Preview

Drag and drop your .csv file into the upload zone, or click Browse File. Shaf will parse the file and display a row-by-row field mapping preview with inline validation errors highlighted in red.

Resolve Conflicts

If slugs already exist in your workspace, the preview will flag them. Choose your conflict resolution strategy:

Strategy	Behavior
Skip duplicates	Existing links are preserved; duplicate rows are skipped
Overwrite	Existing links are updated with the CSV row data
Rename	A numeric suffix is appended to the conflicting slug

Start Import

Click Start Import. Progress is shown in real-time. Large files (10,000+ rows) are batched in background jobs — you will receive an email notification upon completion.

Exporting Workspace Data

Open Data Export Settings

Navigate to Settings → Data Export.

Choose Your Format

Best for spreadsheets, Excel analysis, and marketing reporting tools.

Exported columns:

1slug, url, description, tags, created_at, clicks_total, clicks_last_30d

Generate & Download

Click Generate Export. For workspaces with over 50,000 links, a download link is prepared server-side and emailed to your account address within minutes.

Troubleshooting

My import failed with a validation error

Open the error log displayed after the failed import attempt. Each row shows a specific error code:

INVALID_URL — The destination URL is malformed or missing the protocol.
SLUG_RESERVED — The slug conflicts with a system-reserved path.
QUOTA_EXCEEDED — Your plan's link limit was reached mid-import.

Fix the flagged rows in your spreadsheet and re-upload only the corrected rows.

Can I import links with custom routing rules (iOS/Android)?

Yes — add ios_url and android_url columns to your CSV. These map directly to device routing destinations:

12url,slug,ios_url,android_url
https://yourbrand.com/download,app,https://apps.apple.com/...,https://play.google.com/...

How long does a large import take?

Shaf processes approximately 5,000 rows per minute using batched D1 transactions. A 50,000-row import typically completes in 10–15 minutes. You'll receive an email confirmation with a full success/failure summary when complete.